OpenTrip documentation

Travel Planner SaaS — plan trips together, split everything.

Published documentation

The Fumadocs site in apps/docs publishes this directory from two perspectives:

• user/index.mdx — outcome-oriented guidance for travelers.
• The project, frontend, backend, operations, quality, decisions, and reference sections below — implementation guidance for contributors.

Run make dev-docs to preview both perspectives at http://localhost:5171. The perspective switcher keeps user workflows separate from internal architecture without duplicating the underlying documentation. See CONTRIBUTING.md for audience, structure, screenshot, and review rules.

Map

Project

• project/README.md — product overview and scope.
• project/architecture.md — system architecture.
• project/handoff-implementation.md — prototype-to-product mapping.

Frontend (FSD)

• frontend/README.md
• frontend/layers.md
• frontend/ui-system.md
• frontend/map.md
• frontend/i18n.md
• frontend/data-caching.md — React Query write-echo (Hyperdrive read-after-write)
• frontend/miniapp.md — native WeChat WebView shell, one-time-code auth bridge, and embedded PWA behavior.

Client API (web, mobile, other apps)

Start here for multi-client development:

• backend/api/README.md — client HTTP contract index (routes, envelopes, DTOs, multi-client notes; split by resource)
• backend/auth.md — Better Auth mount, cookies/session, OAuth

Backend (DDD + Hexagonal)

• backend/README.md
• backend/domain.md
• backend/api/README.md — client-facing HTTP contract and DTOs
• backend/database.md
• backend/auth.md
• backend/agent.md
• backend/trip-ops.md — trip mutation registry (HTTP + agent)
• backend/weather.md — weather proxy, cache, agent tool
• backend/cover.md — Unsplash trip cover on create
• backend/fx.md — FX rates proxy for settle-up conversion
• backend/geo.md — geo places/routes (OSM/Google), agent tools
• backend/lodging.md — Airbnb lodging search, agent tools
• backend/street-view.md — provider-neutral street-view search, cards, viewer, and agent tools

Operations and quality

• operations/README.md
• operations/cloudflare.md
• operations/docker.md
• quality/README.md
• decisions/README.md

Reference sources

• reference/README.md

Implementation specifications

• superpowers/README.md

Repository layout

apps/
  web/   React + Vite frontend (FSD)
  docs/  Fumadocs static documentation site
  miniapp/ dependency-free native WeChat PWA shell
  api/   Hono backend (DDD + Hexagonal)
packages/
  agent-ui-catalog/  shared json-render catalog and spec safety boundary
deploy/
  cloudflare/  Pages + Workers + Hyperdrive
  docker/      Compose (postgres + api + web)
docs/          this documentation
scripts/       repo tooling (docs:check)