Skip to content

docs: bring the architecture diagrams up to date with live video - #247

Merged
TheCodeHeist-Coder merged 2 commits into
mainfrom
docs/architecture-v3
Nov 22, 2026
Merged

TheCodeHeist-Coder merged 2 commits into
mainfrom
docs/architecture-v3

Conversation

@TheCodeHeist-Coder

Copy link
Copy Markdown
Owner

What was wrong

The prose in ARCHITECTURE.md already described the streaming service, but every diagram still showed the v2 system: no streaming, no LiveKit, no nginx, no admin plane. Anyone reading the diagrams — which is most people — came away with the wrong shape of the system.

Three diagrams also asserted things the code contradicts.

What changed

Diagrams redrawn in Mermaid, which GitHub renders natively and which survives a new service being added far better than hand-aligned ASCII boxes. The ASCII sequence flows are kept — they read well and don't rot the same way.

Diagrams now matching reality

Diagram Was Now
System overview 4 services, no edge Adds streaming + LiveKit as an optional tier, nginx at the edge, and the admin plane
Deployment topology Postgres/Redis as Docker services with volumes They run on the host via apt, reached through host.docker.internal — there is no db service to depends_on. Adds the two published LiveKit media ports and the Compose profile gating the video tier
README architecture ASCII, v2 only Mermaid, all five services
(new) Flow 4 — Running a quiz on camera

The overview makes one thing explicit that drives most of the live-video deployment steps: WebRTC media bypasses nginx entirely. It cannot be reverse-proxied, so the browser talks to LiveKit directly on 7881/7882 while everything else terminates at nginx.

Factual corrections

  • Flow 3 scoring showed max(10, 1000-ms) — the formula from before points were scaled across the time limit. It contradicted the correct formula given earlier in the same file.
  • Flow 3 persistence showed each answer written straight to Postgres. Answers have been buffered and flushed in batches (250ms / 200 answers) since the 750-user load test.
  • Known limitations claimed no automated test suite and no mid-quiz reconnection. There are 29 test files across five services running in CI, and reconnection restores the live question from the Redis deadline.

Checked, not assumed

The join-code race condition is still real — generateAccessCodeController does check-then-write with no transaction — so that limitation stays in the table.

Review notes

Mermaid syntax was verified by hand (fence balance, label escaping, arrow forms); I could not install mermaid-cli in this environment to render them, so please confirm all 5 blocks render on the PR diff page before merging.

No code changes — docs only.

The prose already described the streaming service, but every diagram still
showed the v2 system: no streaming, no LiveKit, no nginx, no admin plane.
Someone reading the diagrams came away with the wrong shape of the system.

Redrawn in Mermaid, which GitHub renders natively and which survives a new
service being added far better than hand-aligned ASCII boxes:

- System overview now carries streaming and LiveKit as an optional tier, and
  shows WebRTC media bypassing nginx entirely. That one fact drives most of
  the live-video deployment steps, so it belongs in the picture.
- Deployment topology showed Postgres and Redis as Docker services with
  volumes. They run on the host via apt and are reached through
  host.docker.internal; there is no db service to depend_on. Also adds the
  two published LiveKit media ports and the Compose profile that gates the
  whole video tier.
- New Flow 4 for a quiz on camera, covering why a player's own id proves
  nothing (ids are public; only the signed token counts) and why rooms
  outlive the quiz.
- Added the admin plane, which is deployed to Render/Vercel outside Docker
  and CI/CD, so its absence from the main diagram was not obvious.

Fixed three things the diagrams asserted that the code contradicts:

- Flow 3 showed scoring as max(10, 1000-ms), the formula from before points
  were scaled across the time limit, contradicting the correct formula given
  earlier in the same file.
- Flow 3 wrote each answer straight to Postgres. Answers have been buffered
  and flushed in batches since the 750-user load test.
- Known limitations claimed no automated tests and no mid-quiz reconnection.
  There are 29 test files across five services running in CI, and
  reconnection restores the live question from the Redis deadline.

Verified against the code rather than assumed: the join-code race is still
real (check-then-write with no transaction), so that limitation stays.
@TheCodeHeist-Coder
TheCodeHeist-Coder merged commit e66394e into main Nov 22, 2026
10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant