git init

backend/runtime-rules.md

@@ -0,0 +1,94 @@
+# 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                             |
+| ------------ | -------- | --------------------------------------- |
+| DATABASE_URL | Yes      | PostgreSQL connection string for Prisma |
+
+## Example
+
+```env
+DATABASE_URL="postgresql://postgres:postgres@localhost:5432/toir"
+```
+
+## Generation requirement
+
+When generating the backend, **always** create:
+
+1. **`.env.example`** — with placeholder DATABASE_URL and instructions.
+2. **`.env`** — with the same placeholder so the app can start; user replaces with real values.
+
+If the generator does not create `.env`, the first run will fail with:
+
+```
+Environment variable not found: DATABASE_URL
+```
+
+---
+
+# 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).
+
+---
+
+# Summary
+
+| Requirement     | Action                                                        |
+| --------------- | ------------------------------------------------------------- |
+| DATABASE_URL    | Create `.env` and `.env.example` with DATABASE_URL            |
+| Prisma client   | Run `npx prisma generate`; add `postinstall` script           |
+| Database schema | Document/run `npx prisma migrate dev` after schema generation |