Local development

Requirements

Node.js 22.12 or newer
Corepack with pnpm 10
Docker Compose

From the repository root, prepare the local environment and install the workspace:

corepack pnpm dev:setup
corepack pnpm install
corepack pnpm infra:up
corepack pnpm db:migrate
corepack pnpm dev

dev:setup creates a private .env with random local-only secrets. Keep it out of Git and do not use these values for public deployments.

The local web workspace is at http://127.0.0.1:13000, the API at http://127.0.0.1:14000, the docs site at http://127.0.0.1:4321, and the Keycloak development console at http://127.0.0.1:8080. The local realm permits account registration. Product email delivery is disabled until SMTP is configured. The optional local Mailpit SMTP preview uses 127.0.0.1:1025 and its inbox UI is at http://127.0.0.1:8025.

Run the docs site alone

The documentation site does not need the API, database, worker, or Keycloak. After installing workspace dependencies:

corepack pnpm docs:dev

Astro prints a local URL, usually http://localhost:4321. Build static output with:

corepack pnpm docs:build

Workspace map

Path	Responsibility
`apps/web`	Nuxt customer and recipient workspace.
`apps/api`	NestJS REST API and OpenAPI contract.
`apps/worker`	Asynchronous work and SMTP outbox delivery.
`apps/docs`	Astro and Starlight documentation site.
`packages/domain`	Framework-independent product types.
`packages/database`	PostgreSQL schema, Drizzle client, and migrations.
`packages/credentials`	Open Badges credential and verification logic.

When changing database schema, update the Drizzle definitions and generate/review a migration. Tenant data relies on explicit organization IDs and PostgreSQL row-level security policies.

Write or update documentation

Add Markdown or MDX pages under apps/docs/src/content/docs. Keep one task or concept per page, include a short description in frontmatter, and add the page to the appropriate group in apps/docs/astro.config.mjs. Describe current behavior from the code and label unfinished capabilities clearly. Run corepack pnpm docs:build to produce the static site and its search index.