Local development

Prerequisites

Bun 1.2+
Wrangler CLI (when Workers apps exist)
A Cloudflare account (for deploy and remote bindings)

Clone and install

git clone git@github.com:keepintracks/keepintracks.git
cd keepintracks
bun install

Documentation and marketing sites

The marketing site and two Starlight doc apps are separate — business users and engineers never share a site:

bun marketing:dev  # marketing site → http://localhost:4320
bun docs:dev       # business help → http://localhost:4321
bun dev-docs:dev   # developer docs → http://localhost:4322

Marketing copy is edited in docs/public/ (EN/FR) and synced into apps/marketing on dev/build.

Personal app (base scaffold)

Service	Command	URL
API	`bun --filter personal-api dev`	http://localhost:8787/health
Web	`bun --filter personal-web dev`	http://localhost:5173

bun personal:dev   # both apps
bun --filter personal-api dev:remote   # provision staging D1/KV/R2 + remote wrangler dev

Personal auth (magic link) is implemented. Product domains (vehicles, journal, etc.) are not yet.

Remote bindings are created automatically on deploy via keepintracks-provision (see DEPLOYMENT.md).

Start the personal stack: bun personal:dev
Open http://localhost:5173 — you will be redirected to /login
Enter your email and submit Email me a sign-in link
In local development the API logs the link to the terminal and the login page shows a Local development link
Click the link — you are signed in and redirected to the app
Sign out from Settings

Email encryption backfill

After migration 0003_crypto_agility, encrypt existing plaintext emails:

bun --filter personal-api dev   # in another terminal
bun --filter personal-api run backfill:emails

Or POST http://localhost:8787/dev/backfill-email-encryption (development only).

Account export and deletion

Endpoint	Auth	Purpose
`GET /me/export`	Session cookie	Export account metadata (id, email, timestamps)
`DELETE /me`	Session cookie	Delete account and all sessions

Apply D1 migrations before first auth use:

cd apps/personal-api
wrangler d1 migrations apply DB --local

Personal API secrets (names only)

Secret / var	Where	Purpose
`SESSION_SECRET`	`wrangler secret put SESSION_SECRET --env staging\|production`	Personal-plane root secret (min 32 chars): HMAC session cookies, email encryption HKDF
`PQC_KEM_ENABLED`	`wrangler.jsonc` vars (`true` / `false`)	Enable ML-KEM-768 hybrid encryption for `users.email` at rest
`PQC_SIGN_ENABLED`	`wrangler.jsonc` vars (`true` / `false`)	Enable `session-v2.hybrid` (HMAC + ML-DSA-65) session cookies
`ENVIRONMENT`	`wrangler.jsonc` vars	`development` locally; gates `/dev/*` routes
`WEB_ORIGIN`	`wrangler.jsonc` vars	SPA origin for CORS and magic-link redirects

Cryptography lives in packages/crypto — see ADR-004.

Never reuse personal-api secrets on business-api.

Business app (base scaffold)

Service	Command	URL
API	`bun --filter business-api dev`	http://localhost:8788/health
Web	`bun --filter business-web dev`	http://localhost:5174

bun business:dev   # both apps
bun --filter business-api dev:remote   # provision staging D1/KV/R2 + remote wrangler dev

Org tenancy, auth, and operations domains are not implemented yet — only health check and a placeholder UI.

Enterprise tenants: bun --filter business-api run provision --env production --tenant <slug> --output .cloudflare/<slug>.json --no-update-config creates isolated D1/KV/R2 and writes binding IDs for Workers for Platforms upload.

Monorepo commands

bun dev                              # all apps via Turborepo
bun personal:dev
bun business:dev
bun --filter marketing dev
bun --filter personal-web dev
bun --filter personal-api dev
bun --filter business-web dev
bun --filter business-api dev