Skip to content

Architecture

System-level documentation for SectorWars 2102. Start here if you need a big-picture view; the other files in this directory go deeper on specific concerns.

Documents

File What it covers
services.md Each running service: language, port, responsibilities, entry points.
deployment.md Docker Compose topology, profiles, networks, volumes, healthchecks.
dev-environment.md Local dev workflow: devcontainer, dev-scripts, common commands.
auth.md Authentication: JWT issuance, OAuth providers, admin login, middleware.
multi-regional.md Multi-regional model: Central Nexus, regional servers, region-manager.
async-workers.md Background work: cron, schedulers, lazy-on-read patterns, idempotency.

System topology

SectorWars 2102 is a small constellation of services that share a Postgres database and a Redis cache, fronted in production by an Nginx gateway.

                           ┌─────────────────────────┐
                           │      nginx-gateway      │   :80 / :443
                           │  (TLS, routing, rate    │
                           │   limit, /api proxy)    │
                           └──────────┬──────────────┘
                                      │
              ┌───────────────────────┼───────────────────────────┐
              │                       │                           │
       ┌──────▼──────┐         ┌──────▼──────┐             ┌──────▼──────┐
       │ player-client│        │  admin-ui   │             │  gameserver │
       │ React/Vite   │        │ React/Vite  │             │  FastAPI    │
       │ :3000        │        │ :3001 → 3000│             │  :8080      │
       └──────┬───────┘        └──────┬──────┘             └──┬───────┬──┘
              │                       │                        │       │
              └───────────── REST + WebSocket ─────────────────┘       │
                                                                       │
                                            ┌──────────────────────────┘
                                            │
                              ┌─────────────▼─────────────┐
                              │     PostgreSQL 15         │
                              │  (sectorwars-database)    │
                              │     :5432 → :5433         │
                              └───────────────────────────┘
                                            ▲
                                            │
                              ┌─────────────┴─────────────┐
                              │       Redis 7-alpine      │
                              │   (cache + pub/sub)       │
                              │         :6379             │
                              └───────────────────────────┘

Multi-regional add-ons (multi-regional / production profiles):
  - region-manager      :8081  Provisions regional containers via Docker socket
  - central-nexus-server         FastAPI in "nexus" mode
  - central-nexus-db             Dedicated Postgres for the Nexus
  - redis-nexus         :6380   Cross-region pub/sub
  - regional-server-template     Template service for per-region game servers

Service responsibility (one-liner each)

  • gameserver (services/gameserver) — All game logic, REST API at /api/v1/*, WebSocket at /api/v1/ws/*, OAuth, JWT issuance.
  • player-client (services/player-client) — React/Vite SPA for players. No game logic; calls the gameserver.
  • admin-ui (services/admin-ui) — React/Vite SPA for admins. Same backend, gated by is_admin.
  • region-manager (services/region-manager) — Provisions, scales, monitors per-region containers. Talks to the Docker socket.
  • nginx-gateway (services/nginx-gateway) — TLS termination, routing, rate limiting, regional API path matching.
  • database (services/database) — Postgres 15 with init scripts and a healthcheck. Single instance in dev; per-region in multi-regional mode.

Conventions across services

  • All persistent state goes through Postgres via SQLAlchemy in the gameserver. Frontends never talk to the DB.
  • All cross-service calls are HTTP (REST) or WebSocket. No shared in-process code between gameserver and UIs.
  • Configuration is environment-variable driven; secrets live in .env (gitignored). See deployment.md for the variable list.
  • Docker Compose profiles select which subset of services runs: development / default for local dev, multi-regional and production for the larger topology, monitoring adds Prometheus + Grafana.

Source-of-truth pointers

When this doc disagrees with code, code wins. Quick links into the game repo:

  • Sectorwars2102/docker-compose.yml — authoritative service list.
  • Sectorwars2102/services/gameserver/src/main.py — FastAPI app bootstrap.
  • Sectorwars2102/services/gameserver/src/api/api.py — router aggregation.
  • Sectorwars2102/CLAUDE.md — current operational notes for the dev VM.