KIS-TOiR/prompts/runtime-rules.md

Runtime Rules

Use this document during the Preparation / Discovery and Auth / Runtime / Realm stages defined in prompts/general-prompt.md.

Purpose

Define the runtime topology, environment defaults, scaffold expectations, and bootstrap sequence for a buildable generated workspace.

Mandatory Inputs

• prompts/general-prompt.md
• prompts/auth-rules.md when runtime changes affect auth defaults or seams
• current repository runtime/auth defaults

api-summary.json is an auxiliary artifact only. Refresh it when validator/tooling requires freshness checks or when a compact inventory helps discovery. Do not treat it as the runtime source of truth.

Expected Outputs

• docker-compose.yml
• server/.env.example
• client/.env.example
• a buildable NestJS workspace under server/
• a buildable Vite React TypeScript workspace under client/
• any validator-required auxiliary artifacts such as api-summary.json

Baseline Runtime Topology

• server/ is the backend output path
• client/ is the frontend output path
• Docker scope stays PostgreSQL-only
• Keycloak remains external to repository runtime
• the project remains LLM-first and prompt-driven

Concrete Runtime Defaults

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

Scaffold Expectations

• new or repaired backend workspaces start from the official Nest CLI
• new or repaired frontend workspaces start from the official Vite React TypeScript CLI
• Prisma initialization uses the official Prisma CLI when relevant
• the LLM may customize generated code after scaffold creation, but must not replace official initialization with ad hoc file creation

Runtime Bootstrap

1. import toir-realm.json into Keycloak
2. start PostgreSQL with docker compose up -d
3. from server/:
   • repair or create the workspace with official Nest CLI if needed
   • install dependencies
   • run Prisma commands required by the schema stage
   • run npm run build
   • run npm run start
4. from client/:
   • repair or create the workspace with official Vite CLI if needed
   • install dependencies
   • run npm run build
   • run npm run dev

Completion Expectations

Runtime preparation is incomplete if any of the following is true:

• server/ is missing or not buildable as a NestJS workspace
• client/ is missing or not buildable as a Vite React TypeScript workspace
• framework scaffolding was hand-built instead of created or repaired from official CLIs
• shared env defaults drift from the repository auth/runtime contract
• runtime success is claimed without actual build verification