# listenrwt/fill-in-the-math-server architecture

> Architecture diagram of the GitHub repository listenrwt/fill-in-the-math-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/listenrwt/fill-in-the-math-server
- Repository: https://github.com/listenrwt/fill-in-the-math-server

## Overview

##### 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/.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Transport Layer
    subgraph "Clients"
        direction TB
        Client["Web Browser Client"]:::external
    end

    subgraph "Transport Layer"
        direction TB
        HTTP_API["Express HTTP API"]:::transport
        WS_Core["Socket.IO Core"]:::transport
        ConnHandlers["Connection Handlers"]:::transport
        RoomHandlers["Room Handlers"]:::transport
        GameHandlers["Game Handlers"]:::transport
    end

    %% Business Logic
    subgraph "Service Layer"
        direction TB
        UserService["User Service"]:::logic
        RoomService["Room Service"]:::logic
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        UserRepo["User Repository"]:::data
        DB_Wrapper["DB Connection Wrapper"]:::data
        DB_Schema["Schema Definition"]:::data
        DB_Setup["Setup Logic"]:::data
        DB_Seed["Seeding Logic"]:::data
        GameState["In-Memory Game State"]:::data
    end

    %% Event Engine
    subgraph "Event Engine"
        direction TB
        EventsBase["Events Base & Dispatch"]:::event
        GameEvents["Game Events"]:::event
        RoomEvents["Room Events"]:::event
    end

    %% Utilities
    subgraph "Utils"
        direction TB
        CheckAnswer["Answer Checker"]:::utils
        GameLogic["Game Logic"]:::utils
        QuestionGen["Question Generator"]:::utils
        LevelCalc["User-Level Calculator"]:::utils
        GenHelpers["General Helpers"]:::utils
    end

    %% Flows
    Client -->|"HTTP Request"| HTTP_API
    HTTP_API -->|"authenticate"| UserService
    UserService -->|"getUser"| UserRepo
    UserRepo -->|"query DB"| DB_Wrapper
    DB_Wrapper --> DB_Schema
    DB_Wrapper --> DB_Setup
    DB_Wrapper --> DB_Seed

    Client -->|"WebSocket Connect"| WS_Core
    WS_Core --> ConnHandlers
    ConnHandlers --> RoomHandlers
    ConnHandlers --> GameHandlers
    RoomHandlers -->|"joinRoom"| RoomService
    RoomService --> GameState
    RoomService --> UserRepo
    GameHandlers -->|"submitAnswer"| CheckAnswer
    GameHandlers --> GameLogic
    CheckAnswer --> GameState
    GameLogic --> GameState
    GameHandlers -->|"emitEvents"| WS_Core

    %% Event Engine interactions
    RoomService --> EventsBase
    GameHandlers --> EventsBase
    EventsBase --> GameEvents
    EventsBase --> RoomEvents

    %% Utils interactions
    QuestionGen --> GameLogic
    LevelCalc --> UserService
    GenHelpers --> UserService

    %% Click Events
    click HTTP_API "https://github.com/listenrwt/fill-in-the-math-server/blob/master/src/routes/auth.routes.ts"
    click WS_Core "https://github.com/listenrwt/fill-in-the-math-server/blob/master/src/socket/socket-handlers.ts"
    click ConnHandlers "https://github.com/listenrwt/fill-in-the-math-server/blob/master/src/socket/handlers/connection-handlers.ts"
    click RoomHandlers "https://github.com/listenrwt/fill-in-the-math-server/blob/master/src/socket/handlers/room-handlers.ts"
    click GameHandlers "https://github.com/listenrwt/fill-in-the-math-server/blob/master/src/socket/handlers/game-handlers.ts"
    click UserService "https://github.com/listenrwt/fill-in-the-math-server/blob/master/src/services/user-service.ts"
    click RoomService "https://github.com/listenrwt/fill-in-the-math-server/blob/master/src/services/room-service.ts"
    click UserRepo "https://github.com/listenrwt/fill-in-the-math-server/blob/master/src/repositories/user.repository.ts"
    click DB_Wrapper "https://github.com/listenrwt/fill-in-the-math-server/blob/master/src/database/db.ts"
    click DB_Schema "https://github.com/listenrwt/fill-in-the-math-server/blob/master/src/database/schema.sql"
    click DB_Setup "https://github.com/listenrwt/fill-in-the-math-server/blob/master/src/database/setup.ts"
    click DB_Seed "https://github.com/listenrwt/fill-in-the-math-server/blob/master/src/database/seed.ts"
    click GameState "https://github.com/listenrwt/fill-in-the-math-server/blob/master/src/state/game-state.ts"
    click EventsBase "https://github.com/listenrwt/fill-in-the-math-server/blob/master/src/events/events.ts"
    click GameEvents "https://github.com/listenrwt/fill-in-the-math-server/blob/master/src/events/game.events.ts"
    click RoomEvents "https://github.com/listenrwt/fill-in-the-math-server/blob/master/src/events/room.events.ts"
    click CheckAnswer "https://github.com/listenrwt/fill-in-the-math-server/blob/master/src/utils/check-answer.ts"
    click GameLogic "https://github.com/listenrwt/fill-in-the-math-server/blob/master/src/utils/game-logic.ts"
    click QuestionGen "https://github.com/listenrwt/fill-in-the-math-server/blob/master/src/utils/question-generator.ts"
    click LevelCalc "https://github.com/listenrwt/fill-in-the-math-server/blob/master/src/utils/user-level-calculator.ts"
    click GenHelpers "https://github.com/listenrwt/fill-in-the-math-server/blob/master/src/utils/utils.ts"

    %% Styles
    classDef transport fill:#ADD8E6,stroke:#000,color:#000
    classDef logic fill:#90EE90,stroke:#000,color:#000
    classDef data fill:#FFA500,stroke:#000,color:#000
    classDef event fill:#DDA0DD,stroke:#000,color:#000
    classDef utils fill:#98FB98,stroke:#000,color:#000
    classDef external fill:#FFFFFF,stroke:#000,color:#000,stroke-dasharray: 5 5
```
