Your Journeys, Completely Offline & Fully Synced

The premium, offline-first personal travel organizer and itinerary planner. Take control of your data with lightning-fast local performance.

TravelBuff Dashboard showing destination cards

Powerful Travel Planning

AI Travel Importer

AI-Powered Assistant & Import

Instantly parse travel guides and automatically categorize sights, restaurants, and stays with intelligent context mapping.

Immich Photo Sync

Immich Server Integration

Directly link your self-hosted Immich photo galleries to your visited locations for a unified memory timeline.

Dual Mapping System

Dual Mapping System

Native OpenStreetMap (OSM) default with seamless runtime fallback to Google Maps for precise geocoding.

Media Extracts

Media Extracts & Context

Enrich your visited sights with dynamic Wikipedia Commons integrations, precise location tags, and detailed notes.

Daily Itinerary Planner

Daily Itinerary Planner & Budget

Organize your days with a chronological timeline. Track your spent budget in multi-currency with real-time limits.

Offline-First Sync

Offline-First & Real-Time Sync

Built with Dexie.js for persistent local operations. Dynamic WebSocket syncing propagates your changes across devices.

Download & Deploy TravelBuff

Choose your preferred deployment method below to get started.

Self-Hosted via Docker

Deploy instantly from Docker Hub with zero configuration.

Install on Desktop

Run locally on Windows, macOS, or Linux via ZIP download or GitHub clone.

Self-Host via Docker Hub

Pull the official pre-built image directly from Docker Hub: abhishekkharvadi/TravelBuff:latest

Access Application via Web Browser

Once deployed, open your browser and navigate to:

http://localhost:5000/ ↗
Auto-starts with System: The --restart unless-stopped policy ensures that the TravelBuff container automatically boots whenever Docker or your computer starts up.

Option A: Standard Docker CLI Run

Terminal Command 
# 1. Pull the official Docker image
docker pull abhishekkharvadi/TravelBuff:latest

# 2. Run the container on port 5000
docker run -d \
  -p 5000:5000 \
  --name travelbuff \
  -v travelbuff_data:/app/data \
  --restart unless-stopped \
  abhishekkharvadi/TravelBuff:latest

Option B: Docker Compose (Recommended)

Create a file named docker-compose.yml in your project directory:

docker-compose.yml 
version: '3.8'

services:
  travelbuff:
    image: abhishekkharvadi/TravelBuff:latest
    container_name: travelbuff
    restart: unless-stopped
    ports:
      - "5000:5000"
    environment:
      - PORT=5000
      - NODE_ENV=production
    volumes:
      - travelbuff_data:/app/data

volumes:
  travelbuff_data:
    driver: local

Starting Docker Compose

Terminal
docker compose up -d

How to Stop & Delete / Remove TravelBuff

To pause, stop, or permanently remove the TravelBuff container, data volumes, and Docker images:

Docker CLI (Stop & Delete)
# Stop the running container
docker stop travelbuff

# Remove container and associated data volume
docker rm -f travelbuff
docker volume rm travelbuff_data

# (Optional) Remove the downloaded Docker image
docker rmi abhishekkharvadi/TravelBuff:latest
Docker Compose (Stop & Delete)
# Stop and clean up containers along with data volumes
docker compose down -v

# (Optional) Remove image
docker rmi abhishekkharvadi/TravelBuff:latest

Select Your Operating System

Click your platform icon to view setup instructions via ZIP download or GitHub repository.

macOS

Apple Silicon & Intel Macs

Linux

Ubuntu, Debian, Arch, Fedora

Windows

Windows 10 & 11 (PowerShell)

Install on macOS

Prerequisite: Node.js 18+ installed on your Mac.

Access Application via Web Browser

Once launched, open your browser and navigate to:

http://localhost:3000/ ↗
Auto-starts when your laptop boots: PM2 automatically saves your running instance and registers a macOS startup service, so TravelBuff starts automatically in the background whenever you turn on or log into your Mac.

Option 1: Direct ZIP Download (Recommended)

Download source code without needing Git installed.

Download
Terminal (Extract & Run with Auto-Start)
# 1. Unzip the downloaded file & enter directory
unzip ~/Downloads/TravelBuff-main.zip -d ~/
cd ~/TravelBuff-main

# 2. Install dependencies & build
npm install
npm run build

# 3. Start app in background with PM2
npx pm2 start server.js --name travelbuff

# 4. Enable automatic start on laptop boot
npx pm2 startup
npx pm2 save

Option 2: Clone via Git

Clone directly from the GitHub repository.

macOS Terminal
git clone https://github.com/abhishekkharvadi/TravelBuff.git
cd TravelBuff
npm install
npm run build

# Start app & configure auto-start on boot
npx pm2 start server.js --name travelbuff
npx pm2 startup
npx pm2 save

How to Stop & Delete / Uninstall TravelBuff on macOS

