# TripTalley — Overview

TripTalley tracks money spent during a group trip so "who owes whom" is trivial
at the end. Standing user accounts + groups; trips belong to groups; expenses
belong to trips and are split among participants; settlement is computed on
demand (never stored) as a minimal set of "who pays whom" payments.

## Status
Design phase. No application code yet — the design is locked down in `docs/`.

## Key documents
- `PLAN.md` — owner's original design notes (platform strategy, decisions).
- `docs/DESIGN.md` — architecture & design spec (data model, API, settlement
  algorithm, FX strategy, sync). Source of truth for the backend.
- `docs/ERD.md` + `docs/img/erd.png` — SQLite schema ERD (Mermaid + rendered).
- `docs/UI_DESIGN.md` — mobile UI design (screens, nav, flows).
- `prototype/index.html` — interactive phone-framed click-through prototype.

## Architecture (decided)
- **All money logic server-side; thin client.** Amounts stored as integer
  **minor units** + ISO-4217 code (no floats).
- **Three currency roles:** original (as paid) → settlement (single canonical
  netting currency per trip) → display (per-viewer home currency, presentation
  only). Never net mixed currencies.
- **Convert once, at tally,** using the historical FX rate for each expense's
  date (Frankfurter/ECB, cached, business-day fallback).
- **Largest-remainder rounding** so splits always sum exactly to the total.
- **Debt simplification** for minimal transfers at settlement.
- **Offline-first sync:** idempotent upserts keyed by client-generated expense
  UUID; last-write-wins; soft deletes.
- **Stack (planned):** FastAPI + SQLite + SQLAlchemy backend; thin client is
  either native SwiftUI (per PLAN) or a web client for in-container demos —
  backend is identical either way (open decision, see docs/DESIGN.md §11).

## Structure
```
PLAN.md                owner design notes
docs/                  DESIGN.md, ERD.md, UI_DESIGN.md, img/erd.png
prototype/index.html   interactive mobile prototype (design artifact)
```

## Running things
See `DEPLOY.md`. Today only the static prototype runs:
`python3 -m http.server <port> --bind 0.0.0.0` from `prototype/`, then
`th-expose <port> <name>`. (8080 is often taken by another app on this box —
pick a free port.)