Skip to main content
Most style is enforced by tools, so you rarely need to remember it: the commit hooks and CI run them for you. This page is the summary. The full rules live in the CLAUDE.md file of each area, and those files win if anything here disagrees:

Across the codebase

  • Search before you build. Before writing a helper, type, hook or service, look for one that already exists. Shared code goes in libs/shared/py or libs/shared/ts, never copied between apps.
  • Fail loudly. Don’t swallow errors with a broad except or a silent default. Let them reach a place that can handle them.
  • No magic values. A literal that means something becomes a named constant, grouped by domain (for example app/constants/ in the API).
  • Organise by feature. A feature keeps its components, hooks, types and API calls together.
  • Delete what you replace. No commented-out code, no unused imports, no old versions left “just in case”.
  • Comments say why, not what. Names explain what the code does. A comment is one line of reasoning at the point of surprise.

Python

  • Ruff lints and formats, mypy checks types. Run mise run lint:py and mise run type-check.
  • Every function has full type annotations. Don’t add Any or bare dict/list to a file that has none.
  • Imports go at the top of the file, never inside a function.
  • A docstring is one imperative summary line, plus only what the signature doesn’t already say. No Args: entry that repeats a parameter’s name or type.
  • Routes are thin: record what the request is about with log.set(...), call a service, return a Pydantic model. Services are plain async functions, not classes, and reach MongoDB only through a repository in app/db/repositories/.

TypeScript

  • Biome lints and formats instead of ESLint and Prettier. Run mise run lint, or mise run lint:fix to fix and sort imports.
  • Never use any. Imports go at the top of the file.
  • API request and response types come from @gaia/shared/api/generated, which is generated from the API. Never write a type that copies an API model by hand. After changing an API route or model, run mise run api:types.
  • UI primitives come from HeroUI: <Button>, <Input>, <Modal> and so on, never a raw <button> or a home-made spinner. Icons come from @icons, never Unicode symbols such as arrows or check marks.
  • Global state uses Zustand stores.

Commits

Commit messages and pull request titles follow Conventional Commits.

Next

Commit messages

The format, the allowed types and examples.