trails/openspec/changes/phase-1-mvp/design.md

Context

trails.cool is a new platform with two apps: a collaborative route Planner and a federated activity Journal. The full architecture is documented in docs/architecture.md with 19 resolved design decisions. Phase 1 builds the foundation — both apps with minimal features, shared packages, and deployment infrastructure.

The Planner is stateless and ephemeral — it runs collaborative editing sessions via Yjs and computes routes via BRouter. The Journal is stateful — it stores user accounts, routes, and activities in PostgreSQL with PostGIS.

Both apps share a TypeScript/React stack (React Router 7, Tailwind) and are deployed to a single Hetzner CX21 server via Docker Compose.

Goals / Non-Goals

Goals:

• Working Planner with collaborative waypoint editing and BRouter route computation
• Working Journal with user accounts, route CRUD, and activity feed
• Seamless handoff between Journal and Planner (open route in Planner, save back)
• Shared packages for types, UI components, map rendering, GPX parsing, i18n
• Deployable to Hetzner via Terraform + Docker Compose
• Germany map coverage (~750 MB RD5 segments)

Non-Goals:

• ActivityPub federation (Phase 2)
• Following/followers, likes, comments (Phase 2)
• Photo attachments (Phase 2)
• Route sharing permissions beyond basic CRUD (Phase 2)
• Mobile app or offline support (Phase 3)
• Multi-day route planning UI (Phase 3)
• WASM compilation of BRouter (Phase 3)
• Monitoring stack (Grafana/Prometheus — add when needed)

Decisions

D1: React Router 7 for both apps

Both Planner and Journal use React Router 7 (Remix stack) as their full-stack framework. This gives SSR for Journal (SEO, initial load), API routes, and loader/action patterns.

Alternative considered: Separate frameworks (e.g., Next.js for Journal, Vite SPA for Planner). Rejected because maintaining two frameworks doubles learning curve and prevents sharing server-side code patterns.

D2: BRouter wrapped as HTTP proxy in Planner backend

The Planner's React Router 7 server proxies BRouter API calls. Clients never talk to BRouter directly. This allows rate limiting, request validation, and later caching at the proxy layer.

Alternative considered: Expose BRouter directly. Rejected because BRouter has no built-in auth, rate limiting, or CORS support.

D3: Yjs with y-websocket for CRDT sync

Use y-websocket for the Planner's real-time sync. The WebSocket server runs as part of the Planner's Node.js process (not a separate service). Yjs documents are persisted to PostgreSQL for crash recovery.

Alternative considered: Separate y-websocket service. Rejected for Phase 1 simplicity — one process is easier to deploy and debug. Can extract later.

D4: PostgreSQL shared instance, separate schemas

One PostgreSQL instance with two schemas:

• planner — Yjs session documents, session metadata
• journal — users, routes, activities, media references

Alternative considered: Separate PostgreSQL instances. Rejected — unnecessary overhead for 100 users. Single instance is simpler to backup and manage.

D5: Routing host election via Yjs awareness

Only one client per session talks to BRouter (the "routing host"). The host is the session initiator; on disconnect, the longest-connected client takes over. This avoids redundant BRouter API calls.

Alternative considered: Server-side route computation (Planner backend watches Yjs changes and computes routes). Better long-term but more complex. Client-side host election is simpler for Phase 1.

D6: Scoped JWT for Planner-Journal callback

When the Journal opens a Planner session, it generates a scoped JWT token embedded in the callback URL. The Planner sends this JWT when saving GPX back. The Journal validates the JWT signature to authorize the write.

Alternative considered: Session cookies / OAuth flow. Rejected — the Planner is stateless and doesn't have access to the Journal's session.

D7: Leaflet with plugin-based layers

Leaflet (not Mapbox GL) for map rendering. Leaflet is lighter, has no API key requirement, and has mature plugin ecosystem for OSM tiles.

Alternative considered: Mapbox GL JS. Rejected — requires API key, larger bundle, and commercial license for heavy usage.

D8: pnpm + Turborepo for monorepo

pnpm workspaces for dependency management, Turborepo for build orchestration and caching. This is the standard monorepo toolchain for TypeScript projects.

Alternative considered: Nx. Rejected — heavier setup, more opinionated. Turborepo is simpler and sufficient for our needs.

Risks / Trade-offs

[BRouter Java dependency] → The Planner requires a JVM to run BRouter. This adds Docker image size (~200 MB) and memory usage (~128 MB heap). Mitigation: BRouter runs in its own container with constrained resources.

[Yjs document size growth] → Long editing sessions could grow Yjs documents. Mitigation: Monitor document sizes in PostgreSQL. Add compaction if needed.

[Single server SPOF] → All services on one Hetzner CX21. Mitigation: Acceptable for 100 users. Daily backups to Hetzner Storage Box. Scale to multiple servers in Phase 2 if needed.

[BRouter segment freshness] → RD5 segments are updated weekly on brouter.de. Stale data could cause routing on newly built roads to fail. Mitigation: Weekly cron job to download updated segments.

[Cross-origin Planner-Journal integration] → Planner and Journal are on different subdomains (planner.trails.cool vs trails.cool). Cookie sharing won't work. Mitigation: JWT-based callback (Decision D6). No cookies needed.