ls <relevant-dir>
find <relevant-dir> -type f | head -30

# Which files are central? (entry points often show up as most-imported)
grep -rn "from ['\"]<relevant-module>" src/ | cut -d: -f1 | sort | uniq -c | sort -rn | head -10

## `<function-name>` in `<file>:<line>`

**What it does:** one sentence.

**Inputs:** ...
**Returns:** ...
**Side effects:** (DB writes, network calls, mutations). None if pure.

**Called from:** {list of callers with file:line}.

**How it works:** paragraph walking through the body, naming the helper it delegates to.

**Gotcha (if any):** {a non-obvious thing the reader should know}.

## `<path/to/module>`

**Responsibility:** one-sentence scope — what this module owns.

**Key files:**
- `<file1>` — {what it does}
- `<file2>` — {what it does}

**Public API:** the exports, briefly.

**Depends on:** {other modules this one imports from}.
**Depended on by:** {modules that import this one}.

**How it fits in:** how a typical flow enters this module and what it hands off.

## How `<concept>` works

**What it is:** paragraph at the right level — higher than code, lower than marketing.

**The flow:** step-by-step, naming files and functions at each step.

1. Entry: request arrives at `src/api/routes/<...>.ts:<line>`.
2. Middleware: `<middleware>` runs, validating `<x>`.
3. Handler dispatches to `<service.method>`.
4. Service calls `<repository.method>` and `<external-client.method>`.
5. Response is shaped by `<mapper.method>` and returned.

**The contract:** a minimal code reference (file + line) for the shape.

**Extension points:** where to add a variant. Often a factory, a registry, or a subclass.

**Pitfalls:** 1–3 things that trip up newcomers.