Local Development

The local development workflow follows a strict sequence: configure environment, start infrastructure, start Temporal runtime, run migrations, then start applications.

Prerequisites

Step-by-step setup

1. Install dependencies

pnpm install

2. Configure environment

pnpm env:configure

This script copies .env.example to .env (if it does not exist) and upserts all required keys with local development defaults:

The script is idempotent. Running it again updates existing keys without duplicating them.

3. Start infrastructure

pnpm infra:ensure

This starts all Docker Compose services under the infra profile and waits for health checks to pass. Services include PostgreSQL, Redis, the OTEL collector, Jaeger, Prometheus, Grafana, and Loki.

If infrastructure is already running, the command exits immediately. See Docker Stack for service details.

4. Start local Temporal CLI runtime

pnpm temporal:dev:up

Use pnpm temporal:dev:status to verify readiness.

5. Run database migrations

pnpm db:migrate
pnpm db:schemas:apply

Drizzle ORM migrations run against the database specified in DATABASE_URL. Reapplied desired-state SQL then runs from packages/infra/db/schemas/.

6. Start all applications

pnpm dev

This runs all application dev servers in parallel via Turborepo:

You can also start individual applications:

pnpm dev:web      # Next.js only
pnpm dev:api      # Effect HTTP API only
pnpm dev:worker   # Temporal worker only
pnpm dev:mobile   # Expo React Native only
pnpm dev:mobile:web # Expo web preview (intentional browser target)

pnpm dev:mobile runs Expo/Metro on MOBILE_PORT (default 8081). Open the actual app using iOS Simulator, Android Emulator, or Expo Go. http://localhost:8081 is the Metro/web endpoint and is usually not the best native mobile UX.

To expose your local API via Cloudflare tunnel while developing, set:

DEV_CLOUDFLARE_TUNNEL_ENABLED=true

Optional settings:

• DEV_CLOUDFLARE_TUNNEL_URL (defaults to http://127.0.0.1:${API_PORT})
• DEV_CLOUDFLARE_TUNNEL_LOG_FILE
• DEV_CLOUDFLARE_TUNNEL_TOKEN (for named tunnel mode)
• DEV_CLOUDFLARE_TUNNEL_LOCK_DIR
• DEV_CLOUDFLARE_TUNNEL_STALE_TIMEOUT_SECONDS
• DEV_CLOUDFLARE_TUNNEL_MISSING_PID_GRACE_SECONDS

Tunnel ownership is lock-guarded across worktrees. If another worktree already owns the lock, pnpm dev continues but skips tunnel startup in the current worktree.

Check current lock owner/status:

pnpm dev:tunnel:status

If you specifically want browser preview, run pnpm dev:mobile:web so Expo serves the app intentionally for web.

7. Open local dev views (optional)

pnpm dev:open

Run this after pnpm dev is up. It opens local app/dev dashboards (web, mobile Metro status, API Swagger, Temporal UI, Grafana, Prometheus, Jaeger) in Brave Browser with a Google Chrome fallback.

Verifying the setup

After starting all services, verify everything works:

# Check API health
curl http://localhost:4000/health

# Verify API Swagger endpoint
curl -f http://localhost:4000/docs > /dev/null

# Verify OpenAPI JSON endpoint
curl -f http://localhost:4000/openapi.json > /dev/null

# Open web app
open http://localhost:3000

# Open API Swagger UI
open http://localhost:4000/docs

# Check Temporal CLI runtime
pnpm temporal:dev:status

# Open Grafana dashboards
open http://localhost:3001

Rebuilding contracts

When you change the API, regenerate the OpenAPI spec and client hooks:

# Generate OpenAPI spec from API routes
pnpm openapi:generate

# Regenerate web + mobile API client hooks
pnpm api:client:generate

Running quality checks

# Quick checks (reduced output for agent workflows)
pnpm lint:quiet
pnpm type-check:quiet
pnpm test:quiet

# Full output (for debugging failures)
pnpm lint
pnpm type-check
pnpm test

# Integration tests (resets test DB, requires running infra)
pnpm test:integration

Docker is infra-only

In local development, Docker runs only infrastructure services. Applications run as native Node.js processes for fast hot-reload. In staging and production, applications are deployed as container images built by pnpm deploy:build-images.