Get started

Step 1: Start the database and migrate it

cd api
cp .env.example .env
uv sync
make db-up          # postgres:16 as container trovensa-db on localhost:5434, waits until healthy
make migrate        # alembic upgrade head: migration 0001 creates 32 tables and seeds the 10 personas

make db-up prints db healthy. The default DATABASE_URL is postgresql+asyncpg://app:app@localhost:5434/app; port 5434 is used because 5433 is taken on the development machine.

Step 2: Run the API and seed the illustrative program

make dev            # uvicorn app.main:app --reload on :8100

In a second shell:

cd api
curl -s localhost:8100/api/v1/health/ready     # {"status":"ok","version":"0.1.0","env":"dev","database":"ok"}
uv run python scripts/seed_illustrative.py     # organisation trovensa-demo, programs default and trv-101

The seed is idempotent. It creates organisation trovensa-demo with the program default and the program trv-101 (“Illustrative program TRV-101”), plus records whose titles start with “Illustrative:” and whose illustrative flag is true.

Step 3: Mint a development token

TOKEN=$(uv run python scripts/dev_token.py --user owner@example.com --org trovensa-demo --roles org_owner,program_owner)
curl -s -H "Authorization: Bearer $TOKEN" localhost:8100/api/v1/me | jq .

The response lists the two programs with their permissions. Development tokens are HS256 with the header kid: dev, signed with DEV_TOKEN_SECRET, and the API accepts them only when APP_ENV is dev or test. Keep the shell open; the next step needs $TOKEN.

Step 4: Run the web app in dev-identity mode

cd ../web
npm ci
cp .env.example .env.local

Edit .env.local: leave NEXT_PUBLIC_AUTH_CLIENT_ID and NEXT_PUBLIC_AUTH_AUTHORITY empty, keep NEXT_PUBLIC_API_BASE_URL=http://localhost:8100, and set NEXT_PUBLIC_DEV_TOKEN to the value of $TOKEN. Then:

npm run dev         # next dev -p 3100

Without a client id the app skips the identity provider and sends the development token as the bearer on every API call.

Step 5: Open the illustrative program

Open http://localhost:3100. The resolver reads /me, finds no last_program cookie and sends you to the first program’s home page, /p/<slug>/home. Use the program switcher in the topbar (labelled “Switch program”) to choose Illustrative program TRV-101; the URL becomes /p/trv-101/home.

The rail on the left lists Home, Evidence, Plans, Review, Progress, Setup and Organization; the panel next to it lists the sections of the selected product. Choose Evidence in the rail and Questions in the panel: the illustrative questions appear, each with the “Illustrative” label.

Step 6: Start the worker (optional)

cd ../api
make worker         # claims agent runs, sync runs and tool invocations

With the worker running, an agent action such as Compare findings on a question is queued as an agent run and completed by the fake runtime with illustrative, agent-origin findings that a person then decides on.