trails-cool/trails
1
1
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
trails/openspec/specs/local-dev-environment/spec.md
Ullrich Schäfer 38617ce0aa
Fix OpenSpec validation failures on medium-severity specs 
- komoot-import: add SHALL to Credential storage requirement body
- local-dev-environment: add SHALL to Mobile app dev requirement body
- multi-day-routes: demote ### Note heading to plain paragraph to avoid validator treating it as a requirement

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-24 11:20:57 +02:00

4.3 KiB
Raw Blame History

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: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

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:full with --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 project SHALL provide dedicated dev commands for the apps/mobile React Native app (Expo), separate from the web stack.

Scenario: iOS development

  • WHEN a developer runs pnpm dev:ios from apps/mobile
  • THEN the Expo bundler starts and the iOS simulator opens with the app

Scenario: Android development

  • WHEN a developer runs pnpm dev:android from apps/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.