Totlob Docs

Run the API against Dockerised Postgres, Redis and RabbitMQ, then point the dashboard and the till at it through their Vite dev proxies.

Prerequisites

Node ≥ 20 (CI uses 24) and Docker.
An NPM_TOKEN that can read the @totlob scope on GitHub Packages, exported in your shell. Every repo's .npmrc uses it.

API (api-v2)

cd api-v2
cp .env.example .env          # fill in what you need; everything external is optional in dev
npm install
npm run db:up                 # docker compose: Postgres 16, Redis 7, RabbitMQ 4
npm run db:migrate
npm run dev                   # tsx watch on :3000

Service	Host port	Notes
Postgres 16	5433	DB `totlob_dev`; tests use `totlob_test`
Redis 7	6380	LRU, no volume
RabbitMQ 4	5673 (AMQP), 15673 (UI)	Optional; without it events run in-process

OTP codes: without Mailgun, development logs the code to the console. An address in otp_bypass accepts 0000.
Seeds: node scripts/seed-dashboard-demo.mjs --apply, seed-pos-demo.mjs --apply, seed-pos-sections.mjs --apply, and npm run db:seed-dev-plans. All are dry-run without --apply.
Consumers: npm run consumer:dev, or set WEB_CONSUMES_QUEUE=true.
OpenAPI: npm run docs:openapi writes docs/openapi/*.json.

Merchant dashboard

cd merchant-dashboard-v2
cp .env.example .env          # VITE_API_PROXY_TARGET=http://localhost:3000
npm install
npm run dev                   # :5173, proxies /merchant and /health

To try the AI assistant panel (stubbed), set VITE_ASSISTANT_ENABLED=true.

Point of sale

cd totlob-pos
npm install
VITE_API_BASE_URL= npm run dev   # :5273, proxies /pos and /health

The POS .env points at production

totlob-pos/.env is committed with VITE_API_BASE_URL set to the production API. Override it to empty (same-origin through the proxy) or to your local API when developing, or you'll sell against real data.

Contracts against a local build

To test an unpublished contract change, build the contracts repo and overlay its dist into node_modules/@totlob/contracts-* in the API and app. Restore it with npm install afterwards. Don't trust an old /tmp backup of dist; reinstall the pinned version instead. Details are in api-v2/.claude/LOCAL-DEV.md.

Before you start

Check what each checkout is tracking. At the time of writing:

local master in all three repos was behind origin/master
the dashboard's node_modules had contracts-merchant 0.7.4 against a 0.7.18 pin

Run git fetch && git status and npm install first.