KIS-TOiR/generation/backend-generation.md

Backend Generation Process

Backend generation follows a pipeline aligned with runtime, auth, and validation docs:

DSL ↓ CLI scaffolding ↓ backend code generation ↓ auth generation ↓ runtime infrastructure ↓ database runtime ↓ migration ↓ seed ↓ validation

Follow:

• backend/architecture.md
• backend/runtime-rules.md
• backend/prisma-rules.md
• backend/prisma-service.md
• backend/database-runtime.md
• backend/seed-rules.md
• backend/service-rules.md
• auth/keycloak-architecture.md
• auth/backend-auth-rules.md
• auth/keycloak-realm-template-rules.md

---

Step 1 — Parse DSL

Read DSL inputs and extract:

• entities
• attributes, including the actual primary key attribute per entity
• enums
• foreign keys

The generator must treat auth as default runtime infrastructure, not as a DSL feature toggle.

---

Step 2 — CLI scaffolding

Use official CLIs before generating backend code:

• NestJS project scaffold in server/ (see generation/scaffolding-rules.md)
• install backend dependencies:
  • @prisma/client
  • prisma
  • @nestjs/config
  • jose
  • seed runner when needed by the chosen package tooling

The generator must not use deprecated Keycloak-specific Node adapters such as keycloak-connect.

---

Step 3 — Core backend code generation

Generate backend source artifacts:

1. Prisma schema (server/prisma/schema.prisma) from the domain DSL:
   • attributes
   • primary keys
   • relations
   • enums
2. NestJS modules per entity:
   • module
   • controller
   • service
3. DTO files:
   • create-entity.dto.ts
   • update-entity.dto.ts
   • entity.response.dto.ts (or equivalent)
4. PrismaService:
   • implement OnModuleInit
   • call await this.$connect() in onModuleInit()
   • do not use a beforeExit hook
5. Service update methods:
   • sanitize update payload before Prisma
   • remove id, the entity primary key, and readonly attributes from data
   • do not pass the raw request body directly to prisma.*.update()

Use mapping rules from backend/prisma-rules.md:

• DSL decimal -> DTO string
• DSL date -> DTO string (ISO)

---

Step 4 — Backend auth generation

Generate auth infrastructure as part of the normal backend output. Auth must not be deferred to a manual post-step.

Required generated auth artifacts:

• server/src/auth/auth.module.ts
• JWT auth guard
• roles guard
• @Public() decorator
• @Roles() decorator
• typed authenticated principal interface
• typed auth-aware config validation in server/src/config/

JWT verification rules:

• verify JWTs with issuer, audience, and JWKS
• use a standards-based library such as jose
• resolve JWKS in this exact order:
  1. explicit KEYCLOAK_JWKS_URL
  2. OIDC discovery
  3. ${issuer}/protocol/openid-connect/certs

RBAC rules:

• extract authorization roles only from realm_access.roles
• do not infer roles from other claims
• apply CRUD defaults by HTTP method:
  • GET -> viewer, editor, admin
  • POST, PATCH, PUT -> editor, admin
  • DELETE -> admin
• mark /health as public with @Public()

Controller generation rules:

• generated CRUD controllers must receive auth decorators by default
• path params must still use the actual entity primary key name (:id, :code, etc.)
• public routes must be explicit rather than implicit

---

Step 5 — Runtime infrastructure

Generate backend runtime config files:

• server/.env
• server/.env.example
• server/src/config/* typed validation helpers
• server/package.json lifecycle:
  • "postinstall": "prisma generate"
• server/package.json Prisma seed:
  • "prisma": { "seed": "ts-node prisma/seed.ts" } (or tsx equivalent if that is the chosen project standard)

The generated backend env contract must include:

• PORT
• DATABASE_URL
• CORS_ALLOWED_ORIGINS
• KEYCLOAK_ISSUER_URL
• KEYCLOAK_AUDIENCE
• KEYCLOAK_JWKS_URL (optional)

Fail-fast config rule:

• backend startup must fail fast when required auth or database env vars are missing
• the generator must not silently fall back to production auth values in code

Commands that must be supported and documented:

• npx prisma generate
• npx prisma migrate dev
• npx prisma db seed

---

Step 6 — Database runtime

Create docker-compose.yml at the project root with PostgreSQL only.

Minimum required compose characteristics:

• services.postgres
• image: postgres:16
• ports: ["5432:5432"]

Credentials and database name in compose must match DATABASE_URL.

Keycloak must remain an external runtime dependency and must not be added to docker-compose.yml in this repository.

---

Step 7 — Migration

Apply schema to the development database:

cd server
npx prisma migrate dev

---

Step 8 — Seed

Run development seed:

cd server
npx prisma db seed

Seed file location: server/prisma/seed.ts.

---

Step 9 — Validation

Run runtime, auth, and contract checks from generation/post-generation-validation.md, including:

• docker-compose exists and DB container starts
• Prisma lifecycle commands succeed
• seed runs
• /health responds without auth
• protected routes reject unauthenticated requests with 401
• authenticated users with insufficient role receive 403
• React Admin-compatible API responses include id for every record