User Guide

You’re signed in, the dashboard is staring back at you, and now you want to actually log some travel. This page walks through what TravStats does, how its pieces fit, and which sub-page covers each.

The data model in one paragraph

TravStats stores three kinds of travel as domains of their own: flights, cruises, and lodging (hotels and other stays). A flight is one departure-to-arrival hop with metadata (airline, aircraft, seat, class, tags). A cruise is a voyage with an ordered list of port calls and sea days. A lodging is a house — a hotel, a guesthouse, an apartment, a hostel, a campsite — that carries its own stays, each with dates, room, board and price. A trip groups any of them: “Honeymoon 2024” can hold three flights, a seven-night cruise and two hotels. Tags are free-form labels (business, family, solo, 2026) that work across every domain. Achievements unlock automatically from what you’ve logged — distance milestones, country counts, specific routes, nights slept, ports called at.

A fourth domain, places (points of interest, with lists and curated checklists), exists in the code but sits behind the instance’s beta switch — see Beta features. So do tours (road, hike, bike and ferry sections on a trip).

Everything you log lives in your own Postgres. Statistics, maps, achievements — all derived from those tables. There’s no premium tier that hides features; if it’s in the code it’s yours.

Getting travel in

Ranked by how much typing they save:

1. Drop a document (seconds) — a confirmation mail (.eml, .msg, pasted text), a booking PDF, or a photographed hotel bill. The server decides on its own whether it is looking at a flight, a cruise or a hotel; the detection works without a language model. You always see a review screen before anything saves. Parsers covers the pipeline.
2. Scan a boarding pass (~10 seconds) — photograph the pass or upload an image. The barcode is read first and wins every field it carries; text recognition fills in what the barcode does not hold. The flight-lookup API fills in the rest.
3. Spreadsheet round trip (seconds for thousands) — the whole logbook exports to one workbook, a sheet per table, and comes back in Add only, Merge or Replace mode. Flights, cruises, lodging and places all travel this way. Spreadsheet has the rules.
4. List imports (migration) — a Flightradar24 or generic logbook CSV for flights, a hotel CSV for lodging, a Google Maps saved-places list. Every run is one batch that can be reverted whole. Import & Export.
5. Manual entry (~30 seconds) — the form for anything nobody has a document for. Airports autocomplete from the seeded catalogue; distance computes from the coordinates.

Whichever method you use, the result is the same row. You can edit any field after the fact, and re-importing the same flight (a boarding pass after you’d already entered it manually, for example) fills gaps without overwriting what you’ve curated.

Where you’ll spend your time

The dashboard is multi-domain: an All view that overlays everything, plus one tab per enabled domain — Flights, Cruises, Lodging (and Places and Tours on an instance with the beta switch on). Flights offer Routes, Globe, Heatmap, an airport-frequency map and animated Trips; cruises draw their itineraries as sea routes; lodging shows one pin per house. Every tab carries the same activity list beside the map, and picking an entry focuses it on the map instead of navigating away. The Maps page has the details.

Below the map sit the headline figures for the active tab. The deeper Statistics page has a tab per domain, a cross-domain overview, and a strip of headline tiles including days away — the one measure the domains can be compared on.

A second row covers achievements — 270+ badges in eight categories across flights, cruises, lodging and places. New ones unlock with each save and surface as a toast on the dashboard.

Countries are counted by evidence, not by where an aeroplane touched down: a completed stay, a recorded place, a port call, a day on the ground. A change of planes is kept but greyed out. The rules, the strictness setting and the passport page are on Countries & passport.

When two sources inside one record disagree — an address whose country differs from the stored one, a check-out before its check-in — nothing is corrected silently. The question lands in the Inbox, beside the flight proposals the enrichment APIs make.

Multi-user is built in, even if you’re alone

TravStats handles 1–10 users on one instance. Each user has their own travel, their own tags, their own statistics page. Admins can manage accounts but there is no shared logbook.

Set the user cap and registration mode (open vs invite-only) during the setup wizard or later under Admin. Every account can turn on two-factor authentication or a passkey. Even single-user instances benefit from Personal Access Tokens: mint a read-scoped token, point a script at the API, build whatever you want on top.

Backups, exports, and “what if I want to leave”

Three paths, depending on what you want out:

• Spreadsheet export (Settings → Backup) — one workbook with a sheet per table, column A the row’s id. Readable in any spreadsheet program and re-importable through Settings → Import. The everyday “give me my data” answer.
• Personal export (Settings → Backup) — your account as JSON, covering twelve domains, portable into another TravStats instance. Stored API keys are deliberately not in it.
• Database backup (Admin → Backups) — full Postgres pg_dump plus the upload directories (trip, place and lodging photographs, profile pictures). Daily by default, configurable retention, optional WebDAV sync.

Even if TravStats the project goes quiet, your data lives in a Postgres database in a Docker volume on hardware you own. Lock-in is the opposite of self-hosted, and we know it.

Where the rest of this section goes

• Flights — the add flow in detail, the flight detail page, bulk edits, the merge-on-re-import behaviour.
• Trips — group flights, cruises and stays into a journey with its own page, timeline, map and gallery. Tags vs trips.
• Maps & visualisations — modes per tab, the globe, the legend, what a click opens.
• Statistics — the domain tabs, the KPI strip, which entries count, and where the numbers come from.
• Achievements — the catalogue of 270+ badges, how each kind of badge is detected, hidden ones.
• Cruises — the port-call model, importing a booking, the editable sea route, cruise money.
• Lodging — hotels and stays: houses, stays, chains, loyalty programmes, photographs, what counts as a night.
• Places (beta) — points of interest, lists, curated checklists, the Google Maps import.
• Tours (beta) — road, hike, bike and ferry sections on a trip and their editor.
• Countries & passport — how a country is counted, the strictness setting, the passport page.
• Inbox — flight proposals and data-quality questions, and what each answer does.
• Money & currencies — 155 currencies, ECB rates, what a total leaves out and says so.
• Spreadsheet — the whole logbook as one workbook, and the three import modes.
• Import & Export — the import hub, list imports, batches and reverting them, JSON export, database backups.
• Security — two-factor authentication, recovery codes, passkeys, what an admin can reset.
• Settings — per-user preferences and the admin-only panel.
• Companion app (beta) — pairing a phone with a claim code, what the app reads.