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 flights and cruises, and treats both as members of larger trips. 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 trip groups them: “Honeymoon 2024” can hold three flights and a seven-night cruise, all sharing one tag for filtering. Tags are free-form labels (business, family, solo, 2026) that work across both flights and cruises. Achievements unlock automatically based on what you’ve logged — distance milestones, country counts, specific routes, equator crossings, and similar.

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

Four ways to add a flight

Ranked by how much typing they save:

1. Forward a confirmation email (~5 seconds) — the parser reads the route, date, and aircraft from the email body. The recommended setup uses your local Ollama LLM as the primary parser (handles any airline, including multi-flight bookings reliably). When Ollama is unavailable, regex templates for eight common European carriers (LH, LX, OS, SN, FR, U2, EW, W6) cover single-leg bookings as fallback. You always see a review screen before anything saves.
2. Scan a boarding pass (~10 seconds) — point the camera at the QR/PDF417 barcode or upload an existing photo. Three vision parsers cascade (Ollama vision → OpenAI/Claude → Tesseract OCR) until one extracts a usable flight number, then the flight-lookup API fills in the rest.
3. Bulk import from XLSX/CSV/JSON (seconds for thousands) — the fastest path for backfilling years of past flights. Round-trip XLSX is supported: export, edit in Excel, re-import the same file; rows with an id column update existing flights, rows without create new ones.
4. Manual entry (~30 seconds) — the form for old flights nobody has emails for any more. Departure/arrival airports autocomplete from the seeded ~9000-airport database; distance computes from the coordinates; you don’t enter it yourself.

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

Cruises are added the same way conceptually, with two methods: import a booking confirmation (email or PDF, LLM-parsed with an editable review screen — including the full itinerary and any bundled fly & cruise flights), or enter it manually. The Cruises page covers the cruise add flow, the port-call model, and cruise-specific achievements.

The Flights page goes into each flight method in detail and lists the symptoms-and-fixes for the parser misfires that come up.

Where you’ll spend your time

The dashboard is multi-domain: an All view that overlays everything, plus per-domain tabs (Flights, Cruises). Flights offer Routes, Globe, Heatmap and animated Trips modes; cruises draw their itineraries as sea routes with a port-frequency view. Each answers a different question; pick whichever fits what you’re looking at right now. Full details on the Maps page.

Below the map sit the statistics: total distance (”× around Earth”), total time, countries, top airlines, top aircraft, top airports. Filters on the left let you slice by year, tag, airline, country. Everything is reactive — pick a tag, the map and the numbers both update. The deeper Statistics page breaks them out into Fun, Business, and Unique sections with year comparison and a heatmap calendar.

A second row of stats covers achievements — over 100 unlockable badges across 8 categories (Explorer, Distance, Collector, Elite, Special, Planner, Survivor, Kurios), including a full set of cruise badges (ports, ships, cruise lines, sea days, cruise distance) that unlock independently of the flight ones. New ones unlock with each save and surface as a toast on the dashboard.

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

TravStats handles 1–10 users on one instance. Each user has their own flights, their own tags, their own statistics page. Admins can see everyone’s data but it’s not merged into one shared logbook.

Set the user cap and registration mode (open vs invite-only) during the setup wizard or anytime later under Admin → Settings. Even single-user instances benefit from the Personal Access Tokens feature: 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”

Two paths, depending on scale:

• Personal export (Settings → Data → Export) — your account as JSON, portable into a fresh TravStats instance. Includes flights, tags, achievements, your settings.
• Database backup (Admin → Settings → Backups) — full Postgres pg_dump of every user’s data. Daily by default, configurable retention, optional WebDAV sync to Nextcloud or HiDrive.

The schema is documented in the source. The export format is a plain JSON tree. Even if TravStats the project goes quiet, your data lives in a Postgres database in a Docker volume on hardware you own — nothing about that changes if upstream development slows down. Lock-in is the opposite of self-hosted, and we know it.

The Import & Export page covers both flows with the exact commands.

Where the rest of this section goes

• Flights — the four-method add flow in detail, parser symptoms-and-fixes, bulk-edit recipes (renaming an airline across hundreds of rows, applying a tag to a year of trips), the merge-on-re-import behaviour.
• Trips — group flights into a journey with its own page, photo gallery, and per-trip statistics. Tags vs trips: when to use which.
• Maps & visualisations — the eight visualization modes (Routes, Globe, Heatmap, Hexagon, Columns, Trips, Contour, Trip Routes) with what each is good for, plus filters.
• Statistics — what gets computed across the dashboard and Advanced Stats: Fun, Business, Unique sections, year heatmap, year-over-year comparison, year-report PDF.
• Achievements — full catalogue of unlockable badges across 8 categories, including the hidden easter eggs.
• Cruises — tracking cruise voyages: the port-call model, importing a booking from email or PDF (with fly & cruise flight extraction), ships & ports, sea-route maps, and cruise achievements.
• Import & Export — bulk import (JSON / CSV / XLSX), round-trip XLSX edits, manual pg_dump, full restore, cross-version migration order.
• Settings — per-user preferences (password, language, units, theme, tags, API tokens) and the admin-only panel (instance name, public URL, external API keys, SMTP, backups, users, audit log).