Local Development

Requirements

• Node.js 26.4.0 or later
• pnpm 11.7.0 or later

Setup

Install dependencies and initialize the database:

pnpm install
pnpm run db:reset

db:reset creates and seeds a local SQLite database at packages/database/prisma/dev.db. This file is gitignored.

Running Services

Start all services at once

pnpm run dev:services

Service	Endpoint
Admin BFF	http://127.0.0.1:4010
Entitlement Service	http://127.0.0.1:4317
Identity Service	http://127.0.0.1:4320

Start a single service

pnpm run dev:admin-bff         # Admin BFF only (port 4010)
pnpm run dev:entitlement-service  # Entitlement Service only (port 4317)
pnpm run dev:identity-service     # Identity Service only (port 4320)

Once running, you can access:

URL	Description
http://127.0.0.1:4010/healthz	Admin BFF health check
http://127.0.0.1:4010/graphiql	Admin BFF GraphiQL explorer
http://127.0.0.1:4317/docs	Entitlement Service Swagger UI
http://127.0.0.1:4317/graphiql	Entitlement Service GraphiQL
http://127.0.0.1:4320/docs	Identity Service Swagger UI

The Admin BFF GraphQL endpoint (/graphql) accepts POST requests only. Use GraphiQL for browser-based exploration.

To disable Swagger UI and GraphiQL (e.g., for production-like testing), set ENABLE_INTERNAL_DOCS=false or NODE_ENV=production.

Building Documentation

Build and preview the VitePress documentation site locally:

pnpm run docs:build
pnpm run docs:preview

docs:build regenerates OpenAPI specs, GraphQL SDL, Redoc pages, and the VitePress static site.

Verification

Run the full verification suite before committing:

pnpm run lint
pnpm run typecheck
pnpm run test:all
pnpm run build:all

Or run everything at once:

pnpm run verify