galaxy-game/CLAUDE.md

# Galaxy Game — Project Conventions

This repository hosts the Galaxy Game project.

## Sources of truth

- `docs/ARCHITECTURE.md` — global architecture, security model,
  cross-service contracts, and project-wide rules.
- `docs/FUNCTIONAL.md` — per-domain user stories that describe what each
  user-visible operation does, with the exact gateway and backend logic
  for it. Starting point for any change request that touches behaviour.
- `docs/FUNCTIONAL_ru.md` — Russian translation of `docs/FUNCTIONAL.md`,
  maintained as a convenience for the project owner. **Not a source of
  truth** — when the two files disagree, the English version wins.
  Every point edit applied to `docs/FUNCTIONAL.md` must also be
  mirrored into `docs/FUNCTIONAL_ru.md` in the same patch (translate
  the changed paragraphs only, do not re-translate the whole file).
  A full re-translation only happens on explicit owner request.
- `docs/TESTING.md` — testing layers (unit / integration), the
  integration runbook, and the principles every test must follow
  (no-op observability for testcontainers, `t.Fatal` on
  infrastructure breakages, label-driven preclean). Read before
  adding tests or modifying the integration harness.
- `galaxy/<service>/README.md` — service conventions, layout,
  configuration, and operations for an implemented or planned service.
- `galaxy/<service>/openapi.yaml` and `*.proto` files — exact wire
  contracts for REST and gRPC surfaces.

## Planning of service implementation and Implementing Plan

- `galaxy/<service>/PLAN.md` — staged implementation plan for the service.
  May be already complete and resides for historical reasons.
- `galaxy/<service>/docs/` — per-stage decision records
  (one file per decision, re-organized after full implementation
  of `PLAN.md`).

## Decision records when implementing stages from PLAN.md

- Stage-related discussion and decisions do NOT live in `README.md` or
  `docs/ARCHITECTURE.md`. Those files describe the current state, not the history.
- Each non-trivial decision gets its own `.md` under the module's `docs/`,
  referenced from the relevant `README.md`.
- Any agreement reached during interactive planning that is not obvious from
  the code must be captured — either as a decision record or as an entry in
  the module's README.

## Scope of PLAN.md changes

The existing codebase of `galaxy/<service>` may be modified or extended when a
plan stage requires it. All such changes must be covered by new or updated tests
and reflected in documentation when they affect documented behavior.

## Pre-production migration rule

The platform is not yet in production. Schema changes for `backend` go
into the existing `backend/internal/postgres/migrations/00001_init.sql`
file rather than into new `00002_*`-prefixed files. Local databases and
integration test harnesses are recreated from scratch on every pull.

**This rule is removed before the first production deployment.** From
that point on every schema change becomes a new migration file with a
monotonically increasing prefix, and `00001_init.sql` becomes immutable
history. See `backend/internal/postgres/migrations/README.md` for
details.

## Documentation discipline

- Code and docs are kept in sync. If an implementation changes behavior
  described in a `.md` or `.yaml` file, update that file in the same patch.
- If existing docs are incomplete or wrong for behavior you are already
  touching, fix them in the same patch.
- Do not silently remove commitments from `galaxy/<service>/README.md`
  or `galaxy/<service>/docs/*.md`. When a rule changes, either update it
  in place with the new agreement, or move the section to a more appropriate
  doc with a reference kept.
- Cross-module impact: if a new agreement requires changes in
  already-implemented modules, make those changes — code, tests, docs — in
  the same patch, and record the new rule in `docs/ARCHITECTURE.md`.

## Documentation synchronisation

The same behaviour is described in several parallel sources: code,
`docs/ARCHITECTURE.md`, `docs/FUNCTIONAL.md` (with its Russian mirror
`docs/FUNCTIONAL_ru.md`), the affected service `README.md`, the
relevant `openapi.yaml` or `*.proto`, and the per-stage decision
records under `galaxy/<service>/docs/`. They must never disagree.

- Any patch that changes user-visible behaviour, an API contract, or a
  cross-service flow updates every affected source in the same change
  set — never one source in this patch and another later.
- Before declaring a change complete, read the relevant sections of
  `docs/ARCHITECTURE.md`, `docs/FUNCTIONAL.md`, the affected service
  README, the relevant `openapi.yaml` or `*.proto`, and the implementing
  code; confirm they describe the same behaviour.
- When two sources disagree about existing behaviour, do not pick one
  silently. Decide which one is authoritative, fix the contradiction in
  the same patch, and call out the change in the response. If the
  resolution is non-obvious, escalate to the user before proceeding.
- When touching code, also re-read inline package and Go Doc Comments in
  the affected packages and update them when they no longer match the
  code.
- When `docs/FUNCTIONAL.md` changes, mirror the same change into
  `docs/FUNCTIONAL_ru.md` (translate only the touched paragraphs).
  Skipping the mirror is treated as an incomplete patch.

## Dependencies

- Before adding a new module, check its upstream repository for the latest
  stable version and use that.
- When a well-maintained library clearly outperforms stdlib for a concrete
  need, do not adopt it silently — propose a short list of 1+ candidates for
  the user to pick. Default remains stdlib.

## Language

- All code, comments, identifiers, commit messages, docs, and filenames are
  written in English.
- User-facing chat responses follow the Russian-translation rule from the
  user-level `CLAUDE.md`.