0cf87b72ab
- authentication-methods: document completeAuth mode param ("redirect"|"json");
clarify add-passkey nudge (no dismiss mechanism, disappears on passkey add)
- journal-auth: session maxAge is 30 days; terms allow-list uses /legal/ prefix
matching (broader than fixed list of paths)
- session-notes: mark awareness isolation and UndoManager isolation as not yet
implemented (shared instances in current code)
- activity-feed: add fan-out scenario for visibility change to public
- explore: note that ?perPage is not yet implemented (hardcoded page size)
- multi-day-routes: add per-day GPX track split scenario (splitByDays option);
document overnight vs isDayBreak naming gap
- osm-poi-overlays: debounce is 800ms + 2000ms min interval (not 500ms);
retry is not automatic (fires on next viewport change)
- brouter-integration: rate limit corrected to 300/hour; add segment-cache
requirement (client caches per-pair segments)
- wahoo-route-push: OAuth state shape uses camelCase (returnTo, pushAfter
object) not snake_case with push_after boolean
- komoot-import: document noop adapter / ConnectedServiceManager bypass;
note four Komoot-specific routes that bypass the generic OAuth framework
- background-jobs: exponential backoff not wired (retryLimit only); add SIGINT
- connected-services: add revoked status; name ConnectionNotActiveError
- infrastructure: add INTEGRATION_SECRET and SENTRY_DSN to env var lists;
split secret decryption scenario by workflow (cd-apps vs cd-infra)
- secret-management: correct CD decryption — cd-apps only decrypts app.env;
cd-infra decrypts both
- transactional-emails: welcome email is async (pg-boss job); magic-link email
includes 6-digit numeric code
- journal-route-detail: websites are https: links (not mailto:); opening_hours
is also displayed
- local-dev-environment: add mobile app (Expo) dev commands
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
4.3 KiB
Purpose
One-command local development setup with PostgreSQL, BRouter, automatic schema migration, and segment downloading.
When to Use Local vs. Staging
| Scenario | Use |
|---|---|
| Everyday development, unit tests, E2E tests | Local (pnpm dev:full) |
| Sharing a work-in-progress with reviewers | PR preview (pr-<N>.staging.trails.cool) |
| Testing against production-like infra (Caddy TLS, Docker networking) | Staging (staging.trails.cool) |
| Wahoo OAuth callback testing | Local with HTTPS=1 (see CLAUDE.md) |
| ActivityPub federation testing | Staging (requires real HTTPS + public domain) |
The Planner, Journal, PostgreSQL, and BRouter all run locally. The local stack is the default for all development work. Staging is not a replacement for local dev — it is a pre-merge verification surface and a way to share work without merging first.
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:fullruns 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
Requirement: Optional local monitoring stack
The dev environment SHALL support an optional monitoring profile matching the production stack.
Scenario: Start with monitoring
- WHEN a developer runs
pnpm dev:fullwith--monitoring - THEN Prometheus, Grafana, and Loki start alongside the app services
Requirement: Production-aligned PostgreSQL config
The dev PostgreSQL SHALL match production configuration including pg_stat_statements.
Scenario: pg_stat_statements available
- WHEN the dev PostgreSQL container starts
- THEN pg_stat_statements is enabled via initialization scripts
Requirement: Database seed script
The dev environment SHALL provide a seed script for consistent test data.
Scenario: Seed database
- WHEN a developer runs
pnpm db:seed - THEN test users, routes, and activities are created idempotently in the local database
Requirement: Dev environment reset
The dev environment SHALL provide a command to tear down and recreate the local stack.
Scenario: Reset dev environment
- WHEN a developer runs
pnpm dev:reset - THEN all Docker volumes are removed and containers are recreated
Requirement: Mobile app dev (Expo)
The apps/mobile React Native app (Expo) requires its own dev commands separate from the web stack.
Scenario: iOS development
- WHEN a developer runs
pnpm dev:iosfromapps/mobile - THEN the Expo bundler starts and the iOS simulator opens with the app
Scenario: Android development
- WHEN a developer runs
pnpm dev:androidfromapps/mobile - THEN the Expo bundler starts and an Android emulator opens with the app
Note: the mobile app requires the Journal to be running locally (or pointing at staging) for API calls. It does not use the BRouter or Yjs stack — route edits in mobile go directly through the Journal API.