📄 Software Design Document: Application Flows

Main Flows

1. Account Creation
   1. Client → API → Controller → Service → DB
   2. Returns new virtual account with zero balance
2. Deposit/Withdrawal
   1. Locks account → Creates dual entries → Updates balance
   2. Atomic operation with rollback on failure
3. Transfer
   1. Locks both accounts → Dual entries → Balance updates
   2. All-or-nothing semantics
4. Reversal
   1. Finds original txn → Creates inverse entry → Adjusts balance
   2. Maintains audit trail
5. Balance Check
   1. Reads current balance (no lock needed)
   2. Optional: Cache frequent queries

KYC Design Document

Overview

This document outlines the design for the Know Your Customer (KYC). KYC is essential for compliance with financial regulations, fraud prevention, and user trust. The process will be modular, scalable, and adaptable to both local and international compliance standards.

Goals

• Ensure regulatory compliance (e.g., AML, CDD, GDPR)
• Provide a smooth and secure user experience
• Allow for automated and manual review flows
• Integrate with third-party verification providers

KYC Workflow

sequenceDiagram
    participant User
    participant Frontend
    participant Backend
    participant KYC_Provider(Jumio/Onfido)
    participant AML_Provider(Socure/LexisNexis)
    participant Bank_Provider(Plaid)

    Note over User,Frontend: 1. Registration
    User->>Frontend: Enters email/phone
    Frontend->>Backend: Submit credentials
    Backend-->>Frontend: Send OTP
    User->>Frontend: Inputs OTP
    Frontend->>Backend: Verify OTP
    Backend-->>Frontend: "OTP valid"

    Note over User,Frontend: 2. Profile Setup
    User->>Frontend: Inputs name, DOB, address, SSN
    Frontend->>Backend: Submit profile data
    Backend->>AML_Provider: Validate SSN/address
    AML_Provider-->>Backend: Risk score + fraud flags
    alt SSN valid & low risk
        Backend-->>Frontend: "Profile approved"
    else SSN issue
        Backend-->>Frontend: "Reject: SSN mismatch"
    end

    Note over User,Frontend: 3. ID Verification
    User->>Frontend: Uploads ID + selfie
    Frontend->>KYC_Provider: Send ID/selfie
    KYC_Provider-->>Backend: Liveness result + ID match
    alt ID valid
        Backend-->>Frontend: "ID verified"
    else ID rejected
        Backend-->>Frontend: "Reject: ID expired"
    end

    Note over User,Frontend: 4. Suitability Quiz
    User->>Frontend: Answers income/experience
    Frontend->>Backend: Submit responses
    Backend-->>Frontend: Set trading limits

    Note over User,Frontend: 5. Bank Linking
    User->>Frontend: Selects bank (Plaid/micro-deposits)
    Frontend->>Bank_Provider: Initiate auth
    Bank_Provider-->>Backend: Account ownership
    alt Account valid
        Backend-->>Frontend: "Bank linked"
    else Name mismatch
        Backend-->>Frontend: "Reject: bank account"
    end

    Note over Backend: 6. Final Approval
    Backend->>AML_Provider: OFAC/PEP screening
    alt Clean record
        Backend-->>Frontend: "Account approved"
        Backend->>User: Email confirmation
    else High risk
        Backend->>Backend: Manual review (24-72h)
    end

Hold "Alt" / "Option" to enable pan & zoom

This flow balances user experience (fast onboarding) with compliance (SEC/FINRA/AML rules).

Transaction Funding Design

Overview

TODO

Goals

• TODO

KYC Workflow

sequenceDiagram
    participant User
    participant App
    participant Backend
    participant Fineract(Wallet)
    participant Broker(Alpaca/DriveWealth)
    participant ACH_Provider(Plaid)
    participant Card_Provider(Stripe/Processor)
    participant Virtual_Bank(Evolve/Stripe)

    Note over User,App: 1. Funding Method Selection
    User->>App: Clicks "Add Funds"
    App->>Backend: Request options
    Backend-->>App: Show: Virtual ACH, Card, Wallet, Bank Transfer

    alt Option 1: Virtual Account Deposit
        User->>App: Selects "Deposit to Virtual Account"
        App->>Fineract: Get virtual account details
        Fineract->>Virtual_Bank: Fetch account/routing
        Virtual_Bank-->>App: Display (e.g., "Acct: XXXX")
        User->>Bank: Initiates external transfer
        Virtual_Bank->>Fineract: Webhook on receipt
        Fineract->>Broker: Transfer to brokerage

    else Option 2: Card Deposit (Instant)
        User->>App: Enters card details
        App->>Card_Provider: Tokenize card
        Card_Provider->>Backend: Auth request ($1.00 hold)
        Backend->>Broker: Reserve buying power
        Broker-->>User: Instant trading access
        Card_Provider->>Bank: Settle in 2-3 days

    else Option 3: Wallet Balance
        User->>App: Selects "Use Wallet Funds"
        App->>Fineract: Check balance
        alt Sufficient balance
            Fineract->>Broker: Transfer funds
            Broker-->>User: Immediate availability
        else Insufficient
            App-->>User: "Top up wallet first"
        end

    else Option 4: Bank Transfer (ACH/Wire)
        User->>App: Selects "Link Bank Account"
        App->>ACH_Provider: Launch Plaid
        ACH_Provider->>User: Bank login
        alt Instant Verification
            ACH_Provider-->>Broker: Direct deposit setup
            Broker-->>User: Funds in 1-3 days
        else Micro-Deposits
            ACH_Provider->>Bank: Send $0.01-$0.99
            User->>App: Confirm amounts
            App->>Broker: Complete linkage
        end
    end

    Note over Backend,Broker: Post-Funding Sync
    Broker->>Fineract: Update ledger
    Fineract->>User: Email receipt

Hold "Alt" / "Option" to enable pan & zoom