Development

Local DevelopmentCopy Anchor Link

Start all appsCopy Anchor Link

bun run dev          # All apps except docs (Turborepo parallel)
bun run dev:all      # All apps including docs

Start a single appCopy Anchor Link

bun dev --filter app    # Main app (port 4000)
bun dev --filter api    # API server (port 4002)

PortsCopy Anchor Link

DatabaseCopy Anchor Link

Schema changesCopy Anchor Link

After editing packages/database/src/schema/ (any of the 9 domain modules):

bun db:generate      # Generate a reviewed migration file
bun db:migrate       # Apply migrations to the configured development DB
# Local-only direct schema sync, when intentionally needed:
# bun db:push:local

Seed dataCopy Anchor Link

bun db:seed          # Seed 5 locations
bun db:seed-forms    # Seed Opening Checklist + Daily Standup forms + sample submissions
bun db:seed-q12      # Seed Q12 Gallup Survey
bun db:seed-survey   # Seed Customer Feedback + NPS surveys
bun db:seed-coupons  # Seed coupon theme data + sample coupon
bun db:seed-slack-routes # Seed Slack channel routing (requires SLACK_BOT_TOKEN + CSV in tmp/)

Coupon and survey seeds are development fixtures. They do not prove protected migration history, team rollout admission, real guest/device/privacy acceptance, or permission to distribute QR codes. For isolated Coupon regression and rendered journeys, follow the prepared-checkout runbook. It owns target identity, production-artifact provenance, capture controls, retries, fixture migration/no-op, and cleanup; use no application credentials or production data. See Coupons and Guest NPS for the current release/pilot distinction.

Analytics mart repairCopy Anchor Link

Tip marts are partition-owned by Dagster. Use a local Dagster partition run for development fixtures. Historical production repair requires an approved #989 repair manifest; the former app backfill writer is retired.

See Analytics & Tips Integration for schedules and coverage expectations.

Drizzle StudioCopy Anchor Link

bun --cwd packages/database run db:studio

Opens a visual database editor at localhost:3005.

Linting and Type CheckingCopy Anchor Link

bun run check        # Lint + type-check (Biome via ultracite)
bun run fix          # Auto-fix lint issues

TestingCopy Anchor Link

bun run test         # Run all tests across monorepo

Run a single test file:

cd apps/app && bun run test -- --reporter=verbose path/to/test.test.ts

BuildingCopy Anchor Link

bun run build        # Build all apps
bun run analyze      # Bundle analysis

Environment VariablesCopy Anchor Link

Each app and package has its own .env.local (or .env for packages/database). Run bun setup to create them from .env.example files.

Required variables across the monorepo:

DeploymentCopy Anchor Link

Use the deployment guide for the supported native-Git Vercel flow. Production activation, exact-SHA checks, protected credentials, and rollback evidence are governed by the deployment runbook and the Vercel deployment workflow.

Database migrationsCopy Anchor Link

Generate and review migrations locally with bun db:generate. Production migrations run only through the protected exact-SHA migration workflow; do not apply them from Neon Console, ad-hoc scripts, or an unverified CI job. See the database migration guide for local development and the production deployment guide for the release sequence.

TroubleshootingCopy Anchor Link

bun run dev fails with missing env varsCopy Anchor Link

Run bun setup and fill in all required variables. See Quickstart for the full list.

Database connection errorsCopy Anchor Link

• Verify DATABASE_URL uses the pooled connection string
• Check that your Neon project is not paused (free tier pauses after inactivity)
• For Launch tier: no auto-pause

AI chat not workingCopy Anchor Link

• Verify AI_GATEWAY_API_KEY is set and has credits
• Check the browser console for streaming errors
• The chat route has rate limiting (20 req/min) — wait if exceeded

Build failuresCopy Anchor Link

bun run clean        # Remove all node_modules and build artifacts
bun install
bun run build