Skip to content
Developer docs

Local development

Run the backend, frontend, and website as separate surfaces while keeping the request path and package boundaries visible.

Workspace map

The repository is a pnpm workspace. Shared contracts live in packages/shared; the Fastify backend, CLI, SDK, Next.js console, and Astro website remain separate consumers. Start with the smallest surface that exercises your change.

Run the platform

pnpm install
pnpm dev

The root development command starts the package workspace. To work on one surface in isolation:

pnpm dev:server
pnpm dev:frontend
pnpm dev:site

The API defaults to http://localhost:8080, the console to http://localhost:3000, and the public site uses Astro's local development port.

Follow one request

  1. Validate external input at the Fastify route with the shared Zod schema.
  2. Translate the request into an application service call.
  3. Let the service enforce domain rules and use injected ports for persistence or providers.
  4. Return the stable HTTP error or response contract to the caller.
  5. Use the frontend query layer or SDK rather than duplicating request logic in a view.

Common local changes

Backend

Change routes, services, repositories, agents, or configuration. Run server tests and typecheck.

Frontend

Change the console, query hooks, forms, or browser flows. Run lint, typecheck, and Playwright.

Website

Change public positioning or docs. Run the Astro build and inspect generated routes.

Configuration discipline

Copy .env.example for local work, keep credentials out of browser code and logs, and use the injected configuration boundary. If a test needs a provider, use the repository's fake or test adapter rather than a live secret.

Read the architecture guide →