# accxlr8/chainreaction-backend architecture

> Architecture diagram of the GitHub repository accxlr8/chainreaction-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/accxlr8/chainreaction-backend
- Repository: https://github.com/accxlr8/chainreaction-backend

## Overview

Chain Reaction is a FastAPI backend for two-player games. Clients authenticate and create or join games over HTTP or connect to a game WebSocket; matchmaking is a separate entry path. The game service validates moves, advances the authoritative engine, updates clocks and persists moves/events; the WebSocket route then broadcasts accepted moves and refreshed snapshots. The README documents replay storage and other integrations, but the sampled sources do not establish which runtime components invoke replay storage, so that relationship is left unconnected. Edges reflect excerpts, indexed references, or README statements.

Main entry points: [`app/websocket/routes.py`](https://github.com/accxlr8/chainreaction-backend/blob/main/app/websocket/routes.py) (WebSocket routes), [`app/main.py`](https://github.com/accxlr8/chainreaction-backend/blob/main/app/main.py) (FastAPI app), [`app/games/service.py`](https://github.com/accxlr8/chainreaction-backend/blob/main/app/games/service.py) (Game orchestration), [`app/api/router.py`](https://github.com/accxlr8/chainreaction-backend/blob/main/app/api/router.py) (HTTP router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and identity"]
  node_api_router["HTTP router<br/>[router.py]"]
  node_game_api["Game endpoints<br/>[games.py]"]
  node_user_api["User endpoints<br/>[users.py]"]
  node_health_api["Health endpoint<br/>[health.py]"]
  node_match_api["Matchmaking endpoint<br/>[matchmaking.py]"]
  node_auth_dependency["HTTP auth<br/>[dependencies.py]"]
  node_auth_service["JWT authentication<br/>[service.py]"]
end

subgraph group_gameplay["Game runtime"]
  node_websocket["WebSocket routes<br/>[routes.py]"]
  node_ws_manager["Connection manager<br/>[manager.py]"]
  node_ws_connection["Connection state<br/>[connection.py]"]
  node_ws_protocol["Message protocol<br/>[protocol.py]"]
  node_game_service["Game orchestration<br/>[service.py]"]
  node_game_clock["Game clocks<br/>[clock.py]"]
  node_engine_adapter["Engine adapter<br/>[adapter.py]"]
  node_match_service["Matchmaking service<br/>[service.py]"]
  node_match_queue["Queue operations<br/>[queue.py]"]
end

subgraph group_state["State and integrations"]
  node_repositories["Data repositories<br/>[repositories.py]"]
  node_db_models["Game data models<br/>[models.py]"]
  node_database[("Postgres")]
  node_db_session["Database sessions<br/>[session.py]"]
  node_redis_client["Redis client<br/>[client.py]"]
  node_redis[("Redis")]
  node_redis_keys["Redis keys<br/>[keys.py]"]
  node_replay_storage["Replay storage<br/>[service.py]"]
end

subgraph group_platform["Application platform"]
  node_app["FastAPI app<br/>[main.py]"]
  node_settings["Settings<br/>[settings.py]"]
end

node_clients(("Game clients"))
node_engine["Chain Reaction engine"]
node_azure[("Azure Blob Storage")]

node_clients -->|"sends HTTP"| node_app
node_clients -->|"opens game socket"| node_websocket
node_app -->|"mounts"| node_api_router
node_app -->|"mounts"| node_websocket
node_app -->|"connects"| node_db_session
node_app -->|"connects"| node_redis_client
node_app -->|"loads"| node_settings
node_api_router -->|"routes to"| node_game_api
node_api_router -->|"routes to"| node_user_api
node_api_router -->|"routes to"| node_health_api
node_api_router -->|"routes to"| node_match_api
node_game_api -->|"authenticates with"| node_auth_dependency
node_user_api -->|"authenticates with"| node_auth_dependency
node_match_api -->|"authenticates with"| node_auth_dependency
node_auth_dependency -->|"validates token"| node_auth_service
node_auth_service -->|"reads secret"| node_settings
node_game_api -->|"delegates game actions"| node_game_service
node_game_api -->|"queries data"| node_repositories
node_game_api -->|"uses sessions"| node_db_session
node_match_api -->|"delegates matching"| node_match_service
node_health_api -->|"checks database"| node_db_session
node_health_api -->|"checks Redis"| node_redis_client
node_websocket -->|"authenticates token"| node_auth_service
node_websocket -->|"submits moves"| node_game_service
node_websocket -->|"loads snapshots"| node_repositories
node_websocket -->|"opens sessions"| node_db_session
node_websocket -->|"broadcasts messages"| node_ws_manager
node_websocket -->|"parses messages"| node_ws_protocol
node_ws_manager -->|"manages connections"| node_ws_connection
node_game_service -->|"reads and writes"| node_repositories
node_game_service -->|"applies moves"| node_engine_adapter
node_game_service -->|"advances clocks"| node_game_clock
node_game_service -->|"reads configuration"| node_settings
node_engine_adapter -->|"invokes engine"| node_engine
node_repositories -->|"queries models"| node_db_models
node_db_session -->|"persists through"| node_database
node_match_service -->|"uses queue"| node_match_queue
node_match_service -->|"uses Redis"| node_redis_client
node_match_queue -->|"uses keys"| node_redis_keys
node_redis_client -->|"connects to"| node_redis
node_replay_storage -->|"stores replays"| node_azure

click node_app "https://github.com/accxlr8/chainreaction-backend/blob/main/app/main.py"
click node_api_router "https://github.com/accxlr8/chainreaction-backend/blob/main/app/api/router.py"
click node_game_api "https://github.com/accxlr8/chainreaction-backend/blob/main/app/api/games.py"
click node_user_api "https://github.com/accxlr8/chainreaction-backend/blob/main/app/api/users.py"
click node_health_api "https://github.com/accxlr8/chainreaction-backend/blob/main/app/api/health.py"
click node_match_api "https://github.com/accxlr8/chainreaction-backend/blob/main/app/api/matchmaking.py"
click node_auth_dependency "https://github.com/accxlr8/chainreaction-backend/blob/main/app/auth/dependencies.py"
click node_auth_service "https://github.com/accxlr8/chainreaction-backend/blob/main/app/auth/service.py"
click node_websocket "https://github.com/accxlr8/chainreaction-backend/blob/main/app/websocket/routes.py"
click node_ws_manager "https://github.com/accxlr8/chainreaction-backend/blob/main/app/websocket/manager.py"
click node_ws_connection "https://github.com/accxlr8/chainreaction-backend/blob/main/app/websocket/connection.py"
click node_ws_protocol "https://github.com/accxlr8/chainreaction-backend/blob/main/app/websocket/protocol.py"
click node_game_service "https://github.com/accxlr8/chainreaction-backend/blob/main/app/games/service.py"
click node_game_clock "https://github.com/accxlr8/chainreaction-backend/blob/main/app/games/clock.py"
click node_engine_adapter "https://github.com/accxlr8/chainreaction-backend/blob/main/app/engine/adapter.py"
click node_match_service "https://github.com/accxlr8/chainreaction-backend/blob/main/app/matchmaking/service.py"
click node_match_queue "https://github.com/accxlr8/chainreaction-backend/blob/main/app/matchmaking/queue.py"
click node_repositories "https://github.com/accxlr8/chainreaction-backend/blob/main/app/database/repositories.py"
click node_db_models "https://github.com/accxlr8/chainreaction-backend/blob/main/app/database/models.py"
click node_db_session "https://github.com/accxlr8/chainreaction-backend/blob/main/app/database/session.py"
click node_redis_client "https://github.com/accxlr8/chainreaction-backend/blob/main/app/redis/client.py"
click node_redis_keys "https://github.com/accxlr8/chainreaction-backend/blob/main/app/redis/keys.py"
click node_replay_storage "https://github.com/accxlr8/chainreaction-backend/blob/main/app/storage/service.py"
click node_settings "https://github.com/accxlr8/chainreaction-backend/blob/main/app/config/settings.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api_router,node_game_api,node_user_api,node_health_api,node_match_api,node_auth_dependency,node_auth_service,node_clients toneBlue
class node_websocket,node_ws_manager,node_ws_connection,node_ws_protocol,node_game_service,node_game_clock,node_engine_adapter,node_match_service,node_match_queue,node_azure toneAmber
class node_repositories,node_db_models,node_database,node_db_session,node_redis_client,node_redis,node_redis_keys,node_replay_storage toneMint
class node_app,node_settings toneRose
class node_engine toneIndigo
```

## Components

### API and identity

- [HTTP router](https://github.com/accxlr8/chainreaction-backend/blob/main/app/api/router.py): `app/api/router.py`
- [Game endpoints](https://github.com/accxlr8/chainreaction-backend/blob/main/app/api/games.py): `app/api/games.py`
- [User endpoints](https://github.com/accxlr8/chainreaction-backend/blob/main/app/api/users.py): `app/api/users.py`
- [Health endpoint](https://github.com/accxlr8/chainreaction-backend/blob/main/app/api/health.py): `app/api/health.py`
- [Matchmaking endpoint](https://github.com/accxlr8/chainreaction-backend/blob/main/app/api/matchmaking.py): `app/api/matchmaking.py`
- [HTTP auth](https://github.com/accxlr8/chainreaction-backend/blob/main/app/auth/dependencies.py): `app/auth/dependencies.py`
- [JWT authentication](https://github.com/accxlr8/chainreaction-backend/blob/main/app/auth/service.py): `app/auth/service.py`

### Game runtime

- [WebSocket routes](https://github.com/accxlr8/chainreaction-backend/blob/main/app/websocket/routes.py): `app/websocket/routes.py`
- [Connection manager](https://github.com/accxlr8/chainreaction-backend/blob/main/app/websocket/manager.py): `app/websocket/manager.py`
- [Connection state](https://github.com/accxlr8/chainreaction-backend/blob/main/app/websocket/connection.py): `app/websocket/connection.py`
- [Message protocol](https://github.com/accxlr8/chainreaction-backend/blob/main/app/websocket/protocol.py): `app/websocket/protocol.py`
- [Game orchestration](https://github.com/accxlr8/chainreaction-backend/blob/main/app/games/service.py): `app/games/service.py`
- [Game clocks](https://github.com/accxlr8/chainreaction-backend/blob/main/app/games/clock.py): `app/games/clock.py`
- [Engine adapter](https://github.com/accxlr8/chainreaction-backend/blob/main/app/engine/adapter.py): `app/engine/adapter.py`
- [Matchmaking service](https://github.com/accxlr8/chainreaction-backend/blob/main/app/matchmaking/service.py): `app/matchmaking/service.py`
- [Queue operations](https://github.com/accxlr8/chainreaction-backend/blob/main/app/matchmaking/queue.py): `app/matchmaking/queue.py`

### State and integrations

- [Data repositories](https://github.com/accxlr8/chainreaction-backend/blob/main/app/database/repositories.py): `app/database/repositories.py`
- [Game data models](https://github.com/accxlr8/chainreaction-backend/blob/main/app/database/models.py): `app/database/models.py`
- **Postgres**
- [Database sessions](https://github.com/accxlr8/chainreaction-backend/blob/main/app/database/session.py): `app/database/session.py`
- [Redis client](https://github.com/accxlr8/chainreaction-backend/blob/main/app/redis/client.py): `app/redis/client.py`
- **Redis**
- [Redis keys](https://github.com/accxlr8/chainreaction-backend/blob/main/app/redis/keys.py): `app/redis/keys.py`
- [Replay storage](https://github.com/accxlr8/chainreaction-backend/blob/main/app/storage/service.py): `app/storage/service.py`

### Application platform

- [FastAPI app](https://github.com/accxlr8/chainreaction-backend/blob/main/app/main.py): `app/main.py`
- [Settings](https://github.com/accxlr8/chainreaction-backend/blob/main/app/config/settings.py): `app/config/settings.py`

### Other components

- **Game clients**
- **Chain Reaction engine**
- **Azure Blob Storage**

## Connections

- Game clients → FastAPI app: sends HTTP
- Game clients → WebSocket routes: opens game socket
- FastAPI app → HTTP router: mounts (evidence: `app/main.py`)
- FastAPI app → WebSocket routes: mounts (evidence: `app/main.py`)
- FastAPI app → Database sessions: connects (evidence: `app/main.py`)
- FastAPI app → Redis client: connects (evidence: `app/main.py`)
- FastAPI app → Settings: loads (evidence: `app/main.py`)
- HTTP router → Game endpoints: routes to (evidence: `app/api/router.py`)
- HTTP router → User endpoints: routes to (evidence: `app/api/router.py`)
- HTTP router → Health endpoint: routes to (evidence: `app/api/router.py`)
- HTTP router → Matchmaking endpoint: routes to (evidence: `app/api/router.py`)
- Game endpoints → HTTP auth: authenticates with (evidence: `app/api/games.py`)
- User endpoints → HTTP auth: authenticates with (evidence: `app/api/users.py`)
- Matchmaking endpoint → HTTP auth: authenticates with (evidence: `app/api/matchmaking.py`)
- HTTP auth → JWT authentication: validates token (evidence: `app/auth/dependencies.py`)
- JWT authentication → Settings: reads secret (evidence: `app/auth/service.py`)
- Game endpoints → Game orchestration: delegates game actions (evidence: `app/api/games.py`)
- Game endpoints → Data repositories: queries data (evidence: `app/api/games.py`)
- Game endpoints → Database sessions: uses sessions (evidence: `app/api/games.py`)
- Matchmaking endpoint → Matchmaking service: delegates matching (evidence: `app/api/matchmaking.py`)
- Health endpoint → Database sessions: checks database (evidence: `app/api/health.py`)
- Health endpoint → Redis client: checks Redis (evidence: `app/api/health.py`)
- WebSocket routes → JWT authentication: authenticates token (evidence: `app/websocket/routes.py`)
- WebSocket routes → Game orchestration: submits moves (evidence: `app/websocket/routes.py`)
- WebSocket routes → Data repositories: loads snapshots (evidence: `app/websocket/routes.py`)
- WebSocket routes → Database sessions: opens sessions (evidence: `app/websocket/routes.py`)
- WebSocket routes → Connection manager: broadcasts messages (evidence: `app/websocket/routes.py`)
- WebSocket routes → Message protocol: parses messages (evidence: `app/websocket/routes.py`)
- Connection manager → Connection state: manages connections (evidence: `app/websocket/manager.py`)
- Game orchestration → Data repositories: reads and writes (evidence: `app/games/service.py`)
- Game orchestration → Engine adapter: applies moves (evidence: `app/games/service.py`)
- Game orchestration → Game clocks: advances clocks (evidence: `app/games/service.py`)
- Game orchestration → Settings: reads configuration (evidence: `app/games/service.py`)
- Engine adapter → Chain Reaction engine: invokes engine
- Data repositories → Game data models: queries models (evidence: `app/database/repositories.py`)
- Database sessions → Postgres: persists through
- Matchmaking service → Queue operations: uses queue (evidence: `app/matchmaking/service.py`)
- Matchmaking service → Redis client: uses Redis (evidence: `app/matchmaking/service.py`)
- Queue operations → Redis keys: uses keys (evidence: `app/matchmaking/queue.py`)
- Redis client → Redis: connects to (evidence: `app/redis/client.py`)
- Replay storage → Azure Blob Storage: stores replays
