trip-plan/docs/PROJECT_OVERVIEW.md

Trip Plan — Project Overview

A self-hosted, multi-user web tool for collaboratively planning trips. Runs as a single Docker container.

Core Idea

Multiple people log in to the same instance. Anyone can create a trip by picking a name and a date range. The tool generates a day-by-day calendar for that range, and every member of the trip can fill in what happens on each day — flights, stays, transports, activities. The trip is visualized on an interactive map with the route drawn between stops, distances per leg, and an overall summary (days, nights, flights, total km).

Features

1. Users & Access (privacy-friendly, Mullvad-style)

• No registration form, no email, no password. Click "Create account" and you get a random account number (e.g. 7K2M-9QX4-TT8B-3WPF) — that token IS your login. It's shown once; only its hash is stored server-side.
• Every account gets an auto-generated, editable display name (e.g. brave-otter) so members and cost splits stay human-readable.
• Trips are shared via a join code: every trip has a short code (e.g. M4TH-8RK2); anyone with an account can enter it under "Join a trip" to become an editor. The owner can regenerate the code to cut off further joins.

2. Trips

• Create a trip with name + start date + end date.
• Editing the date range regenerates the calendar (existing day entries outside the new range are kept but flagged).
• Trip list dashboard showing all trips you're a member of.

3. Day-by-Day Calendar

• Calendar grid generated from the trip's date range (weeks as rows, like a real calendar).
• Click any day to open the day editor and add entries:

Entry type	Typical fields
📍 Activity / sightseeing	place, time, notes
🏙️ Stay (area block / accommodation)	location, from → until dates, hotel name in title, price
🚆 Transport	mode (train/bus/ferry/taxi/drive), from → to; auto-created between consecutive stays
✈️ Flight	flight no., from/to airports, departure/arrival time, multi-leg segments
🚙 Rental car	pickup/dropoff, included km
📝 Note	free text

(Legacy hotel/travel/immigration entries are migrated automatically at startup: hotel → stay, travel → transport, immigration → activity with a 🛂 title prefix.)

• Every entry can have a location (searched via OpenStreetMap geocoding — type "Chiang Mai" and pick from suggestions; lat/lng stored automatically).
• Entries show as compact chips inside the day cell; multiple entries per day, ordered.

4. Map Visualization

• Interactive map (Leaflet + OpenStreetMap tiles — free, no API key required, unlike Google Maps).
• All located entries plotted as markers, numbered in chronological order.
• Route polyline connecting the stops in order.
• Distance per leg (km, great-circle) shown on the route and in a leg-by-leg list.

5. Costs & Splitting

• Every entry can carry a price (flights, stays, car rental, train tickets, activities…), in the trip's currency (one currency per trip, no FX conversion).
• Each priced entry records who paid and how it's split:
  • equal — total split equally among selected participants (e.g. rental car 50/50)
  • own — price is per person, everyone pays their own (e.g. flights)
  • payer — personal expense of the payer
• Cost summary per trip: total cost, breakdown by type, per-user share vs. paid vs. net balance, and settle-up suggestions (who transfers how much to whom).

6. Summary

• Total days and nights.
• Number of flights, stays, transports.
• Total distance in km across the whole trip.
• Countries/locations visited (from entry locations).

Tech Stack

Layer	Choice	Why
Backend	Node.js 20 + Express	Small, ubiquitous, one runtime in the container
Database	SQLite (better-sqlite3)	Zero-config single file; persisted via Docker volume
Auth	cookie sessions + bcrypt	Simple and adequate for a self-hosted tool
Frontend	Vanilla JS SPA (no build step)	Keeps image small and the stack simple
Map	Leaflet + OpenStreetMap	Free, no API key, offline-friendly tiles options
Geocoding	Nominatim (proxied server-side)	Free location search, no key
Packaging	Dockerfile + docker-compose	docker compose up and you're running

Architecture

trip_plan/
├── src/server/           # Express app
│   ├── index.js          # bootstrap, static serving
│   ├── db.js             # SQLite schema + connection
│   ├── auth.js           # session middleware
│   ├── routes/           # auth, trips, entries, geocode
│   └── util/distance.js  # haversine km calc
├── public/               # SPA served statically
│   ├── index.html
│   ├── css/styles.css
│   └── js/               # api client, views (trips, calendar, map, summary)
├── tests/                # API tests (node:test + supertest)
├── data/                 # SQLite file (gitignored, volume-mounted)
├── docs/                 # this file + API.md
├── Dockerfile
└── docker-compose.yml

Data Model

users        (id, username, password_hash, created_at)
trips        (id, name, start_date, end_date, owner_id, created_at)
trip_members (trip_id, user_id, role)          -- owner | editor
entries      (id, trip_id, date, type, title, details,
              start_time, end_time, location_name, lat, lng, sort_order)

Route + km are derived: located entries ordered by (date, sort_order) form the route; each consecutive pair is a leg with haversine distance.

API (REST, JSON, under /api)

• POST /api/auth/account (create token account) · POST /api/auth/login · POST /api/auth/logout · GET/PATCH /api/auth/me
• GET/POST /api/trips · GET/PATCH/DELETE /api/trips/:id
• POST /api/trips/join (by join code) · POST /api/trips/:id/join-code (regenerate)
• GET/POST /api/trips/:id/entries · PATCH/DELETE /api/entries/:id
• GET /api/trips/:id/route (legs + km + summary, computed server-side)
• GET /api/geocode?q=... (Nominatim proxy)

Running It

# development
npm install
npm start                 # http://localhost:3000

# production
docker compose up -d      # builds image, mounts ./data for the SQLite file

Non-Goals (for now)

• Real-time collaborative editing (last-write-wins is fine for this scale)
• Driving-route distances via a routing engine (great-circle km first; OSRM could be added later)
• Email invites / password reset (admin resets via CLI)

Build Plan

1. Scaffold — repo, package.json, this doc, API contract. ✅
2. Swarm build (parallel agents): backend API + DB · frontend SPA (calendar, map, summary) · Docker/infra + tests.
3. Integrate & verify — run tests, boot server, smoke-test in browser, build Docker image.
4. Initial commit.