To stop the background service or completely remove TravelBuff and its files from your Mac:

macOS Terminal
# 1. Stop the running background process
npx pm2 stop travelbuff

# 2. Remove from PM2 process list & save state
npx pm2 delete travelbuff
npx pm2 save

# 3. (Optional) Disable automatic startup on Mac boot
npx pm2 unstartup

# 4. Remove project folder & files
rm -rf ~/TravelBuff-main ~/TravelBuff

Install on Linux

Tested on Ubuntu 22.04 LTS, Debian 12, and Fedora 38.

Access Application via Web Browser

Once launched, open your browser and navigate to:

http://localhost:3000/ ↗
Auto-starts on system boot: Systemd integration via PM2 ensures TravelBuff restarts automatically as a system service whenever your machine or server restarts.

Option 1: Direct ZIP Download

Download source code archive via CLI or Browser.

Download
Linux Terminal
# 1. Download & Extract ZIP
wget https://github.com/abhishekkharvadi/TravelBuff/archive/refs/heads/main.zip
unzip main.zip
cd TravelBuff-main

# 2. Install & Start
npm install
npm run build
npx pm2 start server.js --name travelbuff

# 3. Configure auto-start on boot via systemd
npx pm2 startup systemd
npx pm2 save

Option 2: Clone via Git

Terminal
git clone https://github.com/abhishekkharvadi/TravelBuff.git
cd TravelBuff
npm install
npm run build

# Start & configure auto-start on boot
npx pm2 start server.js --name travelbuff
npx pm2 startup systemd
npx pm2 save

How to Stop & Delete / Uninstall TravelBuff on Linux

To stop the background service or completely delete TravelBuff from your system:

Linux Terminal
# 1. Stop background service
npx pm2 stop travelbuff

# 2. Remove process & save state
npx pm2 delete travelbuff
npx pm2 save

# 3. Disable systemd auto-start service
npx pm2 unstartup systemd

# 4. Remove project files
rm -rf ~/TravelBuff-main ~/TravelBuff

Install on Windows

Run via PowerShell or Command Prompt (Node.js 18+ required).

Access Application via Web Browser

Once launched, open your browser and navigate to:

http://localhost:3000/ ↗
Auto-starts when your laptop boots: Use PM2 background manager with pm2 save or add a launcher script to your Windows Startup folder (shell:startup) to ensure TravelBuff runs automatically every time Windows boots.

Option 1: Direct ZIP Download (Recommended)

Download and extract ZIP directly without Git command line.

Download
PowerShell Commands
# 1. Download & Extract using PowerShell
Invoke-WebRequest -Uri "https://github.com/abhishekkharvadi/TravelBuff/archive/refs/heads/main.zip" -OutFile "main.zip"
Expand-Archive -Path "main.zip" -DestinationPath "."
cd TravelBuff-main

# 2. Install dependencies & build
npm install
npm run build

# 3. Start background process with PM2 & save for auto-start
npx pm2 start server.js --name travelbuff
npx pm2 save

Option 2: Clone via Git

PowerShell
git clone https://github.com/abhishekkharvadi/TravelBuff.git
cd TravelBuff
npm install
npm run build

# Start background process & save
npx pm2 start server.js --name travelbuff
npx pm2 save

How to Stop & Delete / Uninstall TravelBuff on Windows

To stop the background process or remove TravelBuff completely from Windows:

PowerShell (Stop & Delete)
# 1. Stop and remove PM2 background process
npx pm2 stop travelbuff
npx pm2 delete travelbuff
npx pm2 save

# (Alternative) Force terminate any active node server
Stop-Process -Name node -Force -ErrorAction SilentlyContinue

# 2. Remove project files and folders
Remove-Item -Recurse -Force .\TravelBuff-main, .\TravelBuff -ErrorAction SilentlyContinue

1. Overview & Features

Welcome to the official documentation for TravelBuff — your personal travel organizer and itinerary planner designed to work seamlessly across all your devices, even when you're offline.

TravelBuff Main Dashboard Overview
Figure 1.1: TravelBuff Main Dashboard Overview

The TravelBuff Philosophy

TravelBuff is designed for travelers who value reliability, speed, and privacy. Traditional travel planners stop working when you lose internet connection in remote locations, subways, or during flights. TravelBuff solves this with an Offline-First approach:

  • All your travel details are saved directly on your device.
  • Any changes you make show up instantly without waiting for a connection.
  • When you reconnect to the internet, your changes automatically sync with your backup account.
  • Live updates automatically sync across your phone, tablet, and computer so all your devices stay up to date.

Core Features

  • Organized Folders & Tags: Group your destinations and regions into clear folders with custom labels.
  • Visited Badges: Easily see where you've been with visual "Visited", "Partial", and "Not Visited" status indicators.
  • Interactive Maps & Numbered Routes: View your spots on interactive maps with clear step-by-step numbered markers (#1, #2, #3...).
  • AI Trip Importer: Automatically convert web articles, travel guides, or documents into structured travel plans with smart location details.
  • Photo & Travel Companion Sync: Connect with your photo library server to easily tag travel companions with face photo avatars.
  • GPS Travel Log Import: Import GPS logs from your trips to accurately measure your actual travel distances.
  • Multi-Currency Expense Tracker: Log expenses in any currency and set custom exchange rates to stay on top of your travel budget.
  • Mobile-Friendly Design: Simple, easy-to-use interface optimized for smartphone screens and touch navigation.
Interactive Map with Step-by-Step Numbered Routes
Figure 1.2: Interactive Map with Step-by-Step Numbered Routes
Visited Status Indicators
Figure 1.3: Visited Status Indicators (Visited, Partial, Not Visited)

2. Setting Up TravelBuff

Prerequisites Check (All Operating Systems)

Before setting up TravelBuff, ensure you have Node.js (version 18 or higher) installed on your computer:

  1. Open your terminal or Command Prompt.
  2. Type node -v and press Enter.
  3. If Node.js is installed, you will see a version number (such as v18.16.0 or v20.9.0). If not, download and install Node.js from nodejs.org.

Step 1: Open the Project Folder

Open your command line tool and navigate to where you downloaded or extracted the TravelBuff project files:

macOS / Linux
cd ~/Downloads/TravelBuff
Windows
cd C:\Users\YourUsername\Downloads\TravelBuff

Step 2: Install Required Packages

Download all the application components by running the install command in your terminal:

Terminal
npm install

This process takes about a minute to complete and sets up all necessary libraries automatically.

Step 3: Create & Configure Environment Settings (.env)

TravelBuff uses a configuration file named .env in the main folder to manage basic application settings.

1. Example Configuration Template:

.env
# Port number where TravelBuff will run (Default: 3000 for Desktop, 5000 for Docker)
PORT=3000

# Secret phrase used to secure user accounts
JWT_SECRET=my-travelbuff-secret-key-12345

# Folder path for storing uploaded photos and documents
UPLOADS_DIR=./data/uploads

2. How to create the .env file on your Operating System:

  • macOS / Linux: Run touch .env then edit with nano .env. Press Ctrl + O to save, and Ctrl + X to exit.
  • Windows: In PowerShell run New-Item .env -ItemType File, then open in Notepad and save.

Step 4: Launch TravelBuff

You can choose to run TravelBuff interactively in your terminal or continuously in the background with automatic startup on machine boot.

Option A: Run Interactively (Foreground Mode)

Terminal
npm run dev
Launching TravelBuff via npm run dev
Figure 2.1: Launching TravelBuff via npm run dev

Option B: Run in the Background with Auto-Start on Boot (PM2)

Run TravelBuff as a background daemon that automatically resumes whenever your computer turns on:

Terminal (macOS & Linux)
# 1. Start application under PM2 process supervisor
npx pm2 start server.js --name travelbuff

# 2. Configure system hook to auto-launch TravelBuff on system startup
npx pm2 startup
npx pm2 save

Option C: Deploying via Docker & Docker Compose

Docker CLI
docker run -d \
  --name travelbuff \
  -p 5000:5000 \
  -e PORT=5000 \
  -e JWT_SECRET=your-secure-jwt-secret-here \
  -v travelbuff_data:/app/data \
  -v travelbuff_uploads:/app/data/uploads \
  --restart unless-stopped \
  abhishekkharvadi/travelbuff:latest
Deploying via Docker CLI / Container setup
Figure 2.3: Deploying via Docker CLI / Container setup

Step 5: Open TravelBuff in Your Web Browser

Once started, open your web browser (Chrome, Safari, Edge, or Firefox) and navigate to the application address:

Managing, Stopping & Deleting TravelBuff

Useful management commands for checking service status, stopping the application, or clean uninstallation:

1. Checking Status & Logs

Terminal
# Check active process status
npx pm2 status

# View live application logs
npx pm2 logs travelbuff

2. Stopping the Application

Terminal
# Desktop (macOS / Linux / Windows)
npx pm2 stop travelbuff

# Docker
docker stop travelbuff

3. Complete Uninstall & Deletion

Terminal
# Desktop (macOS / Linux):
npx pm2 delete travelbuff
npx pm2 save
rm -rf ~/TravelBuff-main ~/TravelBuff

# Docker:
docker rm -f travelbuff
docker volume rm travelbuff_data

3. Setting Up Locations & Folders

Adding Locations & Folders

  • Add a Location: Click the + Add Location button on the Locations screen.
  • Search & Auto-Fill: Start typing your destination in the search bar. Location details—including name, state, country, and map coordinates—are automatically filled in.
  • Automated Featured Cover Photos: TravelBuff automatically searches for and downloads a featured cover photo in the background.
  • Folder Option: Check Create as Folder or click Convert to Folder on any location to contain sub-locations or cities.
Add Location Drawer with Automated Geocoding
Figure 3.1: Add Location Drawer with Automated Geocoding
Hierarchical Folder View
Figure 3.2: Hierarchical Folder View (Countries, States, Cities)

Global Duplicate Prevention

TravelBuff features automatic, live duplicate detection that inspects the entire database across all folders and locations, regardless of hierarchical nesting depth.

  • Multi-Factor Matching: Evaluates exact/normalized names, state/country pairings, and GPS coordinates within 150 meters.
  • Inline Warning Banner: Displays existing parent hierarchy breadcrumbs with a direct "View Existing Folder/Location" jump button.
Global Duplicate Prevention Warning Banner
Figure 3.6: Global Duplicate Prevention Warning Banner

Places of Visit & Categorization

  • Multiple Places per Location: Store cafes, hotels, waterfalls, or museums inside any folder.
  • Spot Categories: Assign categories (hotel, stay, restaurant, cafe, temple, museum, waterfall, mountain, airport, etc.).
  • Coordinates & Descriptions: Exact map coordinates and custom notes for each place.
Places of Visit & Spot Category Badges
Figure 3.3: Places of Visit & Spot Category Badges

Filtering & Sorting Locations

  • Text Search: Instant text search across all locations and places.
  • Country & State Filters: Filter by specific countries or states.
  • Visited Status: Filter by Visited, Not Visited, or Partial.
  • Sorting Options: Sort by Date Added, Alphabetical Order, or Visited Status.
Filter & Sorting Controls
Figure 3.4: Filter & Sorting Controls

Interactive Maps & Image Sources

Map pins render interactively on Leaflet/OpenStreetMap by default, with optional Google Maps place search integration via API key.

Visit History & Immich Integration

Connect your self-hosted Immich photo album server to auto-link memories, or log manual visit date ranges to mark locations as ✓ Visited.

Immich Photo Server Album Linking & Visit Logs
Figure 3.5: Immich Photo Server Album Linking & Visit Logs

4. Collections

System Collections & Custom Collections

  • Visited Places: Automatically gathers all locations marked as ✓ Visited.
  • Bucket List (Not Visited): Gathers all items marked as ○ Not Visited.
  • Custom Collections: Group spots by custom themes using Manual Selection or Auto-Group Rules.
Collections Grid
Figure 4.1: Collections Grid (System & Custom Collections)

Classification Methods: Manual vs. Auto-Group

  1. Manual Selection: Hand-pick specific destination folders or individual places from a searchable tree.
  2. Auto-Group Rules: Automatically populate collections using locations, categories, tags, or keyword matching with Match ANY (OR) or Match ALL (AND) logic.
Manual Selection Tree Selector
Figure 4.2: Manual Selection Tree Selector
Auto-Group Rule Builder
Figure 4.3: Auto-Group Rule Builder

Multi-Select Mode & Bulk Deletion

Manage collections in batches with the interactive selection mode:

  1. Click the "Select" button in the Collections header.
  2. Selection checkboxes will appear on each custom collection card (System collections remain protected).
  3. Click cards to toggle selection (or click "Select All" in the floating bottom action bar).
  4. Click "Delete (N)" to remove selected collections while safely preserving all underlying locations and places.
  5. Click "Done Selecting" to exit multi-select mode.
Multi-Select Mode & Bulk Selection Controls
Figure 4.5: Multi-Select Mode & Bulk Selection Controls

Step-by-Step Practical Examples

  • Example 1: "Wonders of the World": Manual selection of Taj Mahal, Colosseum, Machu Picchu, Great Wall of China, and Petra.
  • Example 2: "Excellent Restaurants in Delhi": Auto-Group by Location (Delhi) + Category (restaurant, cafe) with Match ALL logic.
  • Example 3: "Places for a Day Trip from Chennai": Auto-Group by tag #DayTrip or manual selection (Mahabalipuram, Kanchipuram, Pondicherry).
  • Example 4: "Paris Cultural Landmarks": Auto-Group Paris locations matching museum and monument categories.
  • Example 5: "Tokyo Coffee Trail": Auto-Group Tokyo locations matching cafe category.
Master Collection Map View
Figure 4.4: Master Collection Map View

5. Importing Guides & Using AI

How to Import Content (Step-by-Step Examples)

1. Importing a Web Page URL

Click Import Content -> 🌐 Import Web Page. Select a scraper engine (Jina Reader, Cheerio, Playwright, or Firecrawl) and click Fetch Guide.

2. Importing a Travel Document

Click Import Content -> 📄 Import Document. Upload .md, .pdf, .docx, .html, or .txt files using Fast Local Parser or AI Document Vision Parser.

Import Content Modal (Web URL & File Upload)
Figure 5.1: Import Content Modal (Web URL & File Upload)

Accessing & Resuming Saved Guides

All imported raw content is stored in your database under Settings -> Saved Travel Guides with full automatic progress auto-save.

Saved Travel Guides Table
Figure 5.2: Saved Travel Guides Table

The 3 Review Workspace Tabs & Their Importance

  1. 📄 Original Guide Tab: Inspect converted Markdown text with interactive selection and duplicate detection.
  2. ⚙️ Review Data Tab (Curation Queue): Destination settings, bulk location assignments, inline creation, and row editing.
  3. 🗺️ Places from this Guide Tab: Places grouped neatly by assigned day numbers with 1-click itinerary generation.
Original Guide Tab with Duplicate Headings Detection
Figure 5.3: Original Guide Tab with Duplicate Headings Detection
Review Data Curation Queue & AI Analysis Toolbar
Figure 5.4: Review Data Curation Queue & AI Analysis Toolbar
Places from Guide Tab & 1-Click Itinerary Export
Figure 5.5: Places from Guide Tab & 1-Click Itinerary Export

Action Toolbar & AI Buttons Guide

Features batch OpenStreetMap geocoding, multi-model AI analysis (Gemini, OpenAI, Claude, Ollama), custom prompt console, and batch saving.

Custom AI Prompt Console Drawer
Figure 5.6: Custom AI Prompt Console Drawer

Exporting to a Trip Itinerary

Click ➕ Add Itinerary on the places tab to generate a complete multi-day trip complete with numbered map pins.

6. Creating Itinerary Plans & Travelers

Trip Planner Overview

Manage multi-day trips, active trip view, booking confirmations, companion photo tags, and budget tracking from a clean card layout.

Trip Planner Dashboard & Active Trip Mode Badge
Figure 6.1: Trip Planner Dashboard & Active Trip Mode Badge

Planning a New Trip Setup Wizard

  • Step 1: Basic Trip Details: Title, dates, description, base currency, budget limit, and starting home address.
  • Step 2: Planning Mode: Choose Manual Mode or AI Assisted Mode (with arrival time setup and AI route optimization).
2-Step Trip Creation Wizard
Figure 6.2: 2-Step Trip Creation Wizard

Selecting Locations or Collections for Your Trip

Select parent folders or collections to populate your trip's Places Bank for easy drag-and-drop planning.

Domestic vs. International Trips

Domestic trips track expenses in single home currency, while international trips enable multi-currency logging with custom exchange rate overrides.

The 3-Column Planning Workspace

  • Column 1 (Left): Places Bank: Searchable pool of saved locations and collections ready to add, with quick AI Plan generation.
  • Column 2 (Middle): Daily Schedule: Chronological drag-and-drop itinerary with automatic route distances & driving durations.
  • Column 3 (Right): Interactive Route Map: Color-coded daily sequence paths with numbered markers and geodesic flight arcs.
Interactive 3-Column Planning Workspace
Figure 6.3: Interactive 3-Column Planning Workspace with Stays and Start-from-Home Routing

Daily Stays, Start from Home & Transport Modes

  • Day 1 Start from Home: Toggle [x] Start from Home to incorporate your origin address as the initial route point.
  • Drive to Stay First: Check [x] Drive to stay first for check-in or dropping luggage before sightseeing.
  • Daily Stay Behaviors: Choose between 🔄 Stay here at night (round-trip loop), ➡️ Checkout from Hotel (moving onward), or 🏁 Late check-in.
  • Multi-Modal Transport Modes: Set per-segment modes (🚗 Drive, ✈️ Flight with curved arcs, 🚆 Train, 🚶 Walk, ⛴️ Ferry).
  • Reset & 1-Click Undo: Safely reset itineraries with the option to ↺ Undo Reset instantly from local snapshots.

Workspace Sub-Tabs

Switch between Itinerary (stops & maps), Budget (spent vs target), and Notes (packing lists & documents).

Workspace Sub-Tabs (Itinerary, Budget, Notes)
Figure 6.4: Workspace Sub-Tabs (Itinerary, Budget, Notes)

7. Expense Tracking & Home Addresses

Planned vs. Actual Expenses

Compare planned target allocations against real-time actual spending with visual color-coded budget progress bars.

Planned Budget vs Actual Spent Progress Bar
Figure 7.1: Planned Budget vs Actual Spent Progress Bar

Recording Expenses & Receipt Attachments

Record costs with currency, category (Lodging, Food, Transit, Shopping), notes, and receipt photo uploads. Flight/hotel bookings automatically sync with expenses.

Log Expense Entry & Receipt Attachment Upload
Figure 7.2: Log Expense Entry & Receipt Attachment Upload

Multi-Currency Budgets & 160+ World Currencies

TravelBuff supports all official ISO 4217 world currencies (~160+) with searchable combobox filtering (by code, name, or symbol) and the top 12 popular currencies pinned at the top.

Searchable 160+ ISO Currency Combobox
Figure 7.6: Searchable 160+ ISO Currency Combobox with Pinned Major Currencies

Custom Exchange Rate Overrides

Convert foreign currency costs to base currency automatically or input custom conversion overrides from local exchange kiosks.

Custom Foreign Exchange Rates Override Table
Figure 7.3: Custom Foreign Exchange Rates Override Table

Expense Analytics & Reports

Interactive category charts and printable summary reports for expense reimbursement or tax records.

Category Expense Analytics & Breakdown Charts
Figure 7.4: Category Expense Analytics & Breakdown Charts

Saved Home Addresses

Set primary home location under Settings to compute starting routes for all planned journeys.

Saved Home Addresses Setup Table
Figure 7.5: Saved Home Addresses Setup Table

8. Trip Mode (On-the-Road Companion)

Why Trip Mode is Essential While Traveling

Trip Mode transforms TravelBuff into a streamlined, mobile-optimized, single-screen travel companion designed for effortless one-handed use on the road.

Key Features of Trip Mode

  1. Today's Streamlined Schedule: Shows today's stops with category icons, turn-by-turn map links, and distances.
  2. 100% Offline Mode & Instant Local Sync: Everything is stored locally on device and automatically syncs when internet reconnects.
  3. Quick Expense Logger: Log coffee or taxi cash expenses in 1 tap offline with receipt photo attachment.
  4. Nearby Food & Cafe Finder: Locates restaurants, cafes, and vegetarian spots within 2 km using live GPS with a 1-click Bookmark to Itinerary button.
  5. Instant Booking Vouchers: Fast access to hotel reservations and flight tickets with built-in PDF/image viewer.
  6. GPS Travel Log Import: OwnTracks integration to calculate actual kilometers traveled vs planned route estimates.
  7. Quick Trip Notes: Jot down room numbers, door codes, or reminders instantly.
Mobile Trip Mode Single-Screen Schedule View
Figure 8.1: Mobile Trip Mode Single-Screen Schedule View
100% Offline Mode & Instant Local Storage Status
Figure 8.2: 100% Offline Mode & Instant Local Storage Status
One-Tap Mobile Quick Expense Logger
Figure 8.3: One-Tap Mobile Quick Expense Logger
2 km Radius Nearby Food Finder & 1-Click Bookmark
Figure 8.4: 2 km Radius Nearby Food Finder & 1-Click Bookmark
Instant Booking Vouchers & PDF Viewer
Figure 8.5: Instant Booking Vouchers & PDF Viewer

9. Settings & Administration

TravelBuff provides a structured, 6-tab Hybrid Settings interface with a persistent Global Live Search bar at the top:

  • Global Live Search: Type any keyword (e.g., "Immich", "API key", "Backup", "Currency") for instant matching across all settings. Clicking any result switches directly to the tab and smoothly scrolls to the section with an active glow outline.
6-Tab Hybrid Settings Interface Overview
Figure 9.0: 6-Tab Hybrid Settings Interface Overview
Global Live Search Across All Settings
Figure 9.0b: Global Live Search Across All Settings Sections

1. ⚙️ General & Preferences

  • Base Currency: Select your home currency from 160+ ISO currencies.
  • Default Navigation Map App: (iOS/macOS) Choose between Google Maps and Apple Maps.
  • Saved Home Addresses: Manage origin and destination coordinates for automated trip routing.

2. 🔌 Integrations & AI

  • Immich Server Settings: Endpoint URL, API key, connectivity tester, and public web gallery links.
  • People & Companions (Immich Face Sync): Embedded inside the Immich card to sync recognized face profiles into travel companion avatars.
  • AI Assistant Configuration: Connect OpenAI, Claude, Gemini, Ollama, DeepSeek, Groq, or OpenRouter with custom model selectors and Firecrawl API scraping.
  • Google Maps Integration: Google Maps API key integration for Maps JavaScript, Directions, Geocoding, and Places APIs.
  • OwnTracks GPS Integration: Webhook target URL for live GPS trail logging.
Immich Photo Server Configuration & Connection Tester
Figure 9.1: Immich Photo Server Configuration & Connection Tester
Multi-Model AI Provider Selector & Endpoint Setup
Figure 9.2: Multi-Model AI Provider Selector & Endpoint Setup
Google Maps API Integration Panel
Figure 9.3: Google Maps API Integration Panel

3. 🏷️ Taxonomy & Tags

  • Keyword Tags: Custom taxonomy tags with HEX color pickers.
  • Custom Categories: Custom place categories with emoji icons (📌, 🍜, 🏰).
Custom Categories & HEX Color Tag Selector
Figure 9.6: Custom Categories & HEX Color Tag Selector

4. 💾 Data & Backups

  • Backup & Restore Data: Export full JSON backups or restore in chunked background uploads.
  • Archived Items & Data Retention: View, restore, or permanently delete archived locations.
  • Saved Travel Guides: Review, resume curating, or delete scraped markdown guides.
Database Backup Export & Progress Recovery Modal
Figure 9.4: Database Backup Export & Progress Recovery Modal

5. 👤 Account & User Management

  • My Profile & Security: Profile picture avatar upload and self-service password updates.
  • User Management (Admin Only): User registry table, role assignments, password resets, and complete cascade data deletion.
Admin User Management Registry & Account Wiping
Figure 9.5: Admin User Management Registry & Account Wiping

6. 🖥️ System, Telemetry & API Logs

  • Privacy & Telemetry: 100% anonymous usage statistics toggle and preview payloads.
  • External API Usage Logs: 6-month request tracking across Google Maps, OSRM, Wikipedia, and AI with CSV export.
  • Help & Guided Onboarding: Restart interactive spotlight tours, reopen the Getting Started checklist, and access release notes.

10. Helpful Tips & Shortcuts

📍 Automatic Coordinate Smart Parsing

Paste coordinate strings like 28.6139° N, 77.2090° E or 28.6139, 77.2090 directly into address search; TravelBuff automatically parses and splits latitude/longitude.

Video 10.1: Automatic Coordinate Smart Parsing Demo

⌨️ Keyboard Shortcuts & Modal Controls

Press Esc to dismiss dialog modals, photo viewers, and prompt consoles instantly.

🌐 Native Browser History & Direct Web Bookmarking

Full support for browser back/forward buttons (Alt + Left Arrow / Cmd + [) and direct folder bookmarking (Cmd + D / Ctrl + D).

🍽️ 1-Click Food Spot Bookmarking in Trip Mode

Click Find Nearby Food while in Trip Mode, browse venues within 2 km, and click Bookmark to insert directly into today's itinerary.

🚚 Drag & Drop Itinerary Reordering

Drag stops up or down to re-sequence days while driving distances and durations automatically update in real-time.

Video 10.2: Drag & Drop Itinerary Stop Reordering Demo

✈️ Offline Pre-Loading for Flights & Subways

Open active trip in Trip Mode before boarding flights to cache schedules, hotel vouchers, and maps completely offline.

11. Mobile & Screen Adaptability

Mobile & Screen Adaptability Features

  • Flexible Header Layouts: Navigation automatically shifts for compact phone displays.
  • Fixed Bottom Navigation Bar: Quick touch navigation between Locations, Collections, Trips, and Settings on smartphones.
  • Notch & Edge Padding: Automatic safe area insets to prevent phone home bars from obscuring controls.
Mobile Smartphone Fixed Bottom Navigation Bar
Figure 11.1: Mobile Smartphone Fixed Bottom Navigation Bar
Mobile Screen Edge Padding & Notch Adaptability
Figure 11.2: Mobile Screen Edge Padding & Notch Adaptability

12. Release Notes & Version History

Version 7.4.1 (Current Release)

Locations view reliability update:

  • Locations View Runtime Crash Fix: Fixed ReferenceError: Sparkles is not defined runtime exception on the Locations home screen by importing Sparkles from lucide-react.

Version 7.4.0

Major features & navigation architecture:

  • Global Duplicate Prevention for Folders & Locations: Live duplicate search inspecting names, country/state, and GPS proximity within 150 meters across all hierarchy levels with parent breadcrumbs banner.
  • Collection Multi-Select Mode & Bulk Deletion: Added "Select" / "Done Selecting" toggle in Collections header with card checkboxes and floating bulk action bar.
  • Re-organized Hybrid 6-Tab Settings with Global Live Search: 6 distinct tabs (General & Preferences, Integrations & AI, Taxonomy & Tags, Data & Backups, Account, System) with top fuzzy search bar and scroll glow highlight.
  • App Update Notification Banner & "What's New in v7.4.0" Modal: Persistent update notification banner and rich "What's New" modal dialog.
  • Avatar Dropdown Menu Cleanup: Streamlined user profile dropdown with direct "What's New" link and synchronized APP_VERSION footer.
Profile Menu & v7.4.1 Release Navigation
Figure 12.2: Profile Menu & v7.4.1 Release Navigation

Version 7.3.0

Timeline endpoint checkboxes, stay anchors & flight arcs:

  • Timeline Endpoint Checkboxes & Stay Behaviors: Added Day 1 Start from Home, Drive to Stay First, and configurable Stay behaviors (🔄 Stay here at night, ➡️ Checkout, 🏁 Late check-in).
  • Itinerary Reset & Undo Snapshot: Added reset button with 1-click ↺ Undo Reset recovery.
  • Multi-Modal Transport Modes: Per-segment modes (🚗 Drive, ✈️ Geodesic Flight Arcs, 🚆 Train, 🚶 Walk, ⛴️ Ferry).

Version 7.2.0 - 7.2.2

Places Bank AI Trip Planner, Day-Wise Trip Map filtering, and official OpenStreetMap tile server migration.

Version 7.0.0 - 7.1.0

Interactive UI spotlight tour, getting started checklist widget, and cryptographic anonymous telemetry client.

Version 1.0.0 - 1.2.13

Initial release of TravelBuff with offline-first Dexie.js storage, dual maps, AI travel importer, and multi-currency budgeting.

Insights & Releases

TravelBuff Engineering & Stories

Deep dives into self-hosting, offline-first architecture, trip planning workflows, and product updates.

Why Your Travel Plans Belong on Your Own Server Self-Hosting & Privacy
Aug 16, 2026 • 6 min read

Why Your Travel Plans Belong on Your Own Server (And How to Deploy in 5 Minutes)

Why sensitive itinerary data, reservation vouchers, and GPS logs don't belong on third-party cloud apps, and how to self-host your personal travel organizer with TravelBuff in 5 minutes.

Read Full Article →
TravelBuff v1.2.7 Released Release Notes
Oct 12, 2026 • 4 min read

TravelBuff v1.2.7 Released: Trip Mode, Live Budget Tracking & Immich Albums

Introducing new Trip Mode companion features, budget spend tracking, and enhanced Immich gallery support.

Read Full Article →
Why Offline-First Matters for Travelers Architecture & Tech
Sep 28, 2026 • 5 min read

Why Offline-First Architecture Matters for Modern Travelers

Why relying on cloud apps in remote locations fails, and how Dexie.js keeps your data safe without internet.

Read Full Article →
Self-Hosting August 16, 2026 • 6 min read

Article Title

Subtitle

TB
TravelBuff Team Official TravelBuff Publication
Cover Image
Transparency & Privacy Updated August 2026

TravelBuff Privacy Policy

Our commitment to offline-first data ownership and transparent, anonymous telemetry.

1. The Offline-First Principle

TravelBuff was built from day one as an offline-first, self-hosted personal travel organizer. We believe your travel memories, itinerary plans, and financial details belong solely to you.

  • Local Database Storage: All your trips, destinations, custom notes, itineraries, and expense records are stored directly inside your browser database (Dexie.js / IndexedDB) or your private self-hosted server.
  • No Cloud Account Required: You do not need an account with us to use TravelBuff. We never synchronize your trip content to third-party central clouds.
  • Private Integrations: When you connect Immich or OwnTracks, your data flows directly between your private servers without passing through our infrastructure.

2. Anonymous Usage Statistics (Telemetry)

To help us prioritize device compatibility, bug fixes, and feature improvements, TravelBuff instances send anonymous, high-level system telemetry to our server (telemetry.travelbuff.app).

What We Collect:

  • Instance Identifier: A randomly generated UUIDv4 assigned to your local installation to measure active retention.
  • Environment & Compatibility: Application version, Node.js runtime, host operating system (Linux, macOS, Windows), architecture (x64, arm64), and whether running inside Docker.
  • Feature Adoption Flags (Booleans): Whether integrations are enabled (e.g. has_immich: true/false, has_owntracks, has_google_maps).
  • AI Provider Selection: Which AI provider is selected (e.g. Ollama, OpenAI, Gemini, Anthropic, or none).
  • Binned Scale Buckets: Non-identifying volume categories (e.g. Trip Count: 1-5, Location Count: 50-200) to evaluate database query performance without knowing exact counts.
  • Coarse Location (Country Code): Extracted at the network edge from Cloudflare GeoIP (e.g. US, DE, IN).

What We NEVER Collect:

  • ❌ No PII: No names, email addresses, usernames, or contact information.
  • ❌ No IP Storage: Raw IP addresses are immediately discarded at the edge and never stored in the database.
  • ❌ No Travel Content: No trip names, destination coordinates, notes, itinerary schedules, or photos.
  • ❌ No Financial Data: No budget totals, expense items, currencies, or receipt images.
  • ❌ No Secrets: No API keys, passwords, or private server URLs.

3. How to Opt-Out Anytime

You have full control over whether your instance sends anonymous statistics.

  • In App Settings: Go to Settings > Privacy & Telemetry and toggle off "Send Anonymous System Statistics". You can also click "View Current Payload" to inspect the exact JSON sent before transmitting.
  • Via Environment Variable: Add DISABLE_TELEMETRY=true to your .env file or Docker environment.

4. Open Source Transparency

Because TravelBuff is open-source, the telemetry collection client and database schemas are completely public and auditable by anyone in our repository.

Contact Us

Have questions, feedback, or need help? Send us a message below, or email support@travelbuff.app for support.

Link copied to clipboard!