Skip to content

Services

Each row below points back into the game code repo (Sectorwars2102/) so you can follow the wire.

gameserver

The single backend service. All game logic, persistence, auth, and real-time messaging.

  • Language / framework: Python 3.11, FastAPI 0.103, Uvicorn ([standard]), SQLAlchemy 2.0 async, Pydantic v2, python-jose for JWT, httpx for OAuth, Argon2 for password hashing, redis-py.
  • Container port: 8080 (mapped via GAMESERVER_PORT, default 8080 on the host).
  • Healthcheck: GET /api/v1/status/health (compose) or GET /health (also defined directly on the app).
  • Entry points:
  • services/gameserver/src/main.py — FastAPI app construction, middleware wiring, startup/shutdown hooks, root and /health endpoints.
  • services/gameserver/src/api/api.py — aggregates ~46 routers under /api/v1/* (status, auth, users, admin, combat, trading, sectors, planets, teams, drones, fleets, websocket, AI, paypal, nexus, regional_governance, …).
  • services/gameserver/src/auth/ — dependencies.py, jwt.py, oauth.py, admin.py (see auth.md).
  • services/gameserver/src/core/config.py — settings, environment detection, JWT/OAuth env vars.
  • services/gameserver/src/api/middleware/security.py — OWASP headers, rate limiting, audit logging (setup_security_middleware).
  • Responsibilities:
  • Issues JWT access + refresh tokens.
  • Owns all SQLAlchemy models (src/models/) and migrations (alembic/).
  • Hosts WebSocket channels: /api/v1/ws/connect (player) and /api/v1/ws/admin.
  • Auto-creates the default admin on first start (see src/auth/admin.py).
  • Runs a background heartbeat sweep that disconnects stale WebSockets every 30 s.
  • Notable env vars: DATABASE_URL, REDIS_URL, JWT_SECRET (required, ≥32 chars), ADMIN_USERNAME, ADMIN_PASSWORD, CLIENT_ID_GITHUB, CLIENT_SECRET_GITHUB, GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, STEAM_API_KEY, API_BASE_URL, FRONTEND_URL. See deployment.md for the full list.

The router file (services/gameserver/src/api/api.py) imports 46 route modules.

player-client

Player-facing web app.

  • Language / framework: TypeScript, React 18, Vite. Adds @react-three/fiber, framer-motion, react-router-dom, i18next, axios. See services/player-client/package.json.
  • Container port: 3000.
  • Healthcheck: HTTP GET /index.html via Node.
  • Entry points:
  • services/player-client/src/main.tsx — React root, i18n init.
  • services/player-client/src/App.tsx — top-level router.
  • Responsibilities:
  • Authenticated UI for movement, trading, combat, teams, fleets, gambling, etc.
  • Real-time updates via WebSocket to the gameserver.
  • No business logic — all state changes round-trip through the API.
  • Notable env vars: REACT_APP_API_BASE_URL, REACT_APP_ENVIRONMENT, REACT_APP_MULTI_REGIONAL, REACT_APP_PAYPAL_CLIENT_ID.

admin-ui

Admin / operator console. Same backend as the player client, gated by the user's is_admin flag.

  • Language / framework: TypeScript, React 18, Vite. Adds Chart.js, D3, socket.io-client, i18next. See services/admin-ui/package.json.
  • Container port: 3000 internal, mapped to host 3001 by default (ADMIN_UI_PORT).
  • Healthcheck: HTTP GET /index.html via Node.
  • Entry points:
  • services/admin-ui/src/main.tsx — React root, Chart.js registration, i18n.
  • services/admin-ui/src/App.tsx — admin routes.
  • Responsibilities:
  • Galaxy / region / sector administration, player management, economy controls, faction tuning, first-login flow editing, fleet/drone configuration. All routes ultimately hit /api/v1/admin/* on the gameserver.
  • Notable env vars: VITE_API_URL, VITE_WS_URL, REACT_APP_API_BASE_URL, REACT_APP_NEXUS_MODE.

region-manager

Service-level orchestrator for per-region game servers. Runs only when the multi-regional or production-style profile is active.

  • Language / framework: Python, FastAPI, talks to Docker via the host's Docker socket (/var/run/docker.sock).
  • Container port: 8080 internal, host 8081 (REGION_MANAGER_PORT).
  • Healthcheck: GET /health.
  • Entry points:
  • services/region-manager/src/main.py — FastAPI app, region lifecycle endpoints.
  • services/region-manager/src/region_provisioner.py — creates regional databases, generates configs, starts containers, registers with the Central Nexus.
  • services/region-manager/src/monitoring.py — pulls container stats and player counts.
  • Responsibilities:
  • POST /regions/provision — provision a new regional server (DB + container), background-tasked.
  • DELETE /regions/{name} — graceful tear-down + DB cleanup + Nexus unregister.
  • POST /regions/{name}/scale — adjust CPU / memory / disk.
  • GET /regions, GET /regions/{name}, GET /metrics — read-only views.
  • Background loop that polls container stats every 30 s and auto-scales up at >80 % CPU or >85 % memory (capped at 8 cores / 16 GB).
  • Notable env vars: DATABASE_URL, REDIS_URL, DOCKER_HOST, JWT_SECRET, API_BASE_URL. Mounts the Docker socket read-write — privileged.

nginx-gateway

TLS-terminating reverse proxy that fronts the whole stack.

  • Language / framework: Nginx (alpine).
  • Container ports: 80 and 443 on the host (HTTP_PORT, HTTPS_PORT).
  • Entry points:
  • services/nginx-gateway/Dockerfile — base image and conf injection.
  • services/nginx-gateway/nginx.conf — upstreams, rate limit zones, SSL config, security headers, regional routing.
  • services/nginx-gateway/ssl/ — mounted read-only at /etc/nginx/ssl/.
  • Responsibilities:
  • Forwards / to player-client, /admin/ to admin-ui, /api/v1/ to gameserver.
  • Pattern-matches /api/v1/regions/{region_name}/... and proxies to region-{name}-server:8080 (regional fan-out).
  • Rate limiting zones: api (10 r/s), auth (5 r/s), general (100 r/s).
  • Adds OWASP-aligned security headers (X-Frame-Options DENY, X-Content-Type-Options nosniff, Referrer-Policy, etc.).
  • HTTP→HTTPS redirect except for /health.

database

Postgres 15-alpine instance for development. Multi-regional / production profiles provision additional databases.

  • Image: postgres:15-alpine.
  • Container port: 5432 internal, mapped to host 5433 by default (DB_PORT).
  • Healthcheck: pg_isready against the configured user/db.
  • Entry points / files:
  • services/database/init/ — SQL run on first boot (mounted at /docker-entrypoint-initdb.d).
  • services/database/config/ — postgres config overrides.
  • services/database/Dockerfile and Dockerfile.simple — optional custom image variants.
  • services/database/backup.sh, restore.sh, healthcheck.sh — operator scripts.
  • Multi-regional variants (defined in docker-compose.yml):
  • central-nexus-db (profiles multi-regional, production) — initialized from services/gameserver/sql/init-central-nexus.sql.
  • regional-db-template (profile regional-template) — Postgres template per regional server.

At-a-glance port map (defaults)

Service Container Host Override env
gameserver 8080 8080 GAMESERVER_PORT
player-client 3000 3000 PLAYER_CLIENT_PORT
admin-ui 3000 3001 ADMIN_UI_PORT
region-manager 8080 8081 REGION_MANAGER_PORT
database (dev) 5432 5433 DB_PORT
redis-cache 6379 6379 REDIS_PORT
redis-nexus 6380 6380 REDIS_NEXUS_PORT
nginx-gateway 80 / 443 80 / 443 HTTP_PORT / HTTPS_PORT
central-nexus-db 5432 5433 NEXUS_DB_PORT
central-nexus-server 8080 8080 CENTRAL_NEXUS_PORT
prometheus 9090 9090 PROMETHEUS_PORT
grafana 3000 3002 GRAFANA_PORT

⚠ Note: database and central-nexus-db both default to host port 5433. Only one set should be active at a time per the compose profiles, but be aware of the collision if you run mixed profiles.