# Code style

Conventions for this repo. Read this before writing code here, including any
AI assistant picking the work up in a new session.

## Comments

Do not write comments.

The code should carry its own meaning through names, structure and small
functions. No file headers, no JSDoc blocks, no "why" essays above a branch, no
section banners.

If something genuinely cannot be understood from the code, that is a signal the
code needs restructuring, not annotating. Where a decision has to be recorded —
a schema choice, an external system's quirk, a rejected approach — it belongs in
a markdown file under `docs/` or a module `README.md`, not in the source.

Exceptions, kept rare:

- `eslint-disable` / `@ts-expect-error` directives, which have to sit inline
- a licence header where a dependency requires one

## Structure

- Small functions with precise names. A function long enough to want a comment
  explaining its middle should be two functions.
- One responsibility per file. A component renders; a hook holds state; a repo
  talks to a database; a service holds rules.
- Derive names from the domain, not the mechanism: `blacklistedMemberNumbers`,
  not `strArr`.
- Early return over nested conditionals.
- Keep a module's public surface narrow — export what callers need, nothing
  else.

## TypeScript

- Explicit types on exported functions and on anything crossing an app
  boundary; inference inside.
- `type` for object shapes, `interface` only when declaration merging is wanted.
- No `any` in new code except where an untyped external schema forces it, as in
  the member DB repositories.
- Null over undefined for "this value is absent and that is meaningful".

## React / console

- Hooks at the top of the component, above any early return.
- Mantine components and theme tokens; no hardcoded colours or spacing values.
- Shared visual language lives in `routes/promo-code-campaigns/_components`
  (`StatTiles`, `FilterDrawer`, `promo.module.css`). Reuse it rather than
  restyling something to match.
- Filter and view state belongs in the URL when it changes what is shown, and
  in session storage when it is a reading preference.

## Core

- Controllers parse and respond; services hold logic; repositories hold SQL.
- The Updot member DB is production and read-only — SELECT only. Anything
  derived goes in core2 Postgres.
- Firestore `event-tracking` is read-only.
- Every migration has a working `down`.

## Documentation

Module-level notes go in a `README.md` beside the code, covering what the module
assumes about its data, which environment variables it reads, and decisions a
future reader would otherwise re-litigate. `docs/` holds cross-cutting documents
like this one.
