prospector/docs/STANDARDS.md

Engineering Standards — Quinn Prospector

The house rules for this repo. Project-specific; inherits the workspace-wide TypeScript standards (~/.claude/instructions/typescript-code-standards.md) and the no-stubs / SOLID / DRY commandments. When in doubt, match the existing src/markets/ module — it is the reference implementation of these rules.

1. Feature-sliced architecture (backend src/)

One NestJS feature module per domain (markets/, prospects/, reports/, campaigns/, …). A module owns one bounded concern and exposes it through:

<feature>/
  <feature>.module.ts        — NestJS wiring (imports, providers, exports)
  <feature>.controller.ts    — HTTP surface only (no logic)
  <feature>.service.ts       — I/O + orchestration (DB, other services)
  <pure>.ts                  — pure domain logic, one concern per file
  dto/*.ts                   — class-validator request DTOs
  *.test.ts                  — co-located Vitest, next to the unit it tests
  index.ts                   — public API manifest (the only cross-module entry)
  README.md                  — what/why for the feature (see §4)

• No cross-feature reach-in. Import another feature only through its index.ts / its exported *Module. Never deep-import its internals.
• New domain → new module, not a new file bolted onto an existing one.

2. Separate pure logic from I/O

Domain logic is pure functions in their own files (registry.ts, locality.ts, tour-window.ts, timezone.ts, stats.ts). The *.service.ts does I/O (SQL, HTTP) and calls the pure layer. This is why the aggregations are exhaustively unit-testable with no database.

• Pure files: no @Injectable, no repo, no Date.now() baked in — take now as a parameter so tests are deterministic.
• Reuse, don't re-implement. markets/stats.ts composes reports/reports.ts#buildReport rather than copying the funnel logic. Extract shared logic to a pure module both features import.

3. Type & quality discipline

• strict: true, no any, no as unknown as, no @ts-ignore.
• Explicit return types on every exported function.
• Discriminated unions over boolean flags; make illegal states unrepresentable.
• No stubs / TODOs / fallbacks in production code — complete or fail loudly.
• No dead code — delete it; no _unused, no "kept for migration" re-exports.
• File size: soft 300 LOC, hard 500 (tests exempt). Split god files.
• Validate all inputs at the edge (DTOs + class-validator); handle every error.

4. Filesystem as modular documentation

Documentation lives next to the code it describes, not in a far-off wiki.

• Every feature module has a README.md stating: what it does, the domain model + key decisions (and what was deliberately rejected), a file table (one concern per row), and the HTTP surface. src/markets/README.md is the template.
• src/README.md is the module index — one line per feature, kept current.
• Add/refresh a module's README when you build or materially change it. Do not mass-generate hollow READMEs — an empty doc is worse than none.
• Comments explain why, not what. Code is the source of truth for "what".

5. Testing

• Vitest, co-located *.test.ts. Full-sentence it('…') names.
• Cover the pure layer exhaustively (it's cheap and deterministic).
• Deterministic: pass now/seeds in; no wall-clock, no network in unit tests.
• Green bar before commit: npm run typecheck && npm test && npm run build.

6. Persistence & migrations

• Schema changes are numbered SQL migrations in migrations/ (000N_<name>.sql).
• TypeORM entities in src/entities/ mirror the schema; export via src/entities/index.ts.
• Mutating an existing table → read-modify-write the full row; never blind upsert.

7. Git

• Atomic, scoped commits: git commit -- <paths>, never blind git add -A.
• Conventional-commit subject; end with the Co-Authored-By trailer.
• Verify before commit (§5), push after (fast-forward only).
• Branch: work on main directly (this repo's convention).

8. Frontend (web/)

• Vite + React, served same-origin by this backend; installs as a Chrome PWA.
• One view per web/src/views/*.tsx, wired in App.tsx (NAV + router + titles).
• All HTTP through web/src/api.ts (typed apiFetch); no inline fetch.
• Reuse existing CSS classes (card, funnel, vchart, bars) before adding new.
• designs/*.html are the visual/behavior contract — match them.