Skip to content

Local backend ​

Develop the API without a Cloudflare account. The Worker (apps/server/src/index.ts) is unchanged; a separate Bun entry serves the same oRPC router from a local SQLite file.

bash
bun run claude:bridge                       # research model: your Claude app (port 8799)
bun run seed:clients                        # creates the client "Barista LK" (idempotent)
bun apps/server/dev/local-server.ts         # http://127.0.0.1:3200/rpc/v1/...
bun scripts/local/research-client.ts barista-lk   # run research from the terminal, writes .local/research-barista-lk.json
# apps/web/.env.local (gitignored): VITE_SERVER_URL=http://localhost:3200
bun run dev:web
PieceLocalProduction
Database.local/dev.db: SQLite behind a D1-shaped shim (packages/api/src/dev/local-d1.ts) that applies the real migration files, triggers includedD1
PagesPlain fetch (no scripts run, so JS-built pages read thinner)Cloudflare Browser Rendering
ModelClaude bridgeAnthropic API key
QueueThe job runs in-process right after research.startCloudflare Queue + consumer
AuthNone: every request acts as a dev owner; binds 127.0.0.1 onlybetter-auth sessions and roles

Research uses the Claude app on your machine ​

Run bun run claude:bridge (it uses your own claude login, no API key). The server reaches it through CLAUDE_BRIDGE_URL=http://127.0.0.1:8799 and CLAUDE_BRIDGE_TOKEN (the value in .claude-bridge-token) in apps/server/.env; restart bun run dev after changing them. Without Cloudflare Browser Rendering the server reads pages with a plain fetch. Production refuses the bridge and uses ANTHROPIC_API_KEY.

Accounts (seats) and the sign-in screen ​

Accounts are real and come from packages/auth/src/admin.ts, matching school-management: fixed usernames, passwords only from the environment, reconciled on every start (a changed password signs that seat out everywhere).

SeatWhen it existsPassword
owner (owner@shootgrow.local)AlwaysOWNER_PASSWORD, at least 12 characters (the server will not start without it)
manager, sales, videographer, editorOnly when DEV_SEATS_PASSWORD is set, and never on the production stage (the server refuses to boot)DEV_SEATS_PASSWORD
<client-slug>-admin (role client), one per active client, e.g. barista-lk-adminSame condition. Created on each start for every client that exists then, with its login row on the client's Access tabDEV_SEATS_PASSWORD

The videographer and editor seats also get a crew record linked to them (rate £0 until you set it on the Crew page), so signing in as them maps to a person. A client added later gets its admin account at the next server start.

For development set, in apps/server/.env: OWNER_PASSWORD and DEV_SEATS_PASSWORD; in apps/web/.env.local: VITE_DEV_SEATS_PASSWORD (same value). The sign-in screen then shows Development accounts buttons to sign in as any seat; they exist only in a dev build of the web app. Sign out from the user menu to switch.

With bun run dev (Alchemy) the database is Alchemy's local D1, separate from .local/dev.db, so Barista LK is not in it: run bun run seed:clients (it finds the Alchemy D1 file) or use New client.

The local server lives under apps/server/dev/ and scripts/, which the Worker build never imports.

API added ​

ProcedureWhoDoes
v1.clients.list / getowner, managerClient businesses
v1.clients.createownerCreates a client, freezes the package it signs (starter packages until the template service exists), writes an audit_log row

Table client (migration client): status, plan, frozen package_body, price, contract window, contact fields, pause/end reasons. Leads, crew, events and money tables follow in later milestones; the web screens still use sample data.

The owner data layer (web) ​

The owner screens hold no sample data. apps/web/src/state/owner-data.ts loads every area once (v1.<area>.load) when /owner opens, serves slices to components with useOwnerData(selector), and sends every change through persist(): shown at once, saved on the server, replaced by the server's row, rolled back with the server's reason when refused. Creates carry a client-generated id, so a retry never duplicates. owner.today (needs-you, glance, sales) is a computed report read with TanStack Query, not store data. One agency's data is small, so the whole set is loaded; paging comes when a table needs it.

Internal documentation. Not for clients.