From d20ec30bceca38b5ab1155118766ea801dcadadd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ullrich=20Sch=C3=A4fer?= Date: Sun, 24 May 2026 10:41:51 +0200 Subject: [PATCH 1/2] Add docs/roadmap.md and update CLAUDE.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add docs/roadmap.md: strategic four-phase launch plan (feature complete → polish → beta → announce) with launch-blocking changes, post-launch backlog, and links to ideas/ - Update CLAUDE.md: fix stale phase-1-mvp OpenSpec reference, remove "Phase 2" label from Federation, add roadmap + ideas pointers, expand packages list with all 11 packages and accurate descriptions (including map vs. map-core split rationale) Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE.md | 14 +++++++-- docs/roadmap.md | 81 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 92 insertions(+), 3 deletions(-) create mode 100644 docs/roadmap.md diff --git a/CLAUDE.md b/CLAUDE.md index a1332cf..3f5894e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -9,7 +9,9 @@ trails.cool is a federated, self-hostable platform for outdoor enthusiasts with Full architecture: `docs/architecture.md` Philosophy: `docs/philosophy.md` -OpenSpec change: `openspec/changes/phase-1-mvp/` +Roadmap: `docs/roadmap.md` +Ideas (pre-spec explorations): `docs/ideas/` +OpenSpec changes: `openspec/changes/` ## Principles @@ -25,7 +27,7 @@ OpenSpec change: `openspec/changes/phase-1-mvp/` - **Frontend**: React + Tailwind CSS + React Router 7 (Remix stack) - **Maps**: Leaflet + OpenStreetMap tiles - **CRDT**: Yjs + y-websocket (Planner only) -- **Federation**: Fedify (Journal only, Phase 2) +- **Federation**: Fedify (Journal only) - **Database**: PostgreSQL + PostGIS - **Media storage**: S3-compatible (Garage) - **Routing engine**: BRouter (Java, runs as separate Docker container) @@ -41,9 +43,15 @@ apps/ packages/ types/ — Shared TypeScript interfaces (Route, Activity, Waypoint) ui/ — Shared React components (Tailwind) - map/ — Leaflet map wrappers and tile layer configs + map/ — React/Leaflet components (MapView, RouteLayer); re-exports map-core + map-core/ — Framework-free map constants (colors, tiles, POI, z-index, snap); safe to import server-side gpx/ — GPX parsing, generation, validation + fit/ — FIT file generation (Wahoo route push) i18n/ — react-i18next config + translations + api/ — Shared API contracts (endpoints, pagination, error types, versioning) + db/ — Drizzle schema, database client, migration helpers + jobs/ — pg-boss setup, worker, and background job types + sentry-config/ — Shared Sentry configuration infrastructure/ — Terraform + Docker Compose openspec/ — OpenSpec specs and changes docs/ — Architecture, philosophy, tooling docs diff --git a/docs/roadmap.md b/docs/roadmap.md new file mode 100644 index 0000000..eb9c1f7 --- /dev/null +++ b/docs/roadmap.md @@ -0,0 +1,81 @@ +# Roadmap + +Strategic view of what ships when and why. For implementation detail, see the linked OpenSpec changes in `openspec/changes/`. For exploratory ideas not yet in a change, see `docs/ideas/`. + +--- + +## Launch readiness + +Five changes must ship before public announcement: + +| Change | Why it blocks launch | +|---|---| +| [`route-sharing`](../openspec/changes/route-sharing/) | Visibility levels (private / public / shared-link) and forking. Federation depends on it. | +| [`social-federation`](../openspec/changes/social-federation/) | The platform is described as federated — launching without it would be misleading. ActivityPub, WebFinger, inbound Mastodon follows. | +| [`visual-redesign`](../openspec/changes/visual-redesign/) | Design system not yet implemented. Current UI is unstyled Tailwind. Must land before any public-facing announcement. | +| [`wahoo-production-cutover`](../openspec/changes/wahoo-production-cutover/) | Wahoo sandbox rate limits make the integration unusable at scale. Ops task, not a feature, but launch-blocking. | +| [`changelog`](../openspec/changes/changelog/) | Public `/changelog` is part of the launch narrative — how we communicate "here's what just shipped" to early users on day one. | + +--- + +## Phases + +### Phase 1 — Feature complete + +Implement all launch-blocking changes above, in dependency order: + +1. `route-sharing` (no dependencies) +2. `social-federation` (depends on route-sharing for public routes) +3. `wahoo-production-cutover` (ops, can run in parallel) +4. `changelog` (no feature dependencies) + +### Phase 2 — Polish sprint + +After features are stable, run a dedicated UI/UX review pass: + +- Walk every user-facing flow end-to-end in a real browser +- Implement `visual-redesign` if not already complete (this change may span phases 1–2) +- Fix rough edges: empty states, loading states, error messages, mobile layout +- Review copy and i18n strings for consistency +- No new features during this phase — polish only + +The polish sprint is its own phase because it requires a stable feature set. Polishing during active feature development is expensive churn. + +### Phase 3 — Soft launch / beta + +Invite 10–20 real users before public announcement: + +- Watch Sentry for crashes and unhandled errors +- Watch Grafana for performance regressions +- Watch for federation interop issues (Mastodon follow/unfollow, object delivery) +- Collect structured feedback on onboarding and core flows +- Fix anything critical; defer cosmetic issues to post-launch + +### Phase 4 — Public announcement + +Announce once beta feedback is resolved: + +- Changelog entry for launch +- Social post / blog post + +--- + +## Post-launch + +These changes are scoped and designed but not blocking launch: + +| Change | Notes | +|---|---| +| [`route-discovery`](../openspec/changes/route-discovery/) | Spatial map-based route exploration. The text `/explore` page covers the gap at launch. | +| [`activity-photos`](../openspec/changes/activity-photos/) | Photo uploads for activities. Enriches content but not a day-one requirement. | +| [`mobile-app`](../openspec/changes/mobile-app/) | React Native unified app. Substantial scope; explicitly post-launch. | + +--- + +## Ideas (exploratory, not yet in a change) + +See `docs/ideas/` for pre-spec explorations: + +- `mobile-activity-recording/` — GPS tracking and activity logging from a native app +- `mobile-nearby-sync/` — BLE-based proximity discovery +- `self-host-overpass/` — Self-hosted Overpass API for POI overlays From 12f6e6be51d5d6dc35788e515d9b9413499bf0f2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ullrich=20Sch=C3=A4fer?= Date: Sun, 24 May 2026 10:43:03 +0200 Subject: [PATCH 2/2] Update self-host-overpass README with accurate OVERPASS_URLS env var The proxy now supports OVERPASS_URLS (comma-separated, round-robin fallback) with OVERPASS_URL as a single-entry backward-compat alias; update the switch path note to match. Co-Authored-By: Claude Sonnet 4.6 --- docs/ideas/self-host-overpass/README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/ideas/self-host-overpass/README.md b/docs/ideas/self-host-overpass/README.md index 4977919..98b7ca4 100644 --- a/docs/ideas/self-host-overpass/README.md +++ b/docs/ideas/self-host-overpass/README.md @@ -39,8 +39,10 @@ Revisit once **any** of these is true: different hardware (AX52 ≈ €54/mo for a dedicated 64 GB NVMe box that handles planet at low user counts; see design.md). - **Switch path**: no client changes needed to cut over — the Planner - proxy already reads `OVERPASS_URL` from env and defaults to - private.coffee. Flipping the env var points at our own instance. + proxy reads `OVERPASS_URLS` (comma-separated list with round-robin + fallback) or the single-entry alias `OVERPASS_URL`, defaulting to + `lz4.overpass-api.de` then `overpass-api.de`. Flipping the env var + points at our own instance. ## What's in the folder