KIS-TOiR/prompts/runtime-rules.md

Runtime Rules

This repository keeps the current LLM-first CRUD generation architecture as the primary working baseline and strengthens the existing pipeline instead of replacing it.

Baseline runtime topology

• server/ is the active backend target output path.
• client/ is the active frontend target output path.
• Docker scope remains PostgreSQL only.
• Keycloak remains external to the repository runtime.
• The project remains LLM-first: markdown knowledge blocks in prompts/ orchestrate generation, while active generated/maintained code lives in server/ and client/.

Required input and derived artifacts

• Source of truth:
  • domain/*.dsl
• Required derived artifacts:
  • domain-summary.json
  • root-level *-realm.json

domain-summary.json exists to stabilize generation and validation; it must be regenerated from the DSL and treated as non-authoritative.

Output contract

The strengthened baseline must produce and keep aligned:

• server/prisma/schema.prisma
• backend/frontend env examples
• backend/frontend auth seams
• root .gitignore, server/.gitignore, client/.gitignore
• docker-compose.yml
• domain-summary.json
• root-level realm import artifact

Concrete runtime examples

Use these as the baseline examples for this project unless the prompt explicitly overrides them:

• Backend:
  • PORT=3000
  • DATABASE_URL="postgresql://postgres:postgres@localhost:5432/toir"
  • CORS_ALLOWED_ORIGINS="http://localhost:5173,https://toir-frontend.greact.ru"
  • KEYCLOAK_ISSUER_URL="https://sso.greact.ru/realms/toir"
  • KEYCLOAK_AUDIENCE="toir-backend"
• Frontend:
  • VITE_API_URL=http://localhost:3000
  • VITE_KEYCLOAK_URL=https://sso.greact.ru
  • VITE_KEYCLOAK_REALM=toir
  • VITE_KEYCLOAK_CLIENT_ID=toir-frontend

These example values come from the already working runtime shape and are preferred over local-only Keycloak placeholders.

Runtime bootstrap

1. Import the root-level realm artifact into Keycloak.
2. Start PostgreSQL with docker compose up -d.
3. From server/ run:
   • initialize or repair the workspace with official Nest CLI scaffolding if required before generating domain code
   • npm install
   • npx prisma generate
   • npx prisma migrate dev
   • npx prisma db seed
   • npm run build
   • npm run start
4. From client/ run:
   • initialize or repair the workspace with official Vite React TypeScript scaffolding if required before generating app code
   • npm install
   • npm run build
   • npm run dev

Recovery and completion rules

• Repair degraded framework workspaces before applying any new domain-derived generation changes.
• Do not mark generation complete while server/ or client/ remains non-buildable.
• If dependency installation has not happened yet, buildability may be reported as skipped, but it must never be reported as green without verification.
• Runtime/bootstrap instructions are reusable project baseline rules; TOiR names remain examples, not the only supported domain project.

Scaffold expectations

• NestJS workspace creation should follow the official Nest CLI path for new applications and resource scaffolding.
• Vite frontend creation should follow the official Vite create-vite path for React TypeScript applications.
• The LLM may customize generated code after scaffold creation, but must not replace official workspace initialization with ad hoc file creation.

Common generation failures to avoid

• starting feature generation before scaffold repair
• leaving deleted framework config files unrepaired because the current diff looks smaller
• accepting a form-only validation pass while buildability is unknown
• binding runtime rules to one project-specific DSL filename instead of domain/*.dsl

Baseline intent

• No new generator engine
• No compiler platform
• No planner/emitter/runtime redesign
• Only the current LLM-first pipeline, strengthened by summary, realm, and validation artifacts