Quick Start

This guide will help you get the project running locally.

The goal is to get you from zero to a working environment as quickly as possible.

Prerequisites

Make sure you have the following installed:

• Node.js (see .nvmrc for version)
• pnpm (via corepack)

To enable pnpm:

npm install --global corepack@latest
corepack enable pnpm

Install dependencies

From the root of the repository:

pnpm install

Environment setup

There are two .env files to configure.

Root .env

Copy the example file:

cp .env.example .env

This file defines ports used by local services.

API .env

Navigate to clients/api and copy:

cp .env.example .env

Update the required endpoint values as needed.

If you’re unsure what to use, check with a teammate or use a local/mock endpoint.

Sync assets

From the root:

pnpm sync-assets

This ensures local assets align with expected production assets.

Start development

From the root:

pnpm dev

This will:

• start available client services
• assign them to the configured ports
• enable hot reloading for most changes

You can navigate between services in the terminal UI and open them in a browser.

Optional: run Storybook

To explore UI components in isolation:

pnpm storybook

What you’re running

When everything is up, you are running a local version of the system:

• API → provides data (proxy or mock)
• Coordinator → manages data and renderer loading
• Renderer → displays the experience

This setup allows you to explore the full system without needing the browser environment.

Common issues

If something doesn’t work as expected:

• Make sure .env files exist and are configured
• Re-run pnpm install
• Re-run pnpm sync-assets
• Restart the dev server

Where to go next

• Mental model — how the system thinks
• Architecture overview — how the pieces fit together
• Data flow — how information moves through the system