3.3 KiB
3.3 KiB
Source-of-Truth Hierarchy
This document is the authoritative reference for which files own which decisions.
Tier 1: Authoritative sources (hand-authored; never generated)
domain/*.api.dsl
Single source of truth for the entire domain and API contract:
- Entity names and structure
- Attribute names, scalar types, descriptions
- Primary keys (including natural string keys)
- Foreign keys and relations
- Enum definitions and their values
- Database-level constraints:
is required,is unique,default - DTO shapes per operation (Create, Update, Read, ListRequest, ListResponse)
- Which fields appear in each DTO and with what TypeScript modifier (
!or?) - HTTP method and path for each endpoint (via
label "METHOD /path") - Endpoint names (camelCase identifiers)
- Pagination request/response contract
Drives: server/prisma/schema.prisma, server/src/modules/, client/src/resources/,
server/src/app.module.ts, client/src/App.tsx.
prompts/*.md and AGENTS.md
Authoritative for:
- Agent generation workflow and reading order
- Auth seam patterns (Keycloak, JWT, PKCE S256, JWKS resolution chain)
- Runtime conventions (env examples, docker-compose topology)
- Framework scaffold baseline requirements (NestJS CLI, Vite React TypeScript)
- Filtering and sorting contract
- Naming conventions and implicit rules (pluralization, sort field priority, type mappings)
- Mutation boundaries (what agents must not overwrite)
Tier 2: Deterministic derivatives (never edit manually)
| File | Generated from | Command |
|---|---|---|
api-summary.json |
domain/*.api.dsl |
npm run generate:api-summary |
These files are regenerated from their sources. Manual edits are overwritten on the next generation run.
Tier 3: LLM-generated artifacts (never edit manually after generation)
| Zone | Generated from |
|---|---|
server/prisma/schema.prisma |
domain/*.api.dsl + prompts/prisma-rules.md |
server/src/modules/<entity>/ |
domain/*.api.dsl + prompts/backend-rules.md |
client/src/resources/<entity>/ |
domain/*.api.dsl + prompts/frontend-rules.md |
server/src/app.module.ts |
Module list derived from api.dsl api blocks |
client/src/App.tsx |
Resource list derived from api.dsl api blocks |
To change these files: update domain/*.api.dsl and regenerate.
Tier 4: Handwritten (not generated; not derived)
- Auth seams:
client/src/auth/,server/src/auth/ toir-realm.jsondocker-compose.ymlserver/.env.example,client/.env.example- Framework config:
nest-cli.json,tsconfig*.json,vite.config.*, etc. - All
prompts/*.md,AGENTS.md,domain/dsl-spec.md,domain/*.api.dsl
Validation gate
Stage 1 — Structural gate
node tools/validate-generation.mjs --artifacts-only
Verifies that generated artifacts satisfy the contracts declared in Tier 1 sources.
Stage 2 — Eval harness
npm run eval:generation
Fixture-based semantic checks from tools/eval/fixtures/.
Both stages must pass before any generation task is considered complete.