Границы микросервисов

Принципы разделения

1. По bounded context — auth, session, game — разные агрегаты
2. По частоте изменений — плагины игр меняются чаще session API
3. По масштабированию — realtime и bot масштабируются отдельно
4. Синхронные read — REST; события — NATS

Матрица сервисов

Сервис	Владеет данными	Публичный API	События (publish)	События (subscribe)
auth-service	users, credentials	/auth/*	user.registered	—
session-service	sessions, participants	/sessions/*	session.*, participant.*	user.registered
game-runtime	game_instances, audit	/games/*	game.*	session.closed
media-service	assets metadata	/media/*	—	game.state_changed (optional)
realtime-service	— (stateless)	WS /ws	—	game.*, session.*, participant.*
telegram-bot	bot FSM cache	—	—	game.*, session.*

Контракты между сервисами

Версионирование API

• URL: /api/v1/...
• Breaking changes → /api/v2/
• События: schema version в payload schema_version: 1

Идемпотентность

• Idempotency-Key header на POST action
• action_id UUID в теле

Ошибки (единый формат)

{
  "error": {
    "code": "INVALID_ACTION",
    "message": "Cell not in candidates",
    "details": {}
  }
}

Anti-patterns (избегать)

• Прямой доступ bot к PostgreSQL session tables
• Клиентская генерация кубиков
• Дублирование Participant при dual presence

Deployment modes

Mode	Когда
Microservices	Phase 2+, команда 3+, prod
Modular monolith	Phase 1, 1–2 разработчика
Bot separate	Всегда — отдельный процесс aiogram

Связанные документы

• API обзор
• OpenAPI draft