# Backend Runtime Rules

This document defines runtime configuration requirements for the generated backend. Generators must produce a project that runs without errors when these rules are followed.

---

# Environment Variables

The backend **must** have a `.env` file at the project root (e.g. `server/.env` or backend package root). This file must **not** be committed with real credentials; provide an example instead (e.g. `.env.example`).

## Required variables

| Variable             | Required | Description |
| -------------------- | -------- | ----------- |
| PORT                 | Yes      | Backend listen port |
| DATABASE_URL         | Yes      | PostgreSQL connection string for Prisma |
| CORS_ALLOWED_ORIGINS | Yes      | Comma-separated SPA origins allowed to call the API |
| KEYCLOAK_ISSUER_URL  | Yes      | Keycloak issuer URL used for JWT verification |
| KEYCLOAK_AUDIENCE    | Yes      | Backend audience/client expected in access tokens |
| KEYCLOAK_JWKS_URL    | No       | Optional explicit JWKS URL |

## Example

```env
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"
# KEYCLOAK_JWKS_URL="https://sso.greact.ru/realms/toir/protocol/openid-connect/certs"
```

## Generation requirement

When generating the backend, **always** create:

1. **`.env.example`** — with placeholder DATABASE_URL and instructions.
2. **`.env`** — with local development example values so the app can start.

If the generator does not create `.env`, the first run will fail with:

```
Environment variable not found: DATABASE_URL
```

## Fail-fast requirement

The generated backend must validate required runtime and auth variables at startup.

Rules:

1. Missing required auth variables must stop startup immediately.
2. The generated backend must not silently fall back to production auth settings in code.
3. Auth env validation must be implemented explicitly in generated config/bootstrap code.

---

# Authentication Runtime Rules

The generated backend must verify JWTs against Keycloak using:

- issuer
- audience
- JWKS

JWKS resolution priority must be exactly:

1. explicit `KEYCLOAK_JWKS_URL`
2. OIDC discovery
3. `${issuer}/protocol/openid-connect/certs`

The generated backend must extract authorization roles only from `realm_access.roles`.

---

# Prisma Client Generation

After the Prisma schema is generated or modified, the Prisma client must be generated.

## Command

```bash
npx prisma generate
```

## Lifecycle rule

Add to generated `package.json` so that `prisma generate` runs after every `npm install`:

```json
{
  "scripts": {
    "postinstall": "prisma generate"
  }
}
```

This ensures that after cloning or installing dependencies, the Prisma client is available without a manual step.

**Note:** Path may need to be adjusted if Prisma schema lives in a subfolder (e.g. `prisma generate` is typically run from the package root where `prisma/schema.prisma` exists).

---

# Database Migration

The generation process must document and support database migration.

## Command

```bash
npx prisma migrate dev
```

Run after:

1. Prisma schema has been generated or updated.
2. `npx prisma generate` has been run.

## Generation requirement

1. Include migration in the backend generation pipeline (see `generation/backend-generation.md`).
2. Document in README or post-generation validation that the user must run `npx prisma migrate dev` before first run (or provide a setup script that runs it).

---

# CORS Rules

The generated backend must support the SPA -> API bearer-token model explicitly.

Rules:

1. Use `CORS_ALLOWED_ORIGINS` as the allowed origin list.
2. Allow at minimum these example origins in `.env.example`:
   - `http://localhost:5173`
   - `https://toir-frontend.greact.ru`
3. Allow `Authorization` and JSON content headers.
4. Expose `Content-Range` because React Admin depends on it.
5. Do not enable credentials by default.

---

# Summary

| Requirement             | Action |
| ----------------------- | ------ |
| Runtime env             | Create `.env` and `.env.example` with DB, auth, and CORS variables |
| Fail-fast config        | Validate required auth/runtime variables at startup |
| Prisma client           | Run `npx prisma generate`; add `postinstall` script |
| Database schema         | Document/run `npx prisma migrate dev` after schema generation |
| JWT verification        | Use issuer + audience + JWKS with explicit resolution priority |
| Role extraction         | Use only `realm_access.roles` |
| CORS                    | Support SPA -> API bearer flow and expose `Content-Range` |