trails.cool monorepo (migrated from GitHub)
8e5b6d6fe9
Implements tasks 1.3, 3.2-3.3, 4.1-4.4, 5.1-5.6, 6.1 of
deepen-connected-services. Built TDD: contract test red, adapter green
for each capability seam.
Capability adapters (providers/wahoo/):
- importer.ts: Importer seam — listImportable + importOne against
Wahoo /v1/workouts. Filters fitness_app_id >= 1000 (Wahoo doesn't
share third-party data). 2 contract tests green.
- pusher.ts: RoutePusher seam — pushRoute(ctx, input) -> {remoteId,
version}. FIT-Course conversion, route:<id> external_id, PUT-vs-POST
decision, PUT->POST-on-404 fallback all internal to the adapter
(per ADR-0003). Idempotency via sync_pushes preserved. 4 contract
tests green.
- webhook.ts: WebhookReceiver seam — parseWebhook + handle. Routes
events to local users via provider_user_id; unknown user returns
silently. 6 contract tests green.
- manifest.ts: declares credential_kind=oauth, OAuth config, scopes,
buildAuthUrl, exchangeCode, and references each capability adapter.
Module shape:
- connected-services/index.ts: side-effect imports providers/index.ts
to register manifests, then re-exports manager + registry + types.
- connected-services/providers/index.ts: barrel that calls
registerManifest(wahooManifest).
- connected-services/oauth-state.server.ts: OAuth state encode/decode
(extracted from legacy pushes.server.ts).
- connected-services/push-action.server.ts: orchestration above the
RoutePusher seam — load route, ownership check, scope check, build
RoutePushInput, invoke pusher, return PushOutcome union. Replaces
the legacy pushRouteToProvider in lib/sync/pushes.server.ts.
Caller migration (group 5):
- api.sync.connect.$provider.ts -> manifest.buildAuthUrl
- api.sync.callback.$provider.ts -> manifest.exchangeCode + link()
- api.sync.disconnect.$provider.ts -> unlinkByUserProvider (calls
best-effort revoke via the credential adapter, then deletes locally)
- api.sync.webhook.$provider.ts -> manifest.webhookReceiver dispatch
- api.sync.push.$provider.$routeId.ts -> push-action.pushRouteToProvider
- sync.import.$provider.tsx -> manifest.importer.listImportable +
inline FIT->GPX in the action (form-supplied metadata bypasses the
Importer seam which is reserved for automatic / webhook imports)
- routes.$id.tsx -> getService instead of getConnection
- settings.connections.tsx -> getAllManifests instead of legacy registry
Legacy lib/sync/ deleted except imports.server.ts (which manages the
sync_imports table, untouched by this change).
DB migration verified locally (task 1.3): pnpm db:migrate-data renamed
the table and backfilled credentials JSONB; pnpm db:push then dropped
the legacy access_token/refresh_token/expires_at columns. Final shape
matches the schema; check constraints + unique index in place.
Test status (task 6.1):
- pnpm typecheck: green across all 15 workspaces
- pnpm lint: green
- @trails-cool/journal: 112 passed, 31 skipped — 12 fewer tests than
before because pushes.server.test.ts and the legacy wahoo.test.ts
were deleted. Their coverage is replaced by the new contract tests
(importer/pusher/webhook) plus manager.test.ts + oauth.test.ts.
Remaining: 6.2 (e2e), 6.3-6.4 (manual smoke + staging migration test),
7.1-7.3 (followups + spec deltas at archive).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
||
|---|---|---|
| .claude | ||
| .github | ||
| apps | ||
| docker/brouter | ||
| docs | ||
| e2e | ||
| infrastructure | ||
| openspec | ||
| packages | ||
| scripts | ||
| .gitignore | ||
| .gitleaks.toml | ||
| .mcp.json | ||
| .prettierrc | ||
| .sops.yaml | ||
| CLAUDE.md | ||
| CONTEXT.md | ||
| docker-compose.dev.yml | ||
| eslint.config.js | ||
| LICENSE | ||
| package.json | ||
| playwright.config.ts | ||
| pnpm-lock.yaml | ||
| pnpm-workspace.yaml | ||
| README.md | ||
| SECURITY.md | ||
| tsconfig.base.json | ||
| turbo.json | ||
| vitest.config.ts | ||
| vitest.setup.ts | ||
| vitest.shared.ts | ||
trails.cool
Collaborative route planning and federated activity sharing for outdoor enthusiasts.
Planner — Plan routes together in real-time. Share a link, invite friends, edit waypoints collaboratively. Powered by BRouter for intelligent routing with elevation awareness.
Journal — Track your adventures. Import activities from Garmin, Strava, or Wahoo. Share routes and rides with friends. Self-host your own instance and federate with others via ActivityPub.
Status
Early development. See the architecture plan and project philosophy.
Project Structure
This is a TypeScript monorepo using pnpm workspaces and Turborepo.
apps/
planner/ Collaborative route editor (React Router 7 + Yjs + Leaflet)
journal/ Activity social platform (React Router 7 + Fedify + PostGIS)
packages/
types/ Shared TypeScript interfaces
ui/ Shared React components (Tailwind)
map/ Leaflet map wrappers
gpx/ GPX parsing and generation
i18n/ Internationalization (English + German)
Getting Started
Prerequisites: Node.js 20+, pnpm, Docker
# Clone
git clone https://github.com/trails-cool/trails.git
cd trails
# Install dependencies
pnpm install
# Start development (apps only, no database or routing)
pnpm dev
# Start full stack (PostgreSQL + BRouter + apps)
pnpm dev:full
Full Local Dev Setup
pnpm dev:full starts everything needed to test the Planner end-to-end:
- PostgreSQL + PostGIS on port 5432 (via Docker)
- BRouter routing engine on port 17777 (via Docker)
- Database schema pushed automatically via Drizzle
- BRouter segment downloaded for Berlin area (~124MB, cached)
- Journal on http://localhost:3000
- Planner on http://localhost:3001
Other useful commands:
pnpm dev:services # Start Docker services only (DB + BRouter)
pnpm db:push # Push database schema changes
pnpm db:studio # Open Drizzle Studio (DB browser)
Development Tools
This project uses AI-assisted, spec-driven development. See docs/tooling.md for details.
| Tool | Purpose |
|---|---|
| cmux | Native macOS terminal for running multiple AI coding sessions |
| Claude Code | AI coding assistant (primary development tool) |
| GitHub Copilot | AI coding assistant |
| Crit | Browser-based inline code review |
| OpenSpec | Spec-driven development workflow |
Self-Hosting
The Journal is designed to be self-hosted. A single Docker Compose file gets you running:
curl -O https://raw.githubusercontent.com/trails-cool/trails/main/infrastructure/docker-compose.yml
docker compose up -d
See docs/architecture.md for details on self-hosting configuration.
Philosophy
- Privacy by design — The Planner collects zero user data
- Data ownership — Export everything, self-host, no lock-in
- Open source — MIT licensed, built on open standards
- Simplicity — Start simple, add complexity only when needed
Read more: docs/philosophy.md
Contributing
Human contributions are welcome! This project is built with AI-assisted development (Claude Code + OpenSpec), but we value human judgment, design taste, and community input.
License
MIT