How listenrwt/fill-in-the-math-server works
Project type and purpose
• This is the backend server for “Fill in the Math,” a real-time, multiplayer arithmetic battle-royale game.
• It exposes HTTP endpoints for authentication and uses WebSockets (Socket.IO) for real-time game events.
• It persists users and game metadata in a relational database (via SQL schema and a repository layer) and holds live game sessions in memory.
File structure
• Top-level config: babel.config.ts, eslint.config.js, jest.config.js, tsconfig.json, etc.
• src/index.ts: application entry point, sets up Express and Socket.IO.
• src/routes: REST controllers (auth.routes.ts).
• src/socket: all real-time event handlers, grouped by connection, room, and game logic.
• src/services: business-logic layer (user-service.ts, room-service.ts).
• src/repositories: data-access layer (user.repository.ts).
• src/database: SQL schema, setup, seeding logic, and DB connection wrapper.
• src/state: in-memory game state manager.
• src/events: event definitions and dispatching logic.
• src/utils: pure helper functions (question generator, answer checker, user-level calculator).
• test/: unit and integration tests for each layer.
README for additional insights
• Confirms the use cases: quick join, host/join game, puzzle solving, attacking/defending via realtime events.
• Instructs running both client and server; the server serves only the backend API and WebSocket endpoints.
a. Main components
• Clients (Web Browser / Frontend – not in this repo)
• HTTP API Layer (Express + route handlers)
• WebSocket Layer (Socket.IO + socket/handlers)
• Service Layer (room-service, user-service)
• Repository Layer (user.repository)
• Database (SQL database, schema.sql)
• In-Memory State (game-state module)
• Event Engine (custom EventEmitter in src/events)
• Utility Modules (question generator, game logic, etc.)
b. Relationships & interactions
1. Clients send HTTP requests to the API layer → routed by auth.routes → calls user-service → calls user-repository → database.
2. Clients open a WebSocket connection → socket/connection-handlers register them.
3. During a game: client emits “answerSubmitted” → socket/game-handlers → invoke utils.check-answer & utils.game-logic → update in-memory game-state → emit game events back to clients (attack, heal, eliminate).
4. room-service orchestrates room creation/joining, updates game-state, and persists room metadata if needed.
5. Event Engine (src/events) publishes/subscribes to domain events (game.events, room.events) used by both HTTP and WebSocket handlers.
c. Architectural patterns & principles
• Layered architecture: Controllers → Services → Repositories → Database
• Event-driven design for decoupling game logic from transport
• In-memory state for session data, external persistence for durable data
• Separation of concerns: utils only handle pure logic, keeping services orchestrators
d. Key technologies
• Node.js + TypeScript
• Express.js (HTTP)
• Socket.IO (WebSocket)
• SQL database (likely SQLite or Postgres, based on schema.sql)
• Jest for testing
• Custom EventEmitter in src/events
Final advice
• Be detailed: break out socket handlers into connection, room, and game domains.
• Layers, from raw SQL scripts in database/ to pure functions in utils/.