Catan Web Monorepo

Production-ready monorepo skeleton for a Catan-like web game with an authoritative backend and a pure, deterministic rules engine.

Prerequisites

• Node.js 20+
• pnpm 8+
• Python 3.11+
• Docker (optional, for infra services)

One-command local dev

pnpm dev

This runs:

• apps/web (Next.js) on port 3000
• apps/api (NestJS + Socket.IO) on port 3001
• apps/rules-service (Node) on port 4001
• apps/ai (FastAPI) on port 8001

Optional infra services:

docker compose -f infra/docker-compose.yml up -d

Architecture

                        +----------------------+
                        |      Next.js Web     |
                        |  /apps/web (client)  |
                        +----------+-----------+
                                   |
                                   | Socket.IO
                                   v
+----------------------+     +-----+----------------+
|   Rules Service      |     |     NestJS API      |
| /apps/rules-service  |<--->| /apps/api (author.) |
+----------+-----------+     +----------+----------+
           |                          |
           | direct import            | uses rules for validation
           v                          v
+----------------------+     +----------------------+
|   Rules Engine       |     |  Shared Schemas      |
| /packages/rules      |<--->| /packages/shared     |
+----------------------+     +----------------------+
           ^
           |
+----------+-----------+
|  FastAPI AI Service  |
|     /apps/ai         |
+----------------------+

Rules engine sharing

• The single source of truth for state and move schemas lives in packages/shared (Zod).
• The deterministic, pure rules logic is implemented in packages/rules and imports those schemas.
• The backend (apps/api) validates all moves server-side through applyMove.
• The frontend may import rules for previews only (non-authoritative).

Python -> rules-service

The AI service calls the Node rules service to verify legality and apply moves:

• POST /legal-moves for candidate moves
• POST /apply-move to advance game state

Configure the target URL with RULES_SERVICE_URL (defaults to http://localhost:4001).

Useful commands

• pnpm dev - run all services
• pnpm build - build all packages/apps
• pnpm lint - lint TypeScript (and Python if ruff is installed)
• pnpm test - placeholder tests