# thevoid12/brainwars architecture

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

- Interactive diagram: https://gitdiagram.com/thevoid12/brainwars
- Repository: https://github.com/thevoid12/brainwars

## Overview

##### Project Type and Purpose
- This is a full-stack, real-time quiz game (“brainwars”) implemented as a monolithic Go service that serves both UI assets and JSON/WebSocket APIs.
- Users can sign in, create/join quiz rooms (with up to 10 players or bots), answer questions in real time, and view a live leaderboard. Planned v2 features include Redis-backed pub/sub, global matchmaking, sharing scores, and chat.

##### File-Structure Analysis
- Top-level:
- main.go, go.mod/sum – entrypoint and dependencies
- web/ – HTTP handlers, middleware, static UI templates & assets
- pkg/ – core business-logic packages (auth, users, quiz, room, bots, rate_limit, websocket, db, logger, util)
- config/ – JSON config files per environment
- migrations/ – SQL migration scripts + helper
- deployment/ – Docker, systemd, shell scripts, nginx config
- Patterns:
- Layered architecture (HTTP → handlers → services → data-access layer)
- SQL code generation (sqlc) under pkg/db/sqlc and custom dbal adapters
- WebSocket pub/sub in pkg/websocket for real-time updates

##### Key README Insights
- Environment variables configure Postgres connection
- v1 uses in-memory maps for state sync; v2 will introduce Redis Pub/Sub to sync across instances
- Bots implemented as timed answer generators

##### Main Components
a. Client Layer
- Web UI (HTML/CSS/JS using Tailwind, served from web/ui)
- WebSocket client scripts (ws.js, game.js, etc.)
b. API Layer
- HTTP server (net/http or Gin) with middleware (auth, CSRF, rate-limit, context) in web/middleware
- Route handlers in web/routes and web/ui/handlers
c. Business Logic Layer
- Auth service (pkg/auth)
- User service (pkg/users)
- Room service (pkg/room)
- Quiz service (pkg/quiz + prompt_service)
- Rate-limit service (pkg/rate_limit)
- Bot service (pkg/bots)
- WebSocket event service (pkg/websocket/event_service)
d. Data Layer
- PostgreSQL via pkg/db/db.go and pkg/db/dbal or sqlc packages
- (v2) Redis Pub/Sub for inter-instance messaging
e. External/Infrastructure
- LLM API for question generation
- Docker containers, nginx reverse proxy, systemd service

##### Relationships & Flows
- Browser UI → HTTP(S) → API handlers → service layer → database
- Browser UI ↔ WebSocket ↔ WebSocket service → event dispatcher → service layer → broadcast → Browser UI
- Services call pkg/db for CRUD and complex queries (via sqlc-generated code)
- Bot service schedules answer events back through the same WebSocket channel
- (v2) Multiple instances synchronize room state & events via Redis Pub/Sub

##### Architectural Patterns & Design Principles
- Layered separation (UI / HTTP / Services / Data)
- Single monolith with clearly separated packages
- Dependency injection for database and config
- Use of generated code for consistency (sqlc)
- Middleware funnel for cross-cutting concerns (auth, rate-limiting, CSRF)
- Event-driven real-time updates via WebSockets

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Browser (Frontend)" 
        direction TB
        WebUI["Web UI\n(HTML/CSS/JS)"]:::ui
        WSClient["WebSocket Client\n(ws.js, game.js)"]:::ui
    end

    %% Backend Envelope
    subgraph "Brainwars Service\n(Docker & nginx)" 
        direction TB
        Main["HTTP Server\n(main.go)"]:::api
        Routes["HTTP Routes\n(routes.go)"]:::api
        subgraph "Middleware"
            direction TB
            AuthMid["Auth Middleware"]:::api
            CSRF["CSRF Middleware"]:::api
            RateMid["RateLimit Middleware"]:::api
            ContextMid["Context Middleware"]:::api
            ProfileMid["CustomProfile Middleware"]:::api
        end
        WSService["WebSocket Service\n(websocket_service.go)"]:::api
        EventSvc["Event Service\n(event_service.go)"]:::api
        BotsWS["Bots WS Service\n(bots_websocket_service.go)"]:::api
    end

    %% Services Layer
    subgraph "Services" 
        direction TB
        AuthSvc["Auth Service"]:::services
        UserSvc["User Service"]:::services
        RoomSvc["Room Service"]:::services
        QuizSvc["Quiz Service"]:::services
        PromptSvc["Prompt Service"]:::services
        RateSvc["RateLimit Service"]:::services
        BotSvc["Bot Service"]:::services
    end

    %% Data Layer
    subgraph "Data Stores"
        direction TB
        Postgres["PostgreSQL DB"]:::data
        Redis["Redis Pub/Sub"]:::data
    end

    %% External
    subgraph "External"
        direction TB
        LLM["LLM API\n(Question Generation)"]:::external
    end

    %% Flows HTTP
    WebUI -->|"1. HTTP Request"| Main
    Main -->|routes.go| Routes
    Routes -->|auth| AuthMid
    Routes -->|csrf| CSRF
    Routes -->|rate-limit| RateMid
    Routes -->|context| ContextMid
    Routes -->|profile| ProfileMid
    ProfileMid -->|"calls"| AuthSvc
    ProfileMid -->|"calls"| UserSvc
    ProfileMid -->|"calls"| RoomSvc
    ProfileMid -->|"calls"| QuizSvc
    ProfileMid -->|"calls"| RateSvc

    %% Flows WebSocket
    WSClient -->|"2. WS Connect"| WSService
    WSService --> EventSvc
    EventSvc --> AuthSvc
    EventSvc --> RoomSvc
    EventSvc --> QuizSvc
    EventSvc --> BotSvc
    BotSvc --> BotsWS
    BotsWS --> WSClient

    %% Services to Data
    AuthSvc -->|"SQL"| Postgres
    UserSvc -->|"SQL"| Postgres
    RoomSvc -->|"SQL"| Postgres
    QuizSvc -->|"SQL"| Postgres
    RateSvc -->|"SQL"| Postgres
    BotSvc -->|"state"| Postgres

    %% Redis for v2
    RoomSvc -->|"Pub/Sub"| Redis
    EventSvc -->|"Pub/Sub"| Redis

    %% External LLM
    QuizSvc -->|"REST API"| LLM

    %% Deployment & Infra
    subgraph "Infrastructure"
        direction TB
        Deployment["nginx & systemd\n(deployment/)"]:::infra
    end
    Deployment --> Main
    Deployment --> WSService

    %% Click Events
    click WebUI "https://github.com/thevoid12/brainwars/tree/main/web/ui"
    click WSClient "https://github.com/thevoid12/brainwars/blob/main/web/ui/utility/js/ws.js"
    click Main "https://github.com/thevoid12/brainwars/blob/main/main.go"
    click Routes "https://github.com/thevoid12/brainwars/blob/main/web/routes/routes.go"
    click AuthMid "https://github.com/thevoid12/brainwars/blob/main/web/middleware/auth_middleware.go"
    click CSRF "https://github.com/thevoid12/brainwars/blob/main/web/middleware/csrf_middleware.go"
    click RateMid "https://github.com/thevoid12/brainwars/blob/main/web/middleware/ratelimit_middleware.go"
    click ContextMid "https://github.com/thevoid12/brainwars/blob/main/web/middleware/context_middleware.go"
    click ProfileMid "https://github.com/thevoid12/brainwars/blob/main/web/middleware/customprofile_middleware.go"
    click AuthSvc "https://github.com/thevoid12/brainwars/blob/main/pkg/auth/auth.go"
    click UserSvc "https://github.com/thevoid12/brainwars/blob/main/pkg/users/user_service.go"
    click RoomSvc "https://github.com/thevoid12/brainwars/blob/main/pkg/room/room_service.go"
    click QuizSvc "https://github.com/thevoid12/brainwars/blob/main/pkg/quiz/quiz_service.go"
    click PromptSvc "https://github.com/thevoid12/brainwars/blob/main/pkg/quiz/prompt_service.go"
    click RateSvc "https://github.com/thevoid12/brainwars/blob/main/pkg/rate_limit/rate_limit_service.go"
    click BotSvc "https://github.com/thevoid12/brainwars/blob/main/pkg/bots/bots_service.go"
    click WSService "https://github.com/thevoid12/brainwars/blob/main/pkg/websocket/websocket_service.go"
    click EventSvc "https://github.com/thevoid12/brainwars/blob/main/pkg/websocket/event_service.go"
    click BotsWS "https://github.com/thevoid12/brainwars/blob/main/pkg/websocket/bots_websocket_service.go"
    click Postgres "https://github.com/thevoid12/brainwars/blob/main/pkg/db/db.go"
    click Postgres "https://github.com/thevoid12/brainwars/blob/main/pkg/db/dbal/db.go"
    click Postgres "https://github.com/thevoid12/brainwars/blob/main/pkg/db/dbal/dbmodels.go"
    click Postgres "https://github.com/thevoid12/brainwars/blob/main/pkg/db/sqlc/quiz/quiz_query.sql.go"
    click Postgres "https://github.com/thevoid12/brainwars/blob/main/pkg/db/sqlc/room/room_query.sql.go"
    click Redis "https://github.com/thevoid12/brainwars/tree/main/n/a"
    click LLM "https://github.com/thevoid12/brainwars/tree/main/n/a"
    click Deployment "https://github.com/thevoid12/brainwars/tree/main/deployment/docker/DockerFile"
    click Deployment "https://github.com/thevoid12/brainwars/blob/main/deployment/docker/docker-compose.yml"
    click Deployment "https://github.com/thevoid12/brainwars/blob/main/deployment/nginx.conf"
    click Deployment "https://github.com/thevoid12/brainwars/blob/main/deployment/brainwars.service"

    %% Styles
    classDef ui fill:#D6EFFF,stroke:#333,stroke-width:1px
    classDef api fill:#DDF2DD,stroke:#333,stroke-width:1px
    classDef services fill:#C8E6C9,stroke:#333,stroke-width:1px
    classDef data fill:#FCE5CD,stroke:#333,stroke-width:1px
    classDef external fill:#E2D8F8,stroke:#333,stroke-width:1px
    classDef infra fill:#F0F0F0,stroke:#333,stroke-width:1px
```
