Developer Workflow

This document describes the developer workflow for running a generated fullstack application locally. The generator must produce a project that supports this workflow so the app is fully runnable after generation, including authentication.

This workflow assumes the project was generated from domain/*.dsl plus optional non-duplicating overrides only. Developers must not need to prepare separate DTO/API/UI DSL inputs before running the app.

Prerequisites

Node.js (LTS, e.g. 18+)
npm
Docker and Docker Compose (for the development database)
External Keycloak server reachable by the generated frontend and backend

The generated project must not require the developer to invent auth wiring manually after generation.

Workflow Steps

1. Prepare Keycloak and env files

From the project root, the generated project must include:

root-level generated Keycloak realm import artifact
- repository default example filename: toir-realm.json
server/.env.example
client/.env.example

Required workflow:

Copy the generated env examples to real env files as needed.
Fill all required backend and frontend auth variables.
Import or verify the generated Keycloak realm import artifact in the external Keycloak server before starting the app.

The generator must document that auth config is fail-fast. Missing required auth env vars must stop startup instead of silently falling back to production values in code.

2. Start the database

From the project root:

docker compose up -d

This starts the PostgreSQL container defined in docker-compose.yml. Wait a few seconds for the database to accept connections.

Verify if needed:

docker compose ps

3. Backend setup and start

From the server directory:

cd server
npm install
npx prisma generate
npx prisma migrate dev
npx prisma db seed
npm run start

npm install installs dependencies and runs postinstall when configured.
npx prisma generate explicitly generates Prisma client.
npx prisma migrate dev creates/applies migrations.
npx prisma db seed inserts minimal development data.
npm run start starts the NestJS backend.

The API should be available at the configured port (for example http://localhost:3000).

Verify:

curl http://localhost:3000/health

Expected: { "status": "ok" } (or equivalent).

Generated backend behavior must also ensure:

protected CRUD routes require authentication by default
insufficient roles result in 403
/health remains public

4. Frontend setup and start

In a separate terminal, from the project root:

cd client
npm install
npm run dev

npm install installs frontend dependencies including keycloak-js.
npm run dev starts the Vite dev server (for example http://localhost:5173).

Open the frontend URL in a browser. The generated React Admin app must:

initialize Keycloak before render
use redirect-based login only
authenticate against the configured Keycloak realm/client
call the backend with bearer tokens through the shared request seam

Summary

Step	Command / location
Prepare Keycloak + env	Fill `server/.env` and `client/.env`; import or verify the generated realm import artifact
Start database	From root: `docker compose up -d`
Backend setup/start	`cd server && npm install && npx prisma generate && npx prisma migrate dev && npx prisma db seed && npm run start`
Frontend setup/start	`cd client && npm install && npm run dev`

The generator must produce all required artifacts so that this workflow succeeds:

docker-compose
env examples
schema
migrations
seed
health endpoint
frontend auth integration
backend auth infrastructure
root-level Keycloak realm import artifact

3.8 KiB Raw Blame History