toir-automatization/.claude/worktrees/goofy-haslett/prompts/runtime-rules.md

Runtime Rules

Use this document during the A. Discovery, D. Shared Platform Scaffold, and F. Integration stages defined in prompts/general-prompt.md.

Purpose

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

Ownership rule:

• the parent owns runtime/deploy skeletons, shared platform wiring, and env/runtime conventions
• specialized generators may perform only minor resource-aware integration repairs inside explicitly delegated zones
• do not redesign shared deploy/runtime behavior from a resource generator

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/Dockerfile
• client/Dockerfile
• client/nginx/default.conf
• server/.env.example
• client/.env.example
• server/docker-entrypoint.sh
• db-seed/Dockerfile
• db-seed/import.sh
• 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
• compose-managed services are postgres, server, db-seed, and client
• the internal database container remains PostgreSQL-only
• Keycloak remains external to repository runtime
• the project remains LLM-first and prompt-driven
• runtime/deploy artifacts are first-class deliverables, not optional examples

Proven-Good Runtime Baseline

• preserve the current server/Dockerfile, client/Dockerfile, client/nginx/default.conf, docker-compose.yml, server/docker-entrypoint.sh, db-seed/Dockerfile, and db-seed/import.sh behavior unless a contract change requires a targeted update
• treat docker-compose.yml, the Dockerfiles, nginx config, env templates, and realm import as deploy-facing outputs that must stay coherent with the auth and validation rules
• the runtime stage may create or repair all files named in Expected Outputs; do not describe them as optional support files

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

Runtime Toolchain Baseline

• Runtime Node.js baseline: 22.12.0 or newer within the Node 22 LTS line
• Package manager baseline: npm only
• Commit and preserve package-lock.json files for server/ and client/
• Do not introduce pnpm-lock.yaml, yarn.lock, or Bun-specific package-manager assumptions during regeneration
• After CLI scaffolding, replace floating scaffold dependency ranges with the repository-approved exact versions from AGENTS.md and prompts/general-prompt.md

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
   • apply Prisma migrations when they exist; use db push only as a bootstrap fallback in fresh environments without migrations
   • 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

Prisma Migration Policy At Runtime

• Current accepted repository state: no committed server/prisma/migrations/ directory is required for local bootstrap.
• Current runtime behavior therefore preserves the proven-good fallback in server/docker-entrypoint.sh:
  • use prisma migrate deploy when committed migrations exist
  • otherwise use prisma db push
• Preferred target policy for shared and production environments: commit reviewed Prisma migrations and let runtime use prisma migrate deploy.
• Treat migration absence as accepted temporary technical debt, not as the long-term deploy standard.

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
• runtime/deploy outputs named in this file are missing or incoherent with the auth/runtime contract