Flows — Catalogue¶
Pointer page. The 15 narrative flow docs all live in
../flows/. Each one is a self-contained walk-through: triggering UI action, HTTP/WS sequence, OTel spans named, code citations, edge cases.
If you only have time for one flow doc, read ../flows/dropbet-bet-place.md — it covers ~80% of the runtime hops a new developer encounters. The runnable counterpart that produces a real Jaeger trace is ../e2e-trace-demo.md.
Document form — when to use which¶
Three narrative shapes describe the same subsystems from different angles. Each shape has one canonical doc; don't redraw a flow sequence in a feature doc, and don't re-state a business rule in a flow doc.
| Shape | Purpose | Lives in | When to use it |
|---|---|---|---|
| Flow | Trace-anchored sequence walk-through. Pinned to a real Jaeger traceID. Mermaid sequence + per-method/span walkthrough + failure modes + unresolved questions. |
../flows/ |
"Show me the wire — what API calls, what spans, what DB ops, what queue jobs happen when X is triggered." |
| Feature | Business-rule / formula reference. Definition → formulas as they appear in source → worked numerical examples → edge cases → admin overrides. | ../features/ |
"What number does the system pay? What's the formula?" |
| Recipe | How-to imperative — "add a thing" with numbered steps + verification commands. | ../recipes/ |
"I need to add an endpoint / OTel span / Prisma model / payment provider." |
A given subsystem (e.g. bet placement) may appear in all three — but the flow doc owns the sequence diagram, the feature doc owns the formulas, the recipe owns the imperative steps. Don't duplicate across shapes; cross-link.
User flows (player on dropbet)¶
| Flow | Doc | Audience hint | Notes |
|---|---|---|---|
| Sign-up (new account) | ../flows/dropbet-sign-up.md |
new dev | Email/password + Steam OAuth + Google OAuth branches |
| Sign-in | ../flows/dropbet-sign-in.md |
new dev | Most-read flow. Cookies, captcha bypass, 2FA branch |
| Password reset | ../flows/dropbet-password-reset.md |
new dev | SendGrid + verification token |
| Place bet (dice) | ../flows/dropbet-bet-place.md |
read first | The flagship flow — POST /casino/games/house/dice/bet end-to-end |
| Bet history | ../flows/dropbet-bet-history.md |
new dev | Pagination, span coverage |
| Wallet (deposit / withdraw) | ../flows/dropbet-wallet.md |
integration partner | NowPayments + CCPayment + SkinDeck branches |
| House game (dice / mines / etc.) | ../flows/dropbet-house-game.md |
new dev | Generic house-game pipeline |
| Blackjack (multiplayer) | ../flows/dropbet-blackjack.md |
careful read | dropbet hits apps/api's house-game endpoint, not the orphaned ebit-bj app on 4002 — see §6.4 |
| Speed roulette | ../flows/dropbet-speed-roulette.md |
careful read | EOS-anchored fairness; three-hop trace gap (see ADR-0005) |
| Challenges | ../flows/dropbet-challenges.md |
promo dev | Daily / weekly / event-based challenge engine |
| Leaderboard | ../flows/dropbet-leaderboard.md |
promo dev | Position view, materialized via LeaderboardUserPositionView |
Admin flows¶
| Flow | Doc | Audience hint | Notes |
|---|---|---|---|
| Admin sign-in | ../flows/admin-sign-in.md |
see known issues | Three stacked bugs prevent successful post-login SSR — see architecture.md §Known debt #4 / project_admin_fe_auth_bugs.md. The flow doc walks the intended behaviour; the bugs are called out in §6 |
| Admin bets review | ../flows/admin-bets.md |
ops dev | GET /admin/bets listing + drill-down |
| Admin user mgmt | ../flows/admin-user-mgmt.md |
ops dev | Block / unblock, role assignment, balance adjust |
System / real-time flows¶
| Flow | Doc | Audience hint | Notes |
|---|---|---|---|
| RT websocket | ../flows/rt-websocket.md |
RT dev | socket.io /events namespace, throttle, auth handshake (cookie-based, not Authorization header) |
System flows that don't have a dedicated doc yet (gaps to backfill — sibling agents may take these on):
- Settlement worker — BullMQ bet-settlement consumer. Currently described inline in
dropbet-bet-place.md§5; could be promoted to its own doc once the orphan-trace fix lands. - Bonus accrual — promo / challenge accrual cron + queues. Currently only described in flow docs that mention it.
- Bot fleet — server-side bots driven by BullMQ producers, separate Redis instance (
:6380, passwordbot). Today only documented in../architecture.md§3 and ADR-0008. - Fast Track sync — RabbitMQ producer is stubbed (
disabled = true); flow doc deferred until it's wired.
How to use this catalogue¶
- Onboarding — read
dropbet-sign-up.mdthendropbet-sign-in.mdthendropbet-bet-place.mdin order. Together they cover ~80% of the hops you'll encounter in a typical user session. - Investigating a bug — find the matching flow doc, follow the span names down into the source citations.
- Writing E2E tests — use the flow's span names as your assertion targets. Each flow doc names the entry-point root span, which is what the trace assertions in
../../tests-e2e/anchor on. - Reviewing trace coverage — cross-reference
../audits/perf-trace-coverage-audit.mdfor the endpoint × span-type matrix; the audit calls out which flows hit the four known blind spots (WS, microservice transport, BullMQ, EvoLogger→Loki).
Format¶
Every flow doc follows roughly the same template:
- Trigger — UI action or external event
- Sequence — Mermaid
sequenceDiagramof HTTP / WS / queue hops - Span walk-through — span-by-span list with
file_path:line_numbercitations - Edge cases — what goes wrong, error responses
- Related — links to E2E tests, security findings, ADRs
When adding a new flow doc, follow that shape. Add a row to the table above and to the index in ../flows/ if/when one is created.