Developer Guide

Tech stack

• TanStack Start (React 19, Vite 7, SSR)
• Tailwind v4 with semantic design tokens
• Postgres 15 + pgvector + pg_cron
• Vitest (unit / integration / API) + Playwright (E2E / a11y / perf / security)

Local development

bun install
cp .env.example .env
bun run dev

The dev server runs at http://localhost:8080 with HMR.

Project layout

src/
  routes/                  file-based routing (TanStack)
  routes/api/public/       webhooks + cron endpoints
  components/              feature UI
  components/ui/           shadcn primitives
  lib/                     business logic (server + shared)
  integrations/supabase/   auto-generated clients — do not edit
tests/                     Vitest + Playwright suites
docs/                      long-form docs (source for this center)

Conventions

• Server functions live next to callers as *.functions.ts
• Admin-only server code lives in *.server.ts
• Never hardcode colors — use semantic tokens
• Every bug fix ships a regression test

Testing

See docs/testing.md and /testing-dashboard. npm run test:all runs the full CI gate.