Documentation · Getting started

Getting started

Run the Phase 1 stack from platform/: FastAPI (backend/nims), PostgreSQL, Prisma for migrations, and the React + Vite console.

Prerequisites

• uv (recommended) or pip + a virtualenv under backend/
• Node.js for Prisma CLI and the web app (npm install in platform/ and web/)
• PostgreSQL (e.g. Docker Compose in platform/)

Configure and migrate

1. From platform/, copy .env.example to .env and set DATABASE_URL and JWT_SECRET.
2. Start Postgres (for example docker compose up -d in platform/).
3. Install JS deps: npm install in platform/ and npm install --prefix web (or npm ci as in CI).
4. Run npx prisma migrate dev and npx prisma generate as needed.
5. Seed: make seed or npm run db:seed (runs nims-seed via uv).

Run the API

From platform/:

make sync          # uv sync in backend
make api           # or: uv run --directory backend nims-api

Defaults: reload on, host 0.0.0.0, port 8080 (override with API_HOST, API_PORT, NIMS_RELOAD=false).

• OpenAPI / Swagger: http://localhost:8080/docs
• OpenAPI JSON: http://localhost:8080/docs/json
• GraphiQL: http://localhost:8080/graphql
• Authenticate with seed-printed API tokens: Authorization: Bearer … on GET /v1/me

Operator console (web UI)

Build the SPA so the API can serve it from web/dist at /app/: npm run web:build. For Vite dev only: npm run web:dev.

Note: npm run dev from platform/ starts the Python API, not Vite—use web:dev for the React dev server.

CI parity

From platform/, npm run ci runs ESLint, web typecheck, web build, Ruff, and pytest (uv). See .github/workflows/platform-ci.yml for the GitHub Actions recipe.

← Back to documentation