Add local dev setup, fix BRouter Dockerfile, archive change (#12)

openspec/changes/archive/2026-03-23-local-dev-setup/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-22

openspec/changes/archive/2026-03-23-local-dev-setup/design.md

@@ -0,0 +1,63 @@
+## Context
+
+The Planner app has server-side dependencies (PostgreSQL for sessions, BRouter
+for routing) that aren't available when running `pnpm dev`. The app starts but
+session creation and route computation fail. We need a local dev environment
+that mirrors production dependencies.
+
+## Goals / Non-Goals
+
+**Goals:**
+- One command to start the full local stack (DB + BRouter + apps)
+- Database migrations run automatically
+- BRouter has at least one segment for local route testing
+- Works on macOS (primary dev platform)
+
+**Non-Goals:**
+- Full Germany segment coverage (too large for dev, one tile is enough)
+- Production-like Caddy/Garage setup locally
+- CI integration (CI doesn't need BRouter for current tests)
+
+## Decisions
+
+### D1: Extend docker-compose.dev.yml with BRouter
+
+Add BRouter to the existing dev compose file. Use a named volume for segments
+so they persist across restarts.
+
+**Alternative**: Run BRouter natively (requires JVM). Rejected — Docker is
+simpler and consistent.
+
+### D2: Use a small test segment
+
+Download one BRouter segment covering Berlin area (E10_N50.rd5, ~124MB) for
+local testing. This is small enough to download quickly but covers a useful
+area for route testing.
+
+**Alternative**: Download all Germany (~750MB). Rejected — too slow for first
+dev setup. Can always download more tiles manually.
+
+### D3: Drizzle push for dev, migrations for production
+
+Use `drizzle-kit push` in development (applies schema directly, no migration
+files needed). Use `drizzle-kit migrate` in production.
+
+**Alternative**: Always use migrations. Rejected — adds friction during rapid
+schema iteration in dev.
+
+### D4: Script-based orchestration
+
+A shell script (`scripts/dev.sh`) starts Docker services, waits for health
+checks, runs migrations, and starts the apps. The `pnpm dev:full` command
+wraps this script.
+
+**Alternative**: Use Docker Compose for everything including apps. Rejected —
+we want Vite HMR for the apps, which works better running natively.
+
+## Risks / Trade-offs
+
+**[Docker required]** → Developers need Docker Desktop or OrbStack running.
+Mitigation: Document in README prerequisites.
+
+**[Segment download time]** → First run downloads ~124MB. Mitigation: Only
+one tile, and it's cached in a Docker volume.

openspec/changes/archive/2026-03-23-local-dev-setup/proposal.md

@@ -0,0 +1,31 @@
+## Why
+
+We can't test the Planner end-to-end locally. The Planner needs PostgreSQL
+for session persistence and BRouter for route computation. Without a one-command
+local dev setup, developers must manually run Docker containers and download
+BRouter segments. This blocks iteration on Groups 5-6.
+
+## What Changes
+
+- Add a `pnpm dev:full` command that starts PostgreSQL, BRouter, and both apps
+- Download a minimal BRouter segment for local testing (one tile)
+- Run database migrations automatically on dev startup
+- Seed data for quick testing (sample session with waypoints)
+- Document local dev setup in README
+
+## Capabilities
+
+### New Capabilities
+
+- `local-dev-environment`: One-command local development setup with PostgreSQL, BRouter, and both apps running together
+
+### Modified Capabilities
+
+(None)
+
+## Impact
+
+- **docker-compose.dev.yml**: Add BRouter service with segment volume
+- **package.json**: New `dev:full` script
+- **packages/db**: Add Drizzle migration runner
+- **README.md**: Document local dev prerequisites and setup

openspec/changes/archive/2026-03-23-local-dev-setup/specs/local-dev-environment/spec.md

@@ -0,0 +1,37 @@
+## ADDED Requirements
+
+### Requirement: One-command dev startup
+The project SHALL provide a single command that starts all services needed for local development.
+
+#### Scenario: Start full dev stack
+- **WHEN** a developer runs `pnpm dev:full`
+- **THEN** PostgreSQL, BRouter, and both apps start and are reachable at their respective ports
+
+#### Scenario: Services are healthy before apps start
+- **WHEN** the dev script starts
+- **THEN** it waits for PostgreSQL health check and BRouter readiness before starting the apps
+
+### Requirement: Automatic database setup
+The dev environment SHALL automatically create schemas and tables on startup.
+
+#### Scenario: First run database setup
+- **WHEN** `pnpm dev:full` runs for the first time
+- **THEN** the planner and journal PostgreSQL schemas and tables are created automatically
+
+### Requirement: BRouter segment for local testing
+The dev environment SHALL include at least one BRouter segment for route computation testing.
+
+#### Scenario: Download segment on first run
+- **WHEN** the BRouter Docker volume has no segments
+- **THEN** the dev script downloads E10_N50.rd5 (Berlin area, ~124MB)
+
+#### Scenario: Skip download if segment exists
+- **WHEN** the BRouter Docker volume already has segments
+- **THEN** the dev script skips the download
+
+### Requirement: Local route computation
+The Planner SHALL be able to compute routes locally in the dev environment.
+
+#### Scenario: Compute a route in Berlin
+- **WHEN** a developer sends a route request with two Berlin waypoints to the local Planner
+- **THEN** the Planner proxies to local BRouter and returns a valid GeoJSON route

openspec/changes/archive/2026-03-23-local-dev-setup/tasks.md

@@ -0,0 +1,26 @@
+## 1. Docker Compose Dev Services
+
+- [x] 1.1 Add BRouter service to docker-compose.dev.yml with segment volume
+- [x] 1.2 Add BRouter profiles volume (included in BRouter Dockerfile)
+- [x] 1.3 Verify PostgreSQL + BRouter start with `docker compose -f docker-compose.dev.yml up -d`
+
+## 2. Segment Download
+
+- [x] 2.1 Create scripts/download-dev-segments.sh that downloads E10_N50.rd5 to BRouter volume
+- [x] 2.2 Skip download if segment already exists in volume
+
+## 3. Database Setup
+
+- [x] 3.1 Add `pnpm db:push` script that runs `drizzle-kit push` against local PostgreSQL
+- [x] 3.2 Verify planner and journal schemas are created
+
+## 4. Dev Orchestration
+
+- [x] 4.1 Create scripts/dev.sh that starts Docker services, waits for health, pushes schema, starts apps
+- [x] 4.2 Add `pnpm dev:full` script to root package.json
+- [x] 4.3 Add `pnpm dev:services` script to start only Docker services (for running apps separately)
+
+## 5. Documentation & Verification
+
+- [x] 5.1 Update README.md with local dev prerequisites (Docker, pnpm) and setup instructions
+- [x] 5.2 Test full flow: start dev stack → create session → compute route with Berlin waypoints