KIS-TOiR/prompts/backend-rules.md

Backend Rules

The backend remains derived from domain/*.dsl inside the existing LLM-first pipeline. No compiler platform or generator engine is introduced.

Backend scaffold baseline

• Start backend initialization from the official NestJS CLI workspace, not from manually created files.
• The backend must remain compatible with standard Nest workspace tooling such as nest build and nest start.
• Preserve the core Nest workspace files generated by the CLI, especially:
  • server/tsconfig.json
  • server/tsconfig.build.json
  • server/nest-cli.json
  • server/src/main.ts
  • server/src/app.module.ts
• For domain resources, prefer official Nest CLI generation patterns for modules/controllers/services/resources and then adapt the generated code to Prisma and auth requirements.
• Do not delete required Nest workspace files just because the LLM can inline a smaller custom structure.

Forbidden backend generation patterns

• Do not bootstrap server/ by hand-writing a pseudo-Nest project from memory.
• Do not remove tsconfig.json, tsconfig.build.json, or nest-cli.json after generation.
• Do not replace standard Nest package scripts with ad hoc commands that break nest build or nest start.
• Do not continue CRUD generation on top of a degraded backend workspace without repairing the workspace first.

Domain-derived output

• domain/*.dsl is the source of truth for entities, fields, primary keys, foreign keys, and enums.
• domain-summary.json is a derived artifact used to stabilize LLM generation and validation. It must never replace the DSL as the source of truth.
• Each entity becomes:
  • a Prisma model
  • a NestJS module
  • a controller
  • a service
  • create/update DTOs

DTO and Prisma mapping

• decimal -> Prisma Decimal, DTO/API string
• date -> Prisma DateTime, DTO/API string
• Enums remain string-valued in DTO/API contracts

CRUD and natural-key invariants

• CRUD routes use the real primary key name in the path.
• Every API record returned to React Admin must include id.
• For entities whose primary key is not id, the backend must map the real key to id.
• Natural-key list/sort logic must never build ORM orderBy against a fake physical id.

Service invariants

• Never pass raw update DTOs into Prisma update data.
• Remove id, the real primary key, and readonly fields from update payloads before calling Prisma.
• Keep PrismaService lightweight:
  • extend PrismaClient
  • implement OnModuleInit
  • call $connect()
  • do not use beforeExit

Filtering contract

• List endpoints must support React Admin query parameters:
  • _start, _end, _sort, _order
  • arbitrary field filters from query string
  • q for reference autocomplete search
• String/text search filters may use contains with case-insensitive mode.
• Foreign key filters must use exact-match semantics (no contains for FK scalar keys).
• Enum filters must support both single and repeated query params:
  • status=Draft
  • status=Draft&status=Approved
• Repeated enum params must map to Prisma { in: [...] }.
• Sorting must use real model scalar fields only; natural-key entities must not fallback to fake physical id.

Reproducibility invariants

• A freshly generated backend must be bootstrappable with ordinary Nest + Prisma commands from prompts/runtime-rules.md.
• Missing TypeScript or Nest workspace config is a generation failure, not an acceptable simplification.
• The baseline backend should fail only on missing runtime dependencies or env values, not because the Nest workspace itself is incomplete.

Recovery rule if backend workspace degraded

• If required Nest scaffold files are missing or broken, restore the official workspace baseline before editing Prisma models, modules, controllers, services, or DTOs.
• Treat workspace repair as higher priority than feature generation, because generated domain code on top of a broken workspace is invalid baseline output.

Backend auth defaults

• GET -> viewer | editor | admin
• POST, PATCH, PUT -> editor | admin
• DELETE -> admin