trails-cool/trails
1
1
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
trails.cool monorepo (migrated from GitHub)
848 commits 46 branches 0 tags 6.5 MiB
Find a file
Ullrich Schäfer 1f15330961 Document why HTTPS=1 dev exists, and the one case that still needs it 
Most contributors don't need HTTPS=1 locally — plain HTTP is the
default and the right choice for everything except Wahoo OAuth
callback testing. WebAuthn (passkeys), magic links, sessions, the
Terms gate, SSE all work over HTTP because the WebAuthn spec treats
localhost as a secure context regardless of scheme. CI proves the
point: the e2e suite runs over plain HTTP and passes cleanly.

The original HTTPS=1 plumbing landed in 20b91ef (2026-04-05) bundled
into a Wahoo import fix, with no inline rationale. Once you've
forgotten the reason it tends to leak into the default workflow,
which then breaks the local e2e suite (Playwright always uses HTTP
baseURL; an https ORIGIN env mismatches what it sends) and creates
unnecessary divergence from CI.

Documenting the single legitimate use case so the next contributor
(or future-me) doesn't have to re-derive it from git blame:

- apps/journal/vite.config.ts — expanded the comment near the
  basic-ssl plugin to spell out:
  * What works on HTTP (everything except Wahoo)
  * What needs HTTPS=1 (Wahoo OAuth specifically)
  * The norm: don't add new HTTPS-only paths without writing them
    down here too, so the assumption stays auditable
- apps/journal/.env.example — new tracked file showing the env vars
  the journal app reads, with `ORIGIN=https://localhost:3000`
  marked as HTTPS-only and accompanied by an explanation of the
  ORIGIN/Playwright mismatch trap. Future contributors don't have
  to discover this through a failing e2e run.
- CLAUDE.md — new "Local HTTPS dev (rare)" subsection under
  Development Commands. Includes the exact command for Wahoo testing
  (`HTTPS=1 ORIGIN=https://localhost:3000 pnpm --filter
  @trails-cool/journal dev`), the turbo-doesn't-pass-HTTPS gotcha,
  and the rule of thumb: don't set ORIGIN in your .env unless you
  also always run with HTTPS=1.

No code/behavior changes; documentation only.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-26 12:26:58 +02:00
.claude Add /ia-review and /spec-drift-review process skills 2026-04-26 08:41:07 +02:00
.github Revert cd-apps annotation path: GRAFANA_SERVICE_TOKEN is in .env, not app.env 2026-04-26 11:53:55 +02:00
apps Document why HTTPS=1 dev exists, and the one case that still needs it 2026-04-26 12:26:58 +02:00
docker/brouter Stop BRouter contention kills under rapid editing 2026-04-24 17:43:15 +02:00
docs Refresh IA doc — all six streams shipped on 2026-04-26 2026-04-26 10:03:05 +02:00
e2e Redesign navbar with avatar dropdown and mobile drawer 2026-04-26 09:56:20 +02:00
infrastructure Stop the caddy-502-rate alert firing on every deploy 2026-04-26 11:51:13 +02:00
openspec Include the demo persona on /explore so users can follow it 2026-04-26 11:43:24 +02:00
packages Bump the production group with 28 updates 2026-04-26 08:37:27 +00:00
scripts Make scripts/ a pnpm workspace + add README 2026-04-19 07:56:01 +02:00
.gitignore Ignore .claude/scheduled_tasks.lock 2026-04-19 12:00:02 +02:00
.gitleaks.toml Fix .gitleaks.toml config syntax 2026-03-25 11:59:26 +01:00
.mcp.json Add Sentry MCP server config, ignore worktrees 2026-03-25 07:43:58 +00:00
.prettierrc Complete monorepo toolchain setup (tasks 1.1-1.7) 2026-03-22 12:12:57 +01:00
.sops.yaml SOPS+age secrets, split CD workflows, GitHub OAuth for Grafana 2026-03-27 17:28:04 +01:00
CLAUDE.md Document why HTTPS=1 dev exists, and the one case that still needs it 2026-04-26 12:26:58 +02:00
docker-compose.dev.yml Add local dev setup, fix BRouter Dockerfile, archive change (#12) 2026-03-22 23:11:43 +00:00
eslint.config.js Fix CI on main: RouteMap typecheck + metro.config lint 2026-04-17 22:26:38 +02:00
LICENSE Initial monorepo setup with architecture plan 2026-03-22 11:29:33 +01:00
package.json Bump the production group with 28 updates 2026-04-26 08:37:27 +00:00
playwright.config.ts Implement notifications + supporting fixes 2026-04-26 01:28:55 +02:00
pnpm-lock.yaml Bump vite from 7.3.2 to 8.0.10 2026-04-26 10:02:46 +00:00
pnpm-workspace.yaml Bump vite from 7.3.2 to 8.0.10 2026-04-26 10:02:46 +00:00
README.md Restore 'primary development tool' qualifier for Claude Code in README 2026-03-29 13:12:04 +00:00
SECURITY.md Security hardening: headers, scanning, Docker, firewall 2026-03-25 09:58:12 +01:00
tsconfig.base.json Fix CI typecheck: disable noUncheckedSideEffectImports 2026-04-13 00:10:36 +02:00
turbo.json Standardize monorepo pipeline: test, lint, typecheck across all workspaces 2026-04-13 00:00:43 +02:00
vitest.config.ts Standardize monorepo pipeline: test, lint, typecheck across all workspaces 2026-04-13 00:00:43 +02:00
vitest.setup.ts Add testing strategy: Vitest for unit tests, Playwright for E2E 2026-03-22 12:36:09 +01:00
vitest.shared.ts Add tests to all packages, remove passWithNoTests 2026-04-13 00:48:27 +02:00

README.md

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:

  1. PostgreSQL + PostGIS on port 5432 (via Docker)
  2. BRouter routing engine on port 17777 (via Docker)
  3. Database schema pushed automatically via Drizzle
  4. BRouter segment downloaded for Berlin area (~124MB, cached)
  5. Journal on http://localhost:3000
  6. 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