Skip to content

Architecture diagrams

Top-level Mermaid map of the Evospin local stack: which services exist, what they talk to, where OTel telemetry flows, and where tracing is blind.

Generated 2026-04-25. These diagrams describe the local docker-compose.yml topology — the GitLab-deployed staging/prod hosts run the same binaries with different envs but the same edges.

Documents in this folder

Doc Scope Diagram type
service-map.md All five NestJS apps + 2 Next.js FEs + Postgres + 2 Redis + RabbitMQ. Solid = active edge, dashed = stubbed, red label = trace-propagation gap. graph LR
tracing-flow.md OTLP path from each instrumented process through the OTel Collector, fanning out to Jaeger / Prometheus / Loki. Includes spanmetrics + filelog narrative. flowchart TD
request-flow-bet-place.md Flagship e2e demo — User → ebit-fe → ebit-api → Postgres → BullMQ → ebit-rt → User, with span names per hop. sequenceDiagram
request-flow-signin.md Sign-in path — Browser → ebit-api POST /auth/sign-in → bcrypt → Postgres → Redis session → cookies. sequenceDiagram

Cross-references

  • ../architecture.md — master architecture reference (C4 L1/L2/L3, written longhand). The diagrams in this folder are the runtime-topology view; that doc is the conceptual view. Read this folder first if you want to know "what container talks to what container", and that doc first if you want to know "what does the system do".
  • ../flows/ — 15 narrative flow docs (dropbet-bet-place.md, dropbet-sign-in.md, rt-websocket.md, dropbet-sign-up.md, dropbet-wallet.md, dropbet-house-game.md, dropbet-leaderboard.md, dropbet-challenges.md, dropbet-blackjack.md, dropbet-speed-roulette.md, dropbet-bet-history.md, dropbet-password-reset.md, admin-sign-in.md, admin-bets.md, admin-user-mgmt.md). Each one has a per-flow sequenceDiagram plus span-by-span walkthrough — the diagrams here link to them rather than duplicate.
  • ../api-reference/openapi/ — api.openapi.json (4000) and bo.openapi.json (4003). Use these to look up exact request/response shapes for the endpoints called out in the request-flow diagrams.
  • ../e2e-trace-demo.md — sibling agent's deliverable; the runnable counterpart to request-flow-bet-place.md (paste the trace ID into Jaeger and you should see the spans this doc names).
  • ../audits/perf-trace-coverage-audit.md — endpoint × span-type matrix. Read this alongside tracing-flow.md to understand the blind-spot list.
  • ../observability.md — operator-facing ops runbook for the same OTel pipeline tracing-flow.md diagrams (config files, validation curls, sharp edges).

How to use these diagrams

  • Onboarding — read service-map.md first, then request-flow-signin.md, then request-flow-bet-place.md. The two request-flow docs together cover ~80% of the runtime hops a new developer will encounter.
  • Debugging a missing trace — tracing-flow.md shows where the OTLP packet gets lost. The "Trace blind spots" section names the four known gaps (WS, ExternalControllerClient RPC, BullMQ propagation, EvoLogger→Loki).
  • Capacity planning / incident review — service-map.md's edge table calls out which port-pairs need to be fast (HTTP), which can buffer (Redis pub/sub), and which are intentionally fire-and-forget (the FastTrack RabbitMQ stub).

Validation

find docs/architecture -name '*.md' | wc -l   # should be 5
grep -c '```mermaid' docs/architecture/*.md   # should equal expected diagram count