Treeper

Travel itinerary planner, tracker, and community — for people who plan their own trips, want to find or invite others to join them, and want AI to do the grunt work of turning a bookmarked reel into a real plan.

This repo is a monorepo. Code lives next to the specs that describe it.

For the what and why, start with PRODUCT.md and specs/product-vision.md.

For what’s shipped and what’s next, see specs/progress.md (live tracker) and specs/roadmap.md (sequencing).

For the how we work, see specs/README.md — Treeper uses Spec-Driven Development (SDD): every non-trivial change starts with a spec.

📚 Critical docs (start here)

The single jump‑off for everything operational. Detailed runbooks stay in their own files (they’re long and version-controlled next to what they describe); this table is the index.

Topic	Doc
Product plan (all features/subfeatures)	PRODUCT.md
Local dev recipe + per-app commands & gotchas	CLAUDE.md
Run the full local stack	RUN_LOCAL.md
Run mobile on iOS sim vs deployed APIs	RUN_SIM_PROD.md
Deploy (Coolify: apps, UUIDs, CLI gotchas, migrations)	infra/coolify/DEPLOY.md
iOS / Apple setup (App IDs, App Group, push, signing; account-move runbook)	apps/mobile/ios/APPLE_SETUP.md
Mobile ↔ web feature parity	apps/mobile/docs/WEB_PARITY.md
Instagram saved-export (ZIP) import	INSTAGRAM_EXPORT.md
Per-app setup	mobile · web · backend · workers
Infra	supabase · coolify · signoz
Architecture decisions (ADRs)	specs/adr/
Feature specs	specs/features/

Repository layout

treeper/
├── apps/
│   ├── mobile/              Flutter app (iOS + Android)        — apps/mobile/README.md
│   ├── web/                 Vite + React web frontend (map UI) — apps/web/README.md
│   ├── backend/             NestJS REST API + Supabase auth    — apps/backend/README.md
│   └── workers/             Python (FastAPI) — AI + scrapers   — apps/workers/README.md
├── packages/
│   └── contracts/           Shared TypeScript entity types (web consumes)
├── infra/
│   ├── docker/              docker-compose for local dev
│   └── coolify/             Deploy notes / templates for Coolify
├── scripts/                 Dev and deploy helper scripts
├── specs/                   Spec-Driven Development source of truth
│   ├── product-vision.md
│   ├── glossary.md
│   ├── roadmap.md
│   ├── progress.md          Milestone-level tracker (what's shipped)
│   ├── adr/                 Architecture Decision Records
│   ├── features/            Numbered feature specs
│   └── templates/
└── PRODUCT.md               Product plan, all features and subfeatures

Stack at a glance

Layer	Choice	Why (short)
Mobile	Flutter, pinned via fvm	One codebase, iOS + Android. See ADR-0001.
Web	Vite + React + TS (MapLibre)	Map-first web client; Supabase auth → `/v1` API. See ADR-0009.
Auth + DB + Storage	Supabase (Postgres, Auth, Storage)	Vibecode-friendly, OAuth + email built-in. See ADR-0002.
API / business logic	NestJS, JWT-verifies Supabase tokens	Structured backend without Supabase Edge Functions lock-in. ADR-0002.
AI + scraping	Python (FastAPI) workers	Best ecosystem for LLMs and scrapers. See ADR-0003.
Deploy	Docker images on Coolify	Self-hostable, Git-driven deploys. See ADR-0006.
Process	Spec-Driven Development	See ADR-0005.

Getting started

Prerequisites: git, docker, fvm (for Flutter), node 20+, python 3.11+, a Supabase project.

# 1. Pin Flutter to latest stable for the repo
fvm install stable
fvm use stable

# 2. Mobile app
cd apps/mobile
fvm flutter pub get
fvm flutter run

# 3. Backend + workers (local, via docker-compose)
cd ../../infra/docker
cp ../../apps/backend/.env.example ../../apps/backend/.env
cp ../../apps/workers/.env.example ../../apps/workers/.env
docker compose up --build

Each app has its own README with deeper setup notes, and CLAUDE.md holds the authoritative local-dev recipe (Supabase CLI from infra/, backend :3000, workers :8000, web :5173) plus the per-area gotchas.

Operations & deploy

Apps deploy on Coolify and track the main branch — so deploy = merge → push main, then Coolify auto-builds. DB migrations are applied by the treeper-migrator app whenever a file under infra/supabase/migrations/** changes. Full runbook (CLI gotchas, readiness signals, port labels): infra/coolify/DEPLOY.md.

App	Coolify UUID	FQDN
backend	`o14cr95wpi4d3m76grtxhnjx`	api-treeper.itssatya.in
workers	`r12jao9q6nzqxxujalfs0cj3`	workers-treeper.itssatya.in
web-app	`aol2ofb4kp60jq2vo02jkbki`	treeper.itssatya.in
supabase	—	supabase-treeper.itssatya.in

iOS / Apple (App IDs, App Group, push, share extension, TestFlight signing, and the moving-Apple-account runbook) → apps/mobile/ios/APPLE_SETUP.md. Mobile release builds need --dart-define SUPABASE_URL / SUPABASE_ANON_KEY / API_BASE_URL (see the mobile README).

Where to look

Want to use the product? → PRODUCT.md
Want to add a feature? → specs/README.md — write a spec first.
Want to know why a tech choice was made? → specs/adr/
Want to know what’s planned next? → specs/roadmap.md

License

TBD.