# TravelBuff — Complete System & Feature Documentation

> **Offline-First Personal Travel Organizer & Itinerary Planner**
> Version: 1.2.9 | [Official Website](http://localhost:3000) | [Docker Hub](https://hub.docker.com/r/abhishekkharvadi/travelbuff)

---

## Table of Contents
1. [Overview & Features](#1-overview--features)
   - [The TravelBuff Philosophy](#the-travelbuff-philosophy)
   - [Core Features](#core-features)
2. [Setting Up TravelBuff](#2-setting-up-travelbuff)
   - [Prerequisites Check](#prerequisites-check-all-operating-systems)
   - [Step 1: Open Project Folder](#step-1-open-the-project-folder)
   - [Step 2: Install Packages](#step-2-install-required-packages)
   - [Step 3: Environment Settings (.env)](#step-3-create--configure-environment-settings-env)
   - [Step 4: Launch TravelBuff](#step-4-launch-travelbuff)
   - [Step 5: Open in Web Browser](#step-5-open-travelbuff-in-your-web-browser)
   - [Managing, Stopping & Deleting](#managing-stopping--deleting-travelbuff)
3. [Setting Up Locations & Folders](#3-setting-up-locations--folders)
   - [Adding Locations & Folders](#adding-locations--folders)
   - [Places of Visit & Categorization](#places-of-visit--categorization)
   - [Filtering & Sorting Locations](#filtering--sorting-locations)
   - [Interactive Maps & Image Sources](#interactive-maps--image-sources)
   - [Visit History & Immich Integration](#visit-history--immich-integration)
4. [Collections](#4-collections)
   - [System Collections & Custom Collections](#system-collections--custom-collections)
   - [Classification Methods: Manual vs. Auto-Group](#classification-methods-manual-vs-auto-group)
   - [Step-by-Step Practical Examples](#step-by-step-practical-examples)
5. [Importing Guides & Using AI](#5-importing-guides--using-ai)
   - [How to Import Content](#how-to-import-content-step-by-step-examples)
   - [Accessing & Resuming Saved Guides](#accessing--resuming-saved-guides)
   - [The 3 Review Workspace Tabs](#the-3-review-workspace-tabs--their-importance)
   - [Action Toolbar & AI Buttons Guide](#action-toolbar--ai-buttons-guide)
   - [Exporting to a Trip Itinerary](#exporting-to-a-trip-itinerary)
6. [Creating Itinerary Plans & Travelers](#6-creating-itinerary-plans--travelers)
   - [Trip Planner Overview](#trip-planner-overview)
   - [Planning a New Trip Setup Wizard](#planning-a-new-trip-setup-wizard)
   - [Selecting Locations or Collections](#selecting-locations-or-collections-for-your-trip)
   - [Domestic vs. International Trips](#domestic-vs-international-trips)
   - [The 3-Column Planning Workspace](#the-3-column-planning-workspace)
   - [Workspace Sub-Tabs](#workspace-sub-tabs)
   - [Special Handling: Home Addresses & Hotel Anchors](#special-handling-home-addresses--hotel-anchors)
7. [Expense Tracking & Home Addresses](#7-expense-tracking--home-addresses)
   - [Planned vs. Actual Expenses](#planned-vs-actual-expenses)
   - [Recording Expenses & Receipt Attachments](#recording-expenses--receipt-attachments)
   - [Multi-Currency Budgets & Custom Exchange Rates](#multi-currency-budgets--custom-exchange-rates)
   - [Expense Analytics & Reports](#expense-analytics--reports)
   - [Saved Home Addresses](#saved-home-addresses)
8. [Trip Mode (On-the-Road Companion)](#8-trip-mode-on-the-road-companion)
   - [Why Trip Mode is Essential](#why-trip-mode-is-essential-while-traveling)
   - [Key Features of Trip Mode](#key-features-of-trip-mode)
9. [Settings & Administration](#9-settings--administration)
   - [Immich Photo Server Integration](#immich-photo-server-integration)
   - [AI Assistant Configuration](#ai-assistant-configuration)
   - [Google Maps Integration](#google-maps-integration-optional)
   - [General Configurations & Navigation Options](#general-configurations--navigation-options)
   - [OwnTracks Location Tracking](#owntracks-location-tracking)
   - [Backup & Restore Engine](#backup-restore-engine)
   - [User Management & Administration](#user-management--administration-admin-only)
   - [Saved Home Addresses](#saved-home-addresses-settings)
   - [Custom Categories & Color Tags](#custom-categories--color-tags)
   - [Travel Companions (People)](#travel-companions-people)
10. [Helpful Tips & Shortcuts](#10-helpful-tips--shortcuts)
11. [Mobile & Screen Adaptability](#11-mobile--screen-adaptability)
12. [Release Notes & Version History](#12-release-notes--version-history)

---

## 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 are offline.

![Figure 1.1: TravelBuff Main Dashboard Overview](./public/1.1.png)
*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:

- **Local-First Storage:** All your travel details are saved directly on your device using client-side storage (Dexie.js / IndexedDB).
- **Zero Latency:** Any changes you make show up instantly without waiting for a server connection.
- **Automatic Background Sync:** When you reconnect to the internet, your changes automatically sync with your backup account.
- **Cross-Device Support:** 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 have 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 (Immich) to easily tag travel companions with face photo avatars.
- **GPS Travel Log Import:** Import GPS logs (OwnTracks) 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.

![Figure 1.2: Interactive Map with Step-by-Step Numbered Routes](./public/1.2.png)
*Figure 1.2: Interactive Map with Step-by-Step Numbered Routes*

![Figure 1.3: Visited Status Indicators](./public/1.3.png)
*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](https://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:**
```bash
cd ~/Downloads/TravelBuff
```

**Windows:**
```powershell
cd C:\Users\YourUsername\Downloads\TravelBuff
```

### Step 2: Install Required Packages
Download all the application components by running the install command in your terminal:
```bash
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.

#### 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
```

#### 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)
```bash
npm run dev
```

![Figure 2.1: Launching TravelBuff via npm run dev](./public/2.1.png)
*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:
```bash
# 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:**
```bash
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
```

**Docker Compose (`docker-compose.yml`):**
```yaml
version: 3.8

services:
  travelbuff:
    image: abhishekkharvadi/travelbuff:latest
    container_name: travelbuff
    restart: unless-stopped
    ports:
      - "5000:5000"
    environment:
      - PORT=5000
      - JWT_SECRET=change-this-to-a-secure-random-secret
      - UPLOADS_DIR=/app/data/uploads
    volumes:
      - travelbuff_data:/app/data
      - travelbuff_uploads:/app/data/uploads

volumes:
  travelbuff_data:
    driver: local
  travelbuff_uploads:
    driver: local
```

![Figure 2.3: Deploying via Docker CLI / Container setup](./public/2.3.png)
*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:
- **Desktop Installation (macOS, Linux, Windows):** [http://localhost:3000/](http://localhost:3000/)
- **Docker Installation:** [http://localhost:5000/](http://localhost:5000/)

### Managing, Stopping & Deleting TravelBuff

#### 1. Checking Status & Logs
```bash
# Check active process status
npx pm2 status

# View live application logs
npx pm2 logs travelbuff
```

#### 2. Stopping the Application
```bash
# Desktop (macOS / Linux / Windows)
npx pm2 stop travelbuff

# Docker
docker stop travelbuff
```

#### 3. Complete Uninstall & Deletion
```bash
# 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.

![Figure 3.1: Add Location Drawer with Automated Geocoding](./public/3.1.png)
*Figure 3.1: Add Location Drawer with Automated Geocoding*

![Figure 3.2: Hierarchical Folder View](./public/3.2.png)
*Figure 3.2: Hierarchical Folder View (Countries, States, Cities)*

### 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.

![Figure 3.3: Places of Visit & Spot Category Badges](./public/3.3.png)
*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.

![Figure 3.4: Filter & Sorting Controls](./public/3.4.png)
*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`.

![Figure 3.5: Immich Photo Server Album Linking & Visit Logs](./public/3.5.png)
*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.

![Figure 4.1: Collections Grid](./public/4.1.png)
*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.

![Figure 4.2: Manual Selection Tree Selector](./public/4.2.png)
*Figure 4.2: Manual Selection Tree Selector*

![Figure 4.3: Auto-Group Rule Builder](./public/4.3.png)
*Figure 4.3: Auto-Group Rule Builder*

### 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.

![Figure 4.4: Master Collection Map View](./public/4.4.png)
*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.

![Figure 5.1: Import Content Modal](./public/5.1.png)
*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.

![Figure 5.2: Saved Travel Guides Table](./public/5.2.png)
*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.

![Figure 5.3: Original Guide Tab with Duplicate Headings Detection](./public/5.3.png)
*Figure 5.3: Original Guide Tab with Duplicate Headings Detection*

![Figure 5.4: Review Data Curation Queue & AI Analysis Toolbar](./public/5.4.png)
*Figure 5.4: Review Data Curation Queue & AI Analysis Toolbar*

![Figure 5.5: Places from Guide Tab & 1-Click Itinerary Export](./public/5.5.png)
*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.

![Figure 5.6: Custom AI Prompt Console Drawer](./public/5.6.png)
*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.

![Figure 6.1: Trip Planner Dashboard & Active Trip Mode Badge](./public/6.1.png)
*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).

![Figure 6.2: 2-Step Trip Creation Wizard](./public/6.2.png)
*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.
- **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.

![Figure 6.3: Interactive 3-Column Planning Workspace](./public/6.3.png)
*Figure 6.3: Interactive 3-Column Planning Workspace*

### Workspace Sub-Tabs
Switch between `Itinerary` (stops & maps), `Budget` (spent vs target), and `Notes` (packing lists & documents).

![Figure 6.4: Workspace Sub-Tabs (Itinerary, Budget, Notes)](./public/6.4.png)
*Figure 6.4: Workspace Sub-Tabs (Itinerary, Budget, Notes)*

### Special Handling: Home Addresses & Hotel Anchors
Compute initial driving distance from saved home address and use overnight lodging anchors (hotels, resorts) to return daily routes back to base.

---

## 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.

![Figure 7.1: Planned Budget vs Actual Spent Progress Bar](./public/7.1.png)
*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.

![Figure 7.2: Log Expense Entry & Receipt Attachment Upload](./public/7.2.png)
*Figure 7.2: Log Expense Entry & Receipt Attachment Upload*

### Multi-Currency Budgets & Custom Exchange Rates
Convert foreign currency costs to base currency automatically or input custom conversion overrides from local exchange kiosks.

![Figure 7.3: Custom Foreign Exchange Rates Override Table](./public/7.3.png)
*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.

![Figure 7.4: Category Expense Analytics & Breakdown Charts](./public/7.4.png)
*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.

![Figure 7.5: Saved Home Addresses Setup Table](./public/7.5.png)
*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.

![Figure 8.1: Mobile Trip Mode Single-Screen Schedule View](./public/8.1.png)
*Figure 8.1: Mobile Trip Mode Single-Screen Schedule View*

![Figure 8.2: 100% Offline Mode & Instant Local Storage Status](./public/8.2.png)
*Figure 8.2: 100% Offline Mode & Instant Local Storage Status*

![Figure 8.3: One-Tap Mobile Quick Expense Logger](./public/8.3.png)
*Figure 8.3: One-Tap Mobile Quick Expense Logger*

![Figure 8.4: 2 km Radius Nearby Food Finder & 1-Click Bookmark](./public/8.4.png)
*Figure 8.4: 2 km Radius Nearby Food Finder & 1-Click Bookmark*

![Figure 8.5: Instant Booking Vouchers & PDF Viewer](./public/8.5.png)
*Figure 8.5: Instant Booking Vouchers & PDF Viewer*

---

## 9. Settings & Administration

### Immich Photo Server Integration
Configure self-hosted Immich endpoint URL and API Key with built-in connection tester to sync photo albums and face avatar tags.

![Figure 9.1: Immich Photo Server Configuration & Connection Tester](./public/9.1.png)
*Figure 9.1: Immich Photo Server Configuration & Connection Tester*

### AI Assistant Configuration
Supports OpenAI, Claude, Gemini, Ollama (Self-Hosted), and Local AI models with custom endpoint configurations and model identifiers.

![Figure 9.2: Multi-Model AI Provider Selector & Endpoint Setup](./public/9.2.png)
*Figure 9.2: Multi-Model AI Provider Selector & Endpoint Setup*

### Google Maps Integration (Optional)
Optional Google Maps API key integration for Maps JavaScript, Directions, Distance Matrix, Geocoding, and Places APIs.

![Figure 9.3: Google Maps API Integration Panel](./public/9.3.png)
*Figure 9.3: Google Maps API Integration Panel*

### General Configurations & Navigation Options
Set base home currency (`USD`, `EUR`, `INR`, `GBP`, `JPY`) and default map navigation app (Google Maps vs Apple Maps).

### OwnTracks Location Tracking
Webhook URL endpoint for mobile GPS tracking during trips.

### Backup & Restore Engine
Export single JSON backups containing database records and uploaded media with chunked background restore capabilities.

![Figure 9.4: Database Backup Export & Progress Recovery Modal](./public/9.4.png)
*Figure 9.4: Database Backup Export & Progress Recovery Modal*

### User Management & Administration (Admin Only)
First user receives admin management rights to manage accounts, reset passwords, or wipe user records safely.

![Figure 9.5: Admin User Management Registry & Account Wiping](./public/9.5.png)
*Figure 9.5: Admin User Management Registry & Account Wiping*

### Saved Home Addresses
Manage home starting points with geocoded coordinates.

### Custom Categories & Color Tags
Custom tags with HEX color pickers and spot categories with emoji icons (`📌`, `🍜`, `🏰`).

![Figure 9.6: Custom Categories & HEX Color Tag Selector](./public/9.6.png)
*Figure 9.6: Custom Categories & HEX Color Tag Selector*

### Travel Companions (People)
Manage travel partner profiles linked to Immich face IDs for round avatar display in headers.

---

## 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 Demo: [Automatic Coordinate Smart Parsing Demo](./public/10.1.mov)*

### ⌨️ 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 Demo: [Drag & Drop Itinerary Stop Reordering Demo](./public/10.2.mov)*

### ✈️ 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.

![Figure 11.1: Mobile Smartphone Fixed Bottom Navigation Bar](./public/11.1.png)
*Figure 11.1: Mobile Smartphone Fixed Bottom Navigation Bar*

![Figure 11.2: Mobile Screen Edge Padding & Notch Adaptability](./public/11.2.png)
*Figure 11.2: Mobile Screen Edge Padding & Notch Adaptability*

---

## 12. Release Notes & Version History

### Version 1.2.9 (Current Release)
- Added Docker & Docker Compose setup guide with official repository `abhishekkharvadi/travelbuff:latest` and sample `docker-compose.yml` file.

![Figure 12.1: TravelBuff Version History & Release Badge](./public/12.1.png)
*Figure 12.1: TravelBuff Version History & Release Badge*

### Version 1.2.8
- Comprehensive documentation overhaul with 12 detailed sections, 5 practical collection setup examples, and Trip Mode companion guide.

### Version 1.2.7
- Bulk location selection controls, improved AI category recognition, and normalized spot tags.

### Version 1.2.6
- Automated cover photo lookup with clean fallback imagery for landmarks.

### Version 1.2.0
- Full SPA browser back/forward history navigation and direct URL folder bookmarking support.

### Version 1.1.0
- First-user admin management, account resets, chunked backup & restore engine, and user deletion wiping.

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