62 lines
1.9 KiB
Markdown
62 lines
1.9 KiB
Markdown
# 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).
|