Domain: onboarding

Curated entry point for the onboarding bounded context.

Owner

Founder + agents (Phase 1).

Mission

Owns the new-user onboarding flow from KYC document collection through OFAC / sanctions screening to first-account-eligible state. Boundary: onboarding produces a KYC-cleared user; the accounts domain takes over from there to provision the actual evaluation or instant-funded account.

Code paths

• Application code: apps/api/src/modules/onboarding/
• Domain logic (pure): packages/domain/onboarding/
• Contracts: packages/contracts/api/onboarding.ts
• External clients: packages/clients/persona/
• Database schemas owned: onboarding (KycSubmission, KycDocument, SanctionsScreening, OnboardingFlow)

PRD chapters that touch this domain

• 13-compliance-legal.md - KYC / AML posture, OFAC obligations
• 05-commerce-purchase.md - signup-to-purchase flow
• 07-payout-pipeline.md - re-KYC trigger before first payout
• 16-open-questions.md - Q-I1 (KYC vendor recommendation: Persona)

TDD chapters

(Empty - will populate as TDDs arrive.)

ADRs that affected this domain

• ADR-0001 (transversally applies)

Service interfaces this domain exposes

export interface OnboardingService {
  // initiateKyc(userId: string): Promise<KycInquiryId>
  // handlePersonaWebhook(payload: PersonaWebhookPayload): Promise<void>
  // getKycStatus(userId: string): Promise<KycStatus>
  // runSanctionsScreening(userId: string): Promise<ScreeningResult>
  // (full surface defined during onboarding TDD)
}

Events this domain produces / consumes

Direction	Topic	Triggered by
produces	onboarding.kyc.submitted	User submits KYC docs to Persona
produces	onboarding.kyc.cleared	Persona returns approved + sanctions-clean
produces	onboarding.kyc.flagged	Persona returns suspect or sanctions hit
produces	onboarding.kyc.rejected	Persona returns rejected after manual review
consumes	identity.user.signed_up	Triggers KYC initiation eligibility

External integrations

• Persona - identity verification + sanctions screening (per Q-I1)
• OFAC SDN list - via Persona's screening, fall-through to direct API if needed

Runbooks for this domain

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

On-call

To be filled in Section 17.6.

Cross-domain dependencies

• This domain calls: identity (to read user state).
• This domain emits events consumed by: accounts (user becomes eligible for accounts), audit (every KYC outcome is logged), notifications (KYC-status emails to the user), admin (manual review queue surfaces in the admin app).