Getting Started with Development

Welcome to the RiskFlow Developer's Guide. This guide covers the monorepo layout, local setup, and where to find API reference material.

Project structure

RiskFlow is a pnpm 10 + Turborepo monorepo (Node ≥ 22):

apps/
  backend/   NestJS 10 API (Prisma 7 + PostgreSQL)
  frontend/  React 19 + Vite SPA
packages/
  permissions-utils/   Shared RBAC helpers
  types/               Shared DTO/domain types
docs/                  Docusaurus site (@riskflow/docs)

Prerequisites

• Node.js ≥ 22
• pnpm 10 (corepack enable recommended)
• Docker and Docker Compose (PostgreSQL)

Installation

pnpm install
docker-compose up -d
pnpm --filter @riskflow/backend db:migrate
pnpm --filter @riskflow/backend db:seed

Running locally

# Backend + frontend
pnpm dev

# Backend only
pnpm --filter @riskflow/backend dev

# Frontend only
pnpm --filter frontend dev

# Documentation site (this site)
pnpm dev:docs

The docs dev server runs at http://localhost:3456/docs/ (port 3456 avoids conflicting with the NestJS backend on 3000).

API documentation

The canonical API reference is the NestJS Swagger UI generated from apps/backend at runtime. It is available in development only (when NODE_ENV is not production):

1. Start the backend: pnpm --filter @riskflow/backend dev
2. Open Swagger UI at http://localhost:3000/api/docs
3. REST endpoints are served under /api/v1

Swagger reflects the live NestJS controllers, DTOs, and guards. Use it for all new integrations.

Architecture decisions

Tenancy, vendor identity, and error semantics are documented as ADRs in this site:

• ADR index
• ADR 003 — Vendor identity
• ADR 004 — 404 over 403

Domain vocabulary also lives in CONTEXT.md at the repo root.

Common commands

Task	Command
Type-check all workspaces	pnpm type-check
Build (Turbo-cached)	pnpm build:turbo
Backend tests	pnpm --filter @riskflow/backend test
Frontend tests	pnpm --filter frontend test
Build docs	pnpm build:docs