SYSTEM_GUIDE.md

title	Chessmate System Guide
service	global
status	draft
last_reviewed	2025-12-06
type	index

Chessmate System Guide

Quick navigation and index for the Chessmate microservices platform.

🚀 Quick Start

⚠️ First Time Setup (Required)

Before anything else, install the dx-cli tool:

# Clone the repository
git clone <repository-url>
cd chessmate

# Install dx-cli (REQUIRED FIRST STEP)
cd dx-cli
npm install
npm run build
cd ..

# Verify installation
node dx-cli/dist/index.js doctor

Once dx-cli is installed, see dx-cli/README.md for all available commands.

For Developers

1. Install dx-cli (see above)
2. Read AGENTS.md - Platform principles and philosophy
3. Run node dx-cli/dist/index.js dev - Start development environment
4. Check your service's README: /<service>/README.md
5. Follow dev guide: /<service>/docs/ (use how-to/local-dev.md for setup)

For Operators

1. Install dx-cli (see above)
2. Read SRE Playbook
3. Read Incident Response Guide
4. Check service runbooks: /<service>/docs/RUNBOOK.md

For Product/Business

1. Product Vision
2. Glossary
3. Domain Overview

---

🛠️ Developer Experience Platform (dx-cli)

The unified command-line interface for all developer workflows.

Location: ./dx-cli/

Key Commands:

• node dx-cli/dist/index.js dev - Start development environment
• node dx-cli/dist/index.js test - Run tests
• node dx-cli/dist/index.js build - Build services
• node dx-cli/dist/index.js deploy <env> - Deploy to environment
• node dx-cli/dist/index.js doctor - Check system health

Documentation:

• dx-cli/README.md - Complete command reference
• dx-cli/docs/overview.md - Implementation overview
• dx-cli/docs/DX_PLATFORM.md - Platform architecture
• dx-cli/docs/service-spec.md - service.yaml specification

See Quick Start above for installation instructions.

---

📋 Service Directory

API Services

account-api

Player account and profile management service.

• Language: Python (FastAPI)
• Database: PostgreSQL
• Status: Operational
• Quick Links: README | Docs | API Spec

live-game-api

Real-time active game state and moves.

• Language: Python (FastAPI)
• Database: PostgreSQL
• Status: Operational
• Quick Links: README | Docs | API Spec

game-history-api

Authoritative history ingestion and retrieval service fed by Kafka game events.

• Language: Go (REST)
• Database: PostgreSQL + S3 archival
• Status: Draft
• Quick Links: README | Docs | API Spec

matchmaking-api

Player matching and queue management.

• Language: Python (FastAPI)
• Database: PostgreSQL
• Status: Operational
• Quick Links: README | Docs | API Spec

rating-api

Player ratings across pools using Glicko-2.

• Language: Python (FastAPI)
• Database: PostgreSQL
• Status: Draft
• Quick Links: README | Docs | API Spec

bot-orchestrator-api

Engine-backed bot orchestration service (BotSpec, engine, knowledge integration).

• Language: Python (FastAPI)
• Database: None (stateless)
• Status: Draft
• Quick Links: README | Docs | API Spec

engine-cluster-api

Chess engine evaluation service running Stockfish-like engines.

• Language: Python (FastAPI)
• Database: None (stateless)
• Status: Draft
• Quick Links: README | Docs | API Spec

chess-knowledge-api

Chess knowledge service for opening books and endgame tablebases.

• Language: Python (FastAPI)
• Database: None (stateless)
• Status: Draft
• Quick Links: README | Docs | API Spec

Client Applications

chess-app

Mobile and web user interface.

• Language: TypeScript (React Native + React)
• Platforms: iOS, Android, Web
• Status: Operational
• Quick Links: README | Docs

---

📚 Platform Documentation

Architecture & Design

• System Architecture Overview
• System Context
• Domain Map
• Service Catalog
• Integration Flows

Standards & Guidelines

• Engineering Guide (AGENTS.md)
• Coding Style Standards
• Testing Standards
• Logging Standards
• Security Standards
• Observability Standards
• Documentation Standards

Operations & Reliability

• SRE Playbook
• Incident Response Guide
• On-Call Engineer Guide

Business Context

• Product Vision
• Domain Overview
• Glossary

Decisions

• Architectural Decision Records

---

🔍 Search by Topic

Getting Started

• I'm a new developer: Read AGENTS.md, then your service README
• I'm setting up my dev environment: See /<service>/docs/GETTING_STARTED.md I need to run tests: Check your service's README for test commands I need to deploy: Read /<service>/docs/RUNBOOK.md → Deployment section I need to set up my dev environment: See /<service>/docs/how-to/local-dev.md

Development

• How should I structure code?: Coding Style Standards
• What's the testing strategy?: Testing Standards
• How do I write logs?: Logging Standards
• How do services communicate?: Integration Flows
• What's the overall architecture?: System Architecture

Operations

• I'm on-call: Read On-Call Guide
• There's an incident: See Incident Response Guide
• I need to monitor a service: Check SRE Playbook
• Service won't start: See service-specific RUNBOOK.md

Business & Product

• What's our vision?: Product Vision
• What does term X mean?: Glossary
• How does the business model work?: Domain Overview
• What's the roadmap?: Product Vision → Roadmap

Architecture & Design

• High-level architecture?: System Architecture
• How do services integrate?: Integration Flows
• What's a bounded context?: Domain Map
• Complete service list: Service Catalog
• Why was X decided?: Architectural Decisions

---

🔗 Cross-References

By Service

account-api

• Overview: docs/README.md
• API: docs/overview.md
• Architecture: docs/ARCHITECTURE.md
• Domain: docs/domain.md (if exists)
• Ops: docs/RUNBOOK.md

live-game-api

• Overview: docs/README.md
• API: docs/overview.md
• Architecture: docs/ARCHITECTURE.md
• Domain: docs/domain.md (if exists)
• Ops: docs/RUNBOOK.md

matchmaking-api

• Overview: docs/README.md
• API: docs/overview.md
• Architecture: docs/ARCHITECTURE.md
• Domain: docs/domain.md (if exists)
• Ops: docs/RUNBOOK.md

chess-app

• Overview: docs/README.md
• Architecture: docs/ARCHITECTURE.md

---

📊 Repository Structure

chessmate/
├── AGENTS.md                    # Engineering guide & principles
├── ARCHITECTURE.md              # System architecture overview
├── SYSTEM_GUIDE.md              # This file - navigation & index
│
├── docs/                        # Cross-service documentation
│   ├── README.md                # Docs index & navigation
│   ├── standards/               # Platform standards
│   │   ├── coding-style.md
│   │   ├── testing.md
│   │   ├── logging.md
│   │   ├── security.md
│   │   ├── observability.md
│   │   └── documentation.md
│   ├── architecture/            # System architecture
│   │   ├── system-context.md
│   │   ├── domain-map.md
│   │   ├── service-catalog.md
│   │   └── integration-flows.md
│   ├── operations/              # Operational guides
│   │   ├── sre-playbook.md
│   │   ├── incident-response.md
│   │   └── oncall-guide.md
│   ├── business/                # Business context
│   │   ├── product-vision.md
│   │   ├── domain-overview.md
│   │   └── glossary.md
│   └── decisions/               # Architectural decisions
│       ├── README.md
│       └── ADR-*.md
│
├── account-api/                 # Service: Account & Identity
│   ├── README.md
│   ├── docs/
│   │   ├── README.md
│   │   ├── overview.md
│   │   ├── ARCHITECTURE.md
│   │   ├── api.md
│   │   ├── domain.md
│   │   ├── operations.md
│   │   ├── RUNBOOK.md
│   │   ├── how-to/
│   │   ├── decisions/
│   │   └── migrations/
│   ├── app/
│   ├── migrations/
│   ├── tests/
│   └── pyproject.toml
│
├── live-game-api/               # Service: Real-Time Gaming
│   ├── README.md
│   ├── docs/
│   │   └── [same structure as account-api]
│   ├── app/
│   ├── migrations/
│   ├── tests/
│   └── pyproject.toml
│
├── matchmaking-api/             # Service: Player Matching
│   ├── README.md
│   ├── docs/
│   │   └── [same structure as account-api]
│   ├── app/
│   ├── migrations/
│   ├── tests/
│   └── pyproject.toml
│
└── chess-app/                   # Client: Mobile & Web UI
    ├── README.md
    ├── docs/
    │   ├── README.md
    │   ├── overview.md
    │   ├── ARCHITECTURE.md
    │   ├── how-to/
    │   └── decisions/
    ├── src/
    ├── package.json
    └── [React/React Native config]

---

🆘 Getting Help

Question	Resource
Where do I start?	Read AGENTS.md first
How do I set up my dev environment?	Service-specific GETTING_STARTED.md
What's the architecture?	ARCHITECTURE.md and system-context.md
How do I deploy?	Service RUNBOOK.md under "Deployment"
There's an incident!	Incident Response Guide
What does term X mean?	Glossary
Why was decision Y made?	Architecture Decisions
How do I write code?	Coding Standards
How should I test?	Testing Standards
What's the product roadmap?	Product Vision

---

Last updated: 2025-12-06 For updates to this guide, see: Documentation Standards