[bashmohandes]

Motivation

• Provide a compact, diagram-first description of the system topology, browser and server subsystems (accounts, achievements, results, room managers), and deployment boundaries so new contributors can understand runtime responsibilities at a glance.
• Record the rationale behind key design choices in short ADRs to preserve trade-offs and make future changes easier to evaluate.

Description

• Add a new docs/ hub with architecture.md that maps the browser shell, Node process, room managers, SQLite persistence and deployment topology using multiple mermaid diagrams and sequence/ER views.
• Add docs/adr/ with seven concise ADR files (0001–0007) documenting decisions about the build-free client, SQLite migrations, server-side scoring and achievements, authoritative ephemeral rooms, session boundaries, preserving classic games, and same-origin security, plus an adr/README.md index.
• Add docs/README.md that points to the architecture map and ADR index so the documentation is discoverable from the repo root.
• Files created: docs/README.md, docs/architecture.md, and docs/adr/0001-* through 0007-* and docs/adr/README.md.

Testing

• Ran npm test (the repository test suite via node --test) and all tests completed successfully.
• Ran repository checks including git diff --check with no issues reported.
• Ran an automated Markdown/link check which reported relative Markdown links OK and counted 14 mermaid diagrams in the new docs.

---

Codex Task

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4c26e306d8

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Document the actual Battle Tanks snapshot cadence

The Battle Tanks server simulates at 60 Hz, but it does not deliver snapshots at that rate: server/battle-tanks-rooms.js gates broadcastStates() on at least 40 ms since the previous broadcast, so state delivery is capped at 25 Hz and is typically lower when sampled by the 60 Hz timer in server/index.js. This table gives incorrect expectations for client interpolation and bandwidth planning; either document the throttled delivery cadence or change the broadcaster if 60 Hz snapshots are intended.

Useful? React with 👍 / 👎.