Development Guide

The rules behind these commands live in AGENTS.md; this page is the how-to.

First run

git clone https://github.com/krizaka/orochia.git && cd orochia
npm install
npm run setup        # .env + PostgreSQL 16 + migrations + seed
npm run dev          # http://localhost:3000

npm run setup is idempotent: run it again after pulling, or whenever the databases were stopped.

Clone the admin console and the design system next to this repository with npm run workspace -- clone, then npm run workspace -- status shows the three repositories at a glance.

Accounts of the development seed

The database

PostgreSQL runs in the orochia-postgres-dev container (deploy/docker/docker-compose.dev.yml, data in a named Docker volume).

db:reset, db:restore and db:psql work only on the local container: they refuse NODE_ENV=production and any DATABASE_URL that does not point at this machine.

Changing the schema

1. Edit the tables in packages/db/src/schema/*.ts (and their relations in schema/index.ts).
2. npm run db:generate -- --name short_description writes packages/db/drizzle/NNNN_short_description.sql.
3. Read the SQL. Renames are generated as drop + add — rewrite them as ALTER … RENAME by hand when data must survive.
4. npm run db:migrate, then npm run db:check.
5. npm run docs:generate — docs/DATABASE.md follows the schema.
6. Commit the schema, the migration and the docs together. Never edit a migration that was already applied anywhere.

The seed

packages/db/src/seed.ts builds a small, coherent platform that exercises every feature. It is idempotent (rows are keyed by e-mail, Bunny video id, gateway reference…), so npm run db:seed can run any time; it writes ledger rows exactly as settlement does (10 % platform fee) and refuses to run with NODE_ENV=production.

Tests

npm run check                    # lint + types + unit tests + generated docs up to date
npm run db:reset -- --yes        # the scenarios change data: start them from the seed
npm run test:e2e                 # needs the app running (npm run dev); OROCHIA_URL to target another one

Environment

One .env at the repository root (created by npm run setup from .env.example). Leave the payment and Bunny variables empty locally: with OROCHIA_DEMO_MODE=true unlocks settle immediately when no gateway is configured, and playback answers that streaming is not configured. In production every secret is mandatory (see Deployment).

Troubleshooting