ThreatLens documentation
Two sets of documents live here, and they are not the same kind of thing.
As-built — what the deployed system does
Derived from the code. Keep these current when behaviour changes.
| Document | Covers |
|---|
| PLATFORM.md | Session lifecycle, scoring, the ground-truth boundary, roles and cohort access, deployment |
| EVENT-CATALOG.md | The eight telemetry tables, 52 event templates, 20 detection rules |
| SCENARIO-CATALOG.md | All 30 scenarios — category, difficulty, techniques, correct verdict |
These are checked against the code by apps/api/src/common/docs/docs-in-sync.spec.ts, which
runs in the normal API test job. It fails when the counts quoted here — scenarios, templates,
rules, telemetry tables, scoring weights — stop matching source, and when the scenario tables
drift from seed.ts. After changing a scenario, run:
npm run docs:sync --workspace=apps/api
The catalogue tables are generated, so edit seed.ts rather than the table. Prose is written
by hand; the check only pins the numbers in it, not the wording.
Operational runbooks sit outside this folder: infra/RAILWAY.md and
infra/DEPLOY.md.
Design specification — what was planned
ThreatLens-Architecture.md and parts/ are the
original specification, written before the build. They are the source of the § references
that appear throughout the codebase's comments, and they remain useful for understanding why
something was designed the way it was.
They describe intent, not current behaviour. They are written in design tense ("the content
team will", "at MVP launch", "Phase 2"), and the build has since diverged — cohort staffing and
groups, platform-admin access, and the scenario catalogue have all moved on. Treat them as
history. Where they and the as-built documents disagree, the as-built documents and the code
win.
The frontend has its own pair with the same split:
apps/web/docs/ARCHITECTURE.md (superseded, carries a
banner saying so) and
apps/web/docs/THREATLENS_BACKEND_INTEGRATION.md.
