Adding a feature

The shape of a feature

Most features touch the same layers, in roughly this order:

1. Schema — add/adjust tables or policies in a new supabase/migrations/ file. Remember: org_id stamped on network rows; no cross-schema FKs; index policy columns.
2. Server function — implement the relevant function in apps/app/src/server/functions/, declaring authMiddleware/orgMiddleware. Replace its NOT_IMPLEMENTED body.
3. Data layer — if it feeds the graph, map results into the shared GraphData type.
4. UI — wire it into a route under apps/app/src/routes/. Graph node/edge data reads and writes through the TanStack DB collections in apps/app/src/components/map-editor/lib/collections.ts (see API surface); everything else uses TanStack Query for cache/optimistic updates.
5. Docs — update this site (see below).

Documentation is part of the change

When making any change to the codebase, check whether the documentation needs updating. A PR that changes user-visible behaviour or architecture without a matching docs update is incomplete.

Specifically:

• User-facing feature → update apps/docs/src/content/docs/users/.
• Architecture, data model, deployment, or workflow → update apps/docs/src/content/docs/developers/.
• New environment variable → update Environment variables and .env.example.
• Schema change → update Database schema.

Docs updates ship in the same PR as the code. The PR template includes a documentation checkbox.

Quality gates

Before opening a PR: pnpm check, pnpm typecheck, and pnpm build should all pass. CI enforces these plus a frozen-lockfile install and the Socket.dev supply-chain check.