Domain: payouts

Curated entry point for the payouts bounded context.

Owner

Founder + agents (Phase 1).

Mission

Owns money flowing out to traders: payout-eligibility checks, Plaid bank-account linking, payout requests, the 90/10 profit split per docs/PRD/02-business-model.md, payout processing, payout-batch operations, and tax form generation (1099 / W-8BEN). Boundary: payouts owns the cash-out side; eligibility thresholds are owned here, but eligibility based on rule compliance (e.g., consistency rule passed) is computed by risk-engine and consumed via events.

Code paths

• Application code: apps/api/src/modules/payouts/
• Domain logic (pure): packages/domain/payouts/
• Contracts: packages/contracts/api/payouts.ts, packages/contracts/events/payouts.ts
• External clients: packages/clients/plaid/
• Database schemas owned: payouts (PayoutRequest, BankLink, PayoutTransfer, PayoutBatch, TaxForm, PlaidWebhookEvent)

PRD chapters that touch this domain

• 07-payout-pipeline.md - canonical payout-flow design
• 02-business-model.md - 90/10 split, payout SLA targets
• 08-live-transition.md - Edge Live payout differences
• 13-compliance-legal.md - re-KYC requirement before payout, 1099 obligation
• 16-open-questions.md - Q-I2 (Mercury + Brex banking)

TDD chapters

(Empty - will populate as TDDs arrive.)

ADRs that affected this domain

• ADR-0001 (transversally applies)

Service interfaces this domain exposes

export interface PayoutsService {
  // linkBankAccount(userId, plaidPublicToken): Promise<BankLink>
  // requestPayout(accountId, amount): Promise<PayoutRequest>
  // approvePayout(requestId, adminId): Promise<PayoutRequest>
  // processPayoutBatch(batchId): Promise<PayoutBatch>
  // generateTaxForm(userId, year): Promise<TaxForm>
  // (full surface defined during payouts TDD)
}

Events this domain produces / consumes

Direction	Topic	Triggered by
produces	payouts.request.submitted	Trader requests a payout
produces	payouts.request.approved	Admin approves (or auto-approve passes)
produces	payouts.transfer.completed	ACH transfer settled
produces	payouts.transfer.failed	Bank reject / NSF / reversal
produces	payouts.tax_form.generated	Annual 1099 / W-8BEN ready
consumes	accounts.account.eod_snapshot_taken	Refresh payout-eligible balance
consumes	risk.evaluation.consistency_passed	Eligibility flag
consumes	onboarding.kyc.cleared	Pre-payout re-KYC

External integrations

• Plaid - bank linking, ACH-fast payouts (per docs/PRD/10-integrations.md)
• Mercury / Brex Treasury - banking partners (per Q-I2)
• Stripe Tax / 1099-NEC API - tax form generation

Runbooks for this domain

(Empty - will populate when alerts are defined in Section 17.6.)

On-call

To be filled in Section 17.6. Likely tight with Risk Officer and finance owner.

Cross-domain dependencies

• This domain calls: identity, accounts, onboarding (re-KYC check).
• This domain emits events consumed by: accounts (ledger debit), audit (every payout event - regulated), notifications (payout-status emails), admin (payout queue UI).