# Runtime Rules

<!-- prompt-version: 2.0 -->
<!-- applies-to: docker-compose.yml, server/.env.example, client/.env.example -->
<!-- validated-by: tools/validate-generation.mjs §validateRuntimeContractChecks -->

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