Skip to main content

Integration Handoff

The contributor portal is the front door for contributor identity and pre-recorder compliance. Downstream systems should consume only explicit portal outputs and should not infer readiness from loose UI state.

Playroll App Identity Bridge​

The canonical bridge between the Playroll app user and the contributor portal contributor is explicit and activation-gated:

playroll_supa_new.playroll_users.user_id
  <-> playroll_contributor_portal.contributors.id

Source of truth:

playroll_contributor_portal.public.contributor_app_links

App read model:

playroll_supa_new.public.contributor_status_projection

The Playroll app starts the flow by calling:

playroll_supa_new.functions.create-contributor-link-intent

The portal completes the flow by calling:

playroll_contributor_portal.functions.activate-contributor-app-link

Activation is allowed only after:

accepted_documents.incarico = true
accepted_documents.privacy = true
accepted_documents.compensation = true
accepted_documents.isee_notice = true
payout_receiving_methods.method_type = sepa_iban
payout_receiving_methods.status = confirmed
payout_receiving_methods.email_confirmation_status = confirmed

Integration rules:

  • do not use email as the Playroll app/portal bridge
  • do not let the app activate a contributor directly
  • do not treat manual_review as sufficient for automatic activation
  • do not copy legal/payment PII to playroll_supa_new
  • do not compute rewards or payable money from this link alone
  • app UI can treat an existing projection row as contributor verification

Recorder Access​

Recorder access should key off the verified email and completion evidence, not a free-form name or contact handle.

Required source data:

public.onboarding_submissions.auth_user_id
public.onboarding_submissions.email
public.onboarding_submissions.accepted_documents
public.onboarding_submissions.document_acceptance_evidence
public.onboarding_submissions.metadata.recorder_access.status

Minimum recorder gate:

accepted_documents.incarico = true
accepted_documents.privacy = true
accepted_documents.compensation = true
accepted_documents.isee_notice = true
verified email present

The current metadata status after successful onboarding is:

documents_completed

Validation Pipeline​

Session validation should write to:

public.session_validation_results

Only this semaphore should unlock validated time:

status = validated

Expected validation payload:

session_id
contributor_id
validation_version
gross_seconds
valid_seconds
invalid_seconds
valid_ratio
rewardable_seconds
result_sha256

Do not create payable money directly from validation output. payable_eur is deprecated.

PlayRoll Time​

Validated sessions create internal PlayRoll time credit:

public.playroll_time_ledger

The ledger is the source of truth for time currency. It is not money.

Required link fields:

contributor_id
session_id
validation_result_id
entry_type = validated_time
seconds_delta
status
source
external_reference
earned_at

Milestones And Rewards​

Milestones convert available time into reward unlocks:

public.reward_milestones
public.contributor_milestone_unlocks

Only a milestone unlock should create a value item:

public.compensation_items

Value items must track every value class, not only bank transfers:

cash
steam_key or software_key
voucher
prepaid_card
referral_bonus
manual_adjustment

Each compensation item should include:

contributor_id
item_type
eur_value
source_session_id
earned_at
paid_at
included_in_cap
receipt_id
validation_result_id
milestone_unlock_id
status

Payout Integration​

The contributor portal currently exports confirmed or manual-review receiving methods through:

public.confirmed_payout_receiving_methods

Automatic money transfer should require:

method_type = sepa_iban
status = confirmed
email_confirmation_status = confirmed

Manual review cases require an operator-approved alternative outside this repo.

The payment system, not the browser portal, should own:

  • payout request creation
  • cap checks at request and approval time
  • provider recipient creation or verification
  • founder approval
  • payment batch submission
  • provider failure handling
  • receipts and value sheets
  • audit events

Reward Balance Display​

The reward workspace is currently static zero-state UI. A future integration should read from:

public.contributor_playroll_time_balances
public.contributor_milestone_progress
public.contributor_reward_balances

Suggested display fields:

pending_seconds
available_seconds
available_hours
milestone credited_seconds
milestone remaining_seconds
in_validation_eur
available_eur
queued_eur
paid_eur
rolling_12mo_cap_used_eur
cap_remaining_eur

Admin Surface​

An internal admin/review surface is not present in this repo. If built, keep it separate from the public contributor flow and gate it to EC team identities.

Expected admin queues:

  • contributor compliance queue
  • session validation queue
  • payment queue
  • failed payments queue
  • cap monitor
  • document/version dashboard
  • manual review queue
  • audit log

Use service-role credentials only in backend or Edge Function contexts. Never place admin operations in browser code.