Repo map — where everything lives

A practical map of the Dispatch monorepo: what each directory holds, how the stack builds, and how to run it locally. For product intent see docs/dispatch-overview.md and docs/dispatch-production-design.md; for current working state see design-system/STATUS.md.

Top-level layout

Path	What it is
apps/web/	Member + admin web app — Angular 22 (standalone, signals, zoneless, SSR/SSG).
apps/api/	Backend API — Go (Gin), the CRUD + domain engine.
apps/web-e2e/	Playwright end-to-end tests for the web app.
libs/auth/	Shared Go auth library — Supabase JWT verification + Gin middleware.
supabase/	Local Postgres stack: config.toml, migrations/, seed.sql.
infra/	Deploy configs — fly/ (API) and cloudflare/ (web/edge).
design-system/	Theme tokens + vanilla HTML/CSS/JS templates — the visual/behavioral spec.
docs/	Product specs, auth setup, authz matrix, implementation notes, this map.
scripts/	One-off build/codegen helpers (e.g. OpenAPI option-method rename).
nx.json / package.json	Nx workspace config + bun scripts (the entry point for all tasks).
orval.config.ts / orval.transform.mjs	Generate the TS API client from the API's OpenAPI spec.
go.work	Go workspace tying apps/api + libs/auth together.

Web app — apps/web/src/app/

Path	Holds
core/	App-wide singletons: api/ client, auth/, http/ interceptors, connection/ heartbeat, theme/, toast/.
features/	Routed feature areas: login/, register/, auth-callback/, member/ (the member app), admin/ (back-office).
shared/	Reusable pieces: crud/ engine, toast/, completion.ts (mandate completion math).
environments/	Per-build environment config.

Dev server (nx serve web): http://localhost:7080 (set via the serve target's port option in apps/web/project.json). The serve-static file-server target (prebuilt bundle preview from dist/) runs on 7081.

API — apps/api/

Path	Holds
main.go	Entry point; reads config, builds the router, listens on PORT (default 7070).
internal/config/	Env-driven config (PORT, DATABASE_URL, SUPABASE_URL, SUPABASE_JWT_SECRET).
internal/router/	Route wiring + openapi.go (spec generation) + handler tests.
internal/crud/	Schema-driven CRUD engine (engine.go, handlers.go, schema.go).
internal/domain/	Domain model + rules (mandates, tasks/dispatches, completion).
internal/db/	Database access.
internal/profile/, skills/, completion/, notifications/	Domain modules.
internal/httpx/	HTTP helpers (error shapes, etc.).
Dockerfile	Container build for deploy (Fly).

Auth library — libs/auth/

Shared Go module imported by the API: verifier.go / jwt.go (Supabase JWT + JWKS verification), middleware.go (Gin auth middleware). Has its own unit tests.

Database — supabase/

Path	Holds
config.toml	Local stack ports: API 54321, db 54322, Studio 54323, Inbucket 54324.
migrations/	Ordered SQL: extensions → auth/profile → access-token hook → core domain → RLS → realtime → v2 entities (nodes, referrals, principal-partner role, contract keys).
seed.sql	Demo data loaded by db reset.

Building & running

All tasks go through bun → Nx. Run from the repo root.

bun install          # first time in a fresh worktree (no node_modules)
bun run build        # = nx run-many -t build  (api + web)
bun run test         # = nx run-many -t test
bun run api:gen      # regenerate the TS API client from the OpenAPI spec

Start the whole stack

bun run stack        # supabase start → db reset (migrations + seed) → dev

bun run dev serves api + web in parallel with the local DB env injected. Or run the pieces:

bun run stack:up     # supabase start (Docker: Postgres + Auth + Studio)
bun run db:reset     # apply migrations + seed
bun run dev          # nx serve api + web
bun run stack:down   # stop Supabase

Local endpoints

Service	URL
Web (Angular dev server)	http://localhost:7080
Web (static preview, nx serve-static web)	http://localhost:7081
API (Go)	http://localhost:7070
API health check	http://localhost:7070/health
Supabase API	http://127.0.0.1:54321
Supabase Studio	http://127.0.0.1:54323
Postgres	postgresql://postgres:postgres@127.0.0.1:54322/postgres
Inbucket (mail catcher)	http://127.0.0.1:54324

Requires Docker running (for Supabase), plus the bun, supabase, and go CLIs.