# 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:

```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).