Code walkthrough — every file explained
Code walkthrough — every file explained
Plain-language documentation for every file in this project. Each page covers one source file and explains the code line by line.
If you are reading this to prepare for an interview, read them in this order. The first four are where the interesting decisions live.
Read these first
| # | File | What it does |
|---|---|---|
| 1 | domain/GameRoom.md | The heart of the project. One lobby: players, movement, collisions, scoring, the leaderboard. |
| 2 | domain/GameManager.md | Holds all the lobbies and decides which one you join. |
| 3 | loop/GameLoop.md | The heartbeat — wakes 20 times a second and drives every lobby. |
| 4 | realtime/socketServer.md | Talks to browsers over WebSocket. |
The rest of the server
| File | What it does |
|---|---|
| domain/types.md | The shapes of all the data. No logic, just definitions. |
| domain/rng.md | Repeatable random numbers, so tests can replay a board. |
| config/gameConfig.md | Every tunable number in one place. |
| realtime/validation.md | Checks messages from browsers before trusting them. |
| realtime/rateLimiter.md | Stops one player flooding the server. |
| persistence/GameRepository.md | The saving contract, plus a fake for tests. |
| persistence/PrismaGameRepository.md | The real PostgreSQL saving. |
| persistence/PersistenceSubscriber.md | Listens for "game over" and queues a save. |
| persistence/WriteQueue.md | Stops 100 saves at once from crushing the database. |
| http/app.md | The plain web pages and JSON endpoints. |
| server.md | Wires every piece together. |
| entrypoint.md | index.ts — starts the process and picks a database. |
Frontend, database and tests
| File | What it does |
|---|---|
| frontend.md | public/index.html — the browser game. |
| database-schema.md | prisma/schema.prisma — the three tables. |
| tests/unit-tests.md | The 53 tests that need no network or database. |
| tests/integration-tests.md | The 17 tests over real WebSockets. |
| loadtest/stress.md | The 2,000-player stress test. |
| loadtest/worker.md | The fake players it drives. |
| loadtest/smoke.md | Plays one full game end to end. |
| project-setup.md | package.json, tsconfig.json, docker-compose.yml, .env. |
How to read a page
Every page has the same four parts:
- In one sentence — what the file is for.
- Why this file exists — the decision behind it.
- The code, line by line — small blocks of code, each followed by an explanation of what every line does.
- If an interviewer asks — the short answer to say out loud.
The one-paragraph summary of the whole project
Players join a lobby and race to collect items. The server decides everything — the browser only says which direction a key is pressed. Twenty times a second the server moves everyone, checks who touched an item, awards points, and sends the new picture to every player in that lobby. Live state lives in memory because it changes too fast for a database; PostgreSQL is written once, when a game ends.
