Running locally

The two-process dev stack — API on :8080, app on :3000 — in fixtures or GCS mode.

Prerequisites

Node 20+ and pnpm 10.28.1 (pinned via packageManager in both repos — corepack enable gets you the right one).

App only (mock data)

cd repos/ollin-study
pnpm install
pnpm dev          # http://localhost:3000 → redirects to /study
pnpm test         # vitest
pnpm typecheck    # tsc --noEmit
pnpm build        # production build (Vercel-compatible)

With no API configured, every screen renders from the deterministic local mock dataset and carries the amber "Demo data" ribbon. That is a fully working product tour — just not real solves.

Two-process dev stack (live data)

# terminal 1 — the API, serving its fixtures on :8080
cd repos/ollin-study-api && pnpm dev

# terminal 2 — the app against it
cd repos/ollin-study
OLLIN_STUDY_API_URL=http://127.0.0.1:8080 pnpm dev

Use 127.0.0.1, not localhost

The API binds IPv4-only and Node's fetch resolves localhost to ::1 first — with http://localhost:8080 every request fails silently and the app drops to mock mode with the demo ribbon showing. This is the most common "why is it demo data?" cause.

API data modes

The API (ollin-study-api) reads one of two sources, selected by STUDY_DATA_MODE:

The default. Serves the committed fixture packs — tiny fabricated families under fixtures/, and trimmed copies of real producer packs under fixtures-real/ (point FIXTURES_ROOT=fixtures-real at those). No network, no credentials; this is what pnpm test runs against.

pnpm dev    # STUDY_DATA_MODE defaults to "local"

Ports

Port	Process
`3000`	`ollin-study` (Next.js) — `pnpm dev` / `pnpm start`
`8080`	`ollin-study-api` (Fastify) — Cloud Run injects `PORT` in prod

Both are overridable (PORT=3001 pnpm dev, PORT=8081 pnpm dev) when the defaults are taken.

Environment reference (app)

Env	Effect
`OLLIN_STUDY_API_URL`	Base URL of ollin-study-api. Set → live fetches (server-side, cached per the API's immutable-stamp model). Unset or unreachable → deterministic mock dataset + demo ribbon.
`NEXT_PUBLIC_SUPABASE_URL` / `NEXT_PUBLIC_SUPABASE_ANON_KEY`	Optional; without them the Supabase clients return `null` and auth UI stays a disabled stub. No real project exists yet.

The API's full environment table lives in the API configuration reference.