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 today, cruises in v2, 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. 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.

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

Where you’ll spend your time

The dashboard has eight map modes for the same data — Routes, Globe, Heatmap, Hexagon, 3D Columns, Trips (animated), Contour, and Trip Routes. 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). 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 — what’s already wired on the v2 development branch, how to follow progress, what changes when v2 ships.
• 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).