{"id":394,"title":"Data Flow: Westside Basketball","slug":"arch-dataflow-westside-basketball","html_content":"

Data Flow

\n

How information moves through the system at runtime. Answers: what happens when?

\n
sequenceDiagram\n    participant Parent\n    participant Stripe\n    participant API as basketball-api\n    participant DB as Postgres\n    participant Outbox as Outbox Table\n    participant Worker as Outbox Worker\n    participant Email as Gmail SDK\n    participant GM as GroupMe\n    participant Admin as Admin / Cron\n    participant Coach as Coach View\n\n    Note over Parent,Coach: Registration Flow\n    Parent->>Stripe: Pay $30 (QR code or link)\n    Stripe->>API: checkout.session.completed\n    API->>DB: Create Parent + Player + Registration (paid)\n    API->>Email: Send confirmation email with token link\n    Email->>Parent: \"Complete your registration\"\n\n    Note over Parent,Coach: Waiver Flow\n    Parent->>API: GET /register?token=xxx\n    API->>Parent: Registration form (pre-filled)\n    Parent->>API: POST /register (waiver + details)\n    API->>DB: Update parent.waiver_signed, player details\n\n    Note over Parent,Coach: Team Placement Flow\n    Admin->>API: POST /api/teams/{id}/players (assign player)\n    API->>DB: Set player.team_id\n\n    Note over Parent,Coach: Contract Signing → Outbox → Welcome Email\n    Parent->>API: POST /api/players/{id}/contract (sign)\n    API->>DB: SET contract_status='signed' (same transaction)\n    API->>Outbox: INSERT event_type='contract_signed' status='pending' (same transaction)\n    API->>Parent: 200 OK (contract recorded)\n\n    Note over Admin,Email: Outbox Worker (cron every 30s or admin trigger)\n    Admin->>API: POST /api/admin/process-outbox\n    API->>Outbox: SELECT * WHERE status='pending'\n    Outbox->>Worker: pending events\n    Worker->>DB: Lookup team.groupme_share_url + parent.email\n    Worker->>Email: Send welcome email with GroupMe share link\n    Email->>Parent: \"Welcome to [team]! Join our GroupMe: [link]\"\n    Worker->>Outbox: UPDATE status='processed'\n    Parent->>GM: Clicks share link → self-joins team group\n\n    Note over Parent,Coach: Tryout Day Flow\n    Admin->>API: GET /api/roster/{tenant}\n    API->>DB: Query players + parents + registrations\n    DB->>API: Player roster with status\n    API->>Admin: JSON roster\n
\n

Key flows

\n\n

Known bug (2026-03-13)

\n

The registration form looks up parents by email (line 796 of register.py). If a parent uses a different email than Stripe checkout, a new parent record is created. The waiver lands on the new parent, not the paid one. Fix: match by token, not email.

\n

Related

\n","is_public":true,"note_type":"architecture","status":null,"parent_slug":null,"position":null,"created_by_sub":null,"created_by_name":null,"updated_by_sub":null,"updated_by_name":null,"project":{"id":5,"name":"Westside Basketball","slug":"westside-basketball","platform":"github","repo_url":"https://github.com/ldraney/west-side-basketball","is_public":true,"page_note":null,"created_at":"2026-02-26T02:00:39","updated_at":"2026-03-15T18:39:02.426531"},"tags":[{"id":1,"name":"architecture"}],"created_at":"2026-03-14T03:59:35.033246","updated_at":"2026-03-24T07:58:50.134077"}