Repository navigation
docs: bring the architecture diagrams up to date with live video - #247
Merged
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What was wrong
The prose in
ARCHITECTURE.mdalready 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
host.docker.internal— there is nodbservice todepends_on. Adds the two published LiveKit media ports and the Compose profile gating the video tierThe 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
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.Checked, not assumed
The join-code race condition is still real —
generateAccessCodeControllerdoes 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-cliin this environment to render them, so please confirm all 5 blocks render on the PR diff page before merging.No code changes — docs only.