Add CLAUDE.md, README, and development tooling docs
- CLAUDE.md: project context for Claude Code sessions - README.md: human-facing project intro, structure, getting started - docs/tooling.md: cmux, Claude Code, Crit, and OpenSpec workflow Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ullrich Schäfer
parent
4214564fd8
commit
48547fdc82
3 changed files with 293 additions and 0 deletions
90
CLAUDE.md
Normal file
90
CLAUDE.md
Normal file
|
|
@ -0,0 +1,90 @@
|
|||
# CLAUDE.md
|
||||
|
||||
## Project Overview
|
||||
|
||||
trails.cool is a federated, self-hostable platform for outdoor enthusiasts with two apps:
|
||||
|
||||
- **Planner** (`apps/planner`) — Stateless collaborative route editor. Real-time editing via Yjs, routing via BRouter, no user accounts, sessions are anonymous and ephemeral.
|
||||
- **Journal** (`apps/journal`) — Federated social platform for routes and activities. User accounts, ActivityPub federation via Fedify, PostgreSQL + PostGIS.
|
||||
|
||||
Full architecture: `docs/architecture.md`
|
||||
Philosophy: `docs/philosophy.md`
|
||||
OpenSpec change: `openspec/changes/phase-1-mvp/`
|
||||
|
||||
## Principles
|
||||
|
||||
- **Privacy-first**: The Planner collects zero user data. The Journal documents all data collection in a privacy manifest. Never add tracking, analytics, or data collection without updating the manifest.
|
||||
- **Data ownership**: All user data must be exportable in open formats (GPX, JSON). Never create data lock-in.
|
||||
- **Simplicity**: Start with the simplest thing that works. Don't add abstractions, config options, or features unless real users need them.
|
||||
- **Open standards**: Use GPX, ActivityPub, OpenStreetMap, WebFinger. Don't invent proprietary formats.
|
||||
- **Inclusive language**: Use "host" not "master", "allowlist" not "whitelist", etc.
|
||||
|
||||
## Tech Stack
|
||||
|
||||
- **Language**: TypeScript (strict mode)
|
||||
- **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)
|
||||
- **Database**: PostgreSQL + PostGIS
|
||||
- **Media storage**: S3-compatible (Garage)
|
||||
- **Routing engine**: BRouter (Java, runs as separate Docker container)
|
||||
- **i18n**: react-i18next (English + German)
|
||||
- **Monorepo**: pnpm workspaces + Turborepo
|
||||
|
||||
## Repository Structure
|
||||
|
||||
```
|
||||
apps/
|
||||
planner/ — Planner app (React Router 7)
|
||||
journal/ — Journal app (React Router 7 + Fedify)
|
||||
packages/
|
||||
types/ — Shared TypeScript interfaces (Route, Activity, Waypoint)
|
||||
ui/ — Shared React components (Tailwind)
|
||||
map/ — Leaflet map wrappers and tile layer configs
|
||||
gpx/ — GPX parsing, generation, validation
|
||||
i18n/ — react-i18next config + translations
|
||||
infrastructure/ — Terraform + Docker Compose
|
||||
openspec/ — OpenSpec specs and changes
|
||||
docs/ — Architecture, philosophy, tooling docs
|
||||
docker/brouter/ — BRouter Docker image
|
||||
```
|
||||
|
||||
## Development Commands
|
||||
|
||||
```bash
|
||||
pnpm install # Install dependencies
|
||||
turbo dev # Start both apps in dev mode
|
||||
turbo build # Build all packages and apps
|
||||
turbo typecheck # Type-check all packages
|
||||
turbo lint # Lint all packages
|
||||
turbo test # Run tests
|
||||
```
|
||||
|
||||
## Code Conventions
|
||||
|
||||
- All user-facing strings must use i18n (`useTranslation()` hook, never hardcode strings)
|
||||
- Use `@trails-cool/types` for shared interfaces — don't duplicate type definitions
|
||||
- Map components go in `@trails-cool/map`, not in individual apps
|
||||
- GPX parsing/generation goes in `@trails-cool/gpx`
|
||||
- Database schemas: `planner.*` for Planner data, `journal.*` for Journal data
|
||||
- Route geometry must be stored as PostGIS LineString (extracted from GPX on save)
|
||||
|
||||
## Key Architecture Decisions
|
||||
|
||||
- **Planner is stateless**: No user accounts, no persistent user data. Sessions are anonymous.
|
||||
- **Journal is the source of truth**: Routes live on the owner's Journal instance.
|
||||
- **Routing host pattern**: One client per Planner session talks to BRouter (elected via Yjs awareness).
|
||||
- **JWT callbacks**: Planner saves back to Journal via scoped JWT tokens in callback URLs.
|
||||
- **Sequential versioning**: Route versions are v1, v2, v3. Yjs state vectors enable conflict-free merging.
|
||||
- **Single domain**: Each instance uses one domain for both web UI and ActivityPub handles.
|
||||
- **Simple permissions**: View + Edit only. No fine-grained permissions.
|
||||
|
||||
## OpenSpec Workflow
|
||||
|
||||
Specs live in `openspec/`. Use these slash commands:
|
||||
|
||||
- `/opsx:propose` — Create a new change with proposal, design, specs, and tasks
|
||||
- `/opsx:apply` — Implement tasks from an existing change
|
||||
- `/opsx:explore` — Think through ideas before proposing
|
||||
- `/opsx:archive` — Archive a completed change
|
||||
94
README.md
Normal file
94
README.md
Normal file
|
|
@ -0,0 +1,94 @@
|
|||
# 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](https://github.com/abrensch/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](docs/architecture.md) and
|
||||
[project philosophy](docs/philosophy.md).
|
||||
|
||||
## 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
|
||||
|
||||
```bash
|
||||
# Clone
|
||||
git clone https://github.com/trails-cool/trails.git
|
||||
cd trails
|
||||
|
||||
# Install dependencies
|
||||
pnpm install
|
||||
|
||||
# Start development
|
||||
turbo dev
|
||||
```
|
||||
|
||||
## Development Tools
|
||||
|
||||
This project uses AI-assisted, spec-driven development. See
|
||||
[docs/tooling.md](docs/tooling.md) for details.
|
||||
|
||||
| Tool | Purpose |
|
||||
|------|---------|
|
||||
| [cmux](https://cmux.dev) | Native macOS terminal for running multiple AI coding sessions |
|
||||
| [Claude Code](https://claude.ai/claude-code) | AI coding assistant (primary development tool) |
|
||||
| [Crit](https://github.com/tomasz-tomczyk/crit) | Browser-based inline code review |
|
||||
| [OpenSpec](https://openspec.dev) | Spec-driven development workflow |
|
||||
|
||||
## Self-Hosting
|
||||
|
||||
The Journal is designed to be self-hosted. A single Docker Compose file gets
|
||||
you running:
|
||||
|
||||
```bash
|
||||
curl -O https://raw.githubusercontent.com/trails-cool/trails/main/infrastructure/docker-compose.yml
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
See [docs/architecture.md](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](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
|
||||
109
docs/tooling.md
Normal file
109
docs/tooling.md
Normal file
|
|
@ -0,0 +1,109 @@
|
|||
# Development Tooling
|
||||
|
||||
This project is built using AI-assisted, spec-driven development. Here are the
|
||||
main tools used in the development workflow.
|
||||
|
||||
## cmux
|
||||
|
||||
**Native macOS terminal for AI coding agents**
|
||||
|
||||
- Website: https://cmux.dev
|
||||
- GitHub: https://github.com/manaflow-ai/cmux
|
||||
|
||||
cmux is a native macOS terminal app purpose-built for running AI coding agents
|
||||
like Claude Code. It provides vertical tabs, split panes, and smart
|
||||
notifications that show which panes need attention — ideal for running multiple
|
||||
Claude Code sessions in parallel across different parts of the monorepo.
|
||||
|
||||
Key features we use:
|
||||
- Split panes for Planner and Journal development side by side
|
||||
- Notification badges when a Claude Code session needs input
|
||||
- Native performance (Swift/AppKit, not Electron)
|
||||
|
||||
## Claude Code
|
||||
|
||||
**AI coding assistant (CLI)**
|
||||
|
||||
- Website: https://claude.ai/claude-code
|
||||
- Docs: https://docs.anthropic.com/en/docs/claude-code
|
||||
|
||||
Claude Code is the primary development tool for this project. It reads the
|
||||
codebase, understands the architecture (via `CLAUDE.md`), and implements
|
||||
features from OpenSpec tasks.
|
||||
|
||||
Key integrations:
|
||||
- `CLAUDE.md` at repo root provides project context
|
||||
- OpenSpec slash commands (`/opsx:propose`, `/opsx:apply`, etc.)
|
||||
- Crit integration for code review
|
||||
|
||||
## Crit
|
||||
|
||||
**Inline code review tool**
|
||||
|
||||
- GitHub: https://github.com/tomasz-tomczyk/crit
|
||||
|
||||
Crit provides browser-based inline review for files and diffs. It's used in
|
||||
the development workflow for reviewing architecture plans, specs, and code
|
||||
changes before committing.
|
||||
|
||||
How we use it:
|
||||
- Review architecture and design documents with inline comments
|
||||
- Claude Code addresses review comments and re-opens for another round
|
||||
- Iterate until the reviewer clicks "Finish Review" with no comments (approved)
|
||||
|
||||
Usage:
|
||||
```bash
|
||||
crit <file> # Review a specific file
|
||||
crit # Review git diff (uncommitted or branch changes)
|
||||
crit share <file> # Share a review via URL
|
||||
```
|
||||
|
||||
## OpenSpec
|
||||
|
||||
**AI-native spec-driven development**
|
||||
|
||||
- Website: https://openspec.dev
|
||||
- GitHub: https://github.com/Fission-AI/OpenSpec
|
||||
|
||||
OpenSpec structures the development workflow around specifications. Each feature
|
||||
starts as a "change" with four artifacts:
|
||||
|
||||
1. **proposal.md** — Why this change is needed and what capabilities it adds
|
||||
2. **design.md** — Technical decisions and architecture
|
||||
3. **specs/** — Testable requirements with WHEN/THEN scenarios
|
||||
4. **tasks.md** — Implementation checklist
|
||||
|
||||
Workflow:
|
||||
```bash
|
||||
# Propose a new feature (generates all artifacts)
|
||||
/opsx:propose "add route sharing"
|
||||
|
||||
# Implement tasks from a change
|
||||
/opsx:apply
|
||||
|
||||
# Archive when done
|
||||
/opsx:archive
|
||||
```
|
||||
|
||||
OpenSpec files live in `openspec/` at the repo root. The current active change
|
||||
is `openspec/changes/phase-1-mvp/`.
|
||||
|
||||
## How They Work Together
|
||||
|
||||
```
|
||||
1. Plan cmux + Claude Code + Crit
|
||||
Draft architecture → review with Crit → iterate
|
||||
|
||||
2. Specify Claude Code + OpenSpec
|
||||
/opsx:propose → generates proposal, design, specs, tasks
|
||||
|
||||
3. Implement cmux + Claude Code + OpenSpec
|
||||
/opsx:apply → Claude Code works through tasks
|
||||
Run multiple sessions in cmux split panes
|
||||
|
||||
4. Review Crit
|
||||
Review changes in browser → address comments → approve
|
||||
|
||||
5. Ship Claude Code
|
||||
Commit, push, deploy
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue