catan/docs/architecture.md

Catan Microservices Architecture

Overview

This repo is a monorepo with separate services (each container) and a shared core engine.

Services:

• api-gateway: Auth, lobby, websocket fanout, user masking, orchestrates game/AI services.
• game-service: Authoritative game state + rule validation, trade offers, AI turn loop triggers.
• ai-service: Model inference + random policy; returns actions + debug metadata.
• analytics-service: Stats, replays, debug views, replay reconstruction.
• web: React UI (served by nginx) for lobby, game, analytics, replays.

Shared:

• catan package: game engine & rules.
• services/common: env settings, shared schemas, JWT helpers, db helpers.

Runtime data flow

1. Client logs in via api-gateway (/api/auth/*).
2. Client interacts with lobby/game via api-gateway.
3. api-gateway forwards game mutations to game-service.
4. game-service applies actions to the core engine and persists events to Postgres.
5. game-service may call ai-service for AI moves.
6. api-gateway broadcasts updated game state to connected clients (websocket).
7. analytics-service reads events from Postgres to compute stats + replays.

Storage

Postgres (single instance) with service-owned tables:

• api-gateway: users
• game-service: games, game_events, trade_offers
• analytics-service: materialized stats + replay metadata (optional)

Replay format

Replay format is JSON:

{
  "id": "uuid",
  "created_at": "...",
  "seed": 123,
  "players": ["A", "B"],
  "actions": [
    {"idx": 1, "actor": "A", "type": "roll", "payload": {}},
    {"idx": 2, "actor": "A", "type": "build_road", "payload": {"edge": 4}}
  ]
}

analytics-service reconstructs a state at any action index by replaying from seed.

Debug mode

DEBUG=true enables:

• full action payloads
• AI logits/probabilities
• full observation snapshots

These are stored in game_events.debug_payload (JSON).