Travel Module
Relevant source files
The following files were used as context for generating this wiki page:
The Travel module manages household trips, itineraries, and associated documentation. It functions as an opt-in module within the Hearth ecosystem, allowing users to track travel dates, destinations, bookings, and flight details. The module supports automatic data enrichment, including real-time flight status updates and distance calculations.
Sources: PRODUCT.md:16, CLAUDE.md:83, src/app/(app)/travel/page.tsx:21
System Architecture
The module utilizes a hierarchical data structure where a Trip acts as a container for multiple Trip Segments. Segments represent specific itinerary items such as flights, lodging, or activities. Data mutations are processed through Server Actions, which validate inputs against Zod schemas before executing Prisma commands.
Sources: src/lib/actions/trips.ts:13-26, tests/unit/trip-commands.test.ts:25-30
Entity Relationships
The following diagram illustrates the relationship between Trips, Trip Segments, and Documents within the Travel module.
The Travel module maintains a strict parent-child relationship between Trips and Segments.
Sources: ios-shell/www/app.js:192-228, tests/unit/trip-commands.test.ts:140-150
Core Data Models
The system categorizes itinerary items using the TripSegment type. This enables domain-specific logic, particularly for flights.
Trip Segment Types
| Type | Description | Relevant Fields |
|---|---|---|
| FLIGHT | Air travel entries | flightNumber, departureIata, arrivalIata, flightStatus |
| LODGING | Hotel or accommodation bookings | provider, location, confirmationCode |
| ACTIVITY | Tours, events, or visits | title, location, cost |
| TRAIN | Rail travel segments | provider, departureTime, arrivalTime |
Sources: src/components/TripSegmentForm.tsx:120-140, ios-shell/www/app.js:207-220
Flight Data Integration
When you add a flight segment, the system can automatically enrich the record with external data.
Flight Status and Tracking
For segments typed as FLIGHT, the module tracks real-time status including gates, terminals, and delays.
- Auto-Refresh: The system triggers a status refresh if a flight is within the tracking window and the user has write permissions.
- Distance Calculation: The system computes distance in kilometers between the
departureIataandarrivalIatacodes using background lookups. - Manual Refresh: Users can manually trigger a refresh via the
refreshFlightStatusActionserver action.
Sources: src/app/(app)/travel/[id]/page.tsx:50-70, src/lib/actions/trips.ts:182-198
Flight status updates flow from external APIs to the local database, triggering a UI revalidation.
Sources: src/lib/actions/trips.ts:182-198, src/app/(app)/travel/[id]/page.tsx:180-220
Document AI and Extraction
The module includes a document extraction pipeline to reduce manual data entry. When you upload travel documents (like flight confirmations), the system attempts to auto-fill the segment form.
Extraction Pipeline
- Text Extraction: Extracts raw text from PDFs or images using local tools (OCR/pdftotext).
- Heuristic/Regex Matching: Scans extracted text for patterns matching flight numbers, dates, and confirmation codes.
- Cloud AI (Optional): If you provide an API key, the system sends document bytes to a cloud provider for advanced field extraction.
Sources: src/app/api/travel/extract/route.ts:40-70, PRODUCT.md:32-38
Mobile Shell Implementation
The Travel module is implemented in the mobile shell (ios-shell) to support Standalone Mode. In this mode, data is stored in an encrypted SQLite database on the device rather than a remote server.
Standalone Capabilities
- Local Storage: Uses the
tripsandtrip_segmentstables in the device-local SQLite database. - Module Toggling: You can enable or disable the Travel module via
Preferencesin the mobile settings, which controls the visibility of travel screens. - Offline Support: Allows creating and editing trips while offline; changes sync to the server when you switch to Connected Mode.
Sources: ios-shell/www/app.js:65-75, ios-shell/www/app.js:192-228, ios-shell/www/app.js:460-475
Security and Permissions
The Travel module enforces household-wide visibility but gates write access based on user roles.
- Shared Visibility: Every member of the household sees and can access all trips.
- Role Gating:
ADMINandMEMBERroles can create, edit, and delete trips.READONLYroles are blocked from all write actions (enforced viarequireUser()in server actions).
- Module Enablement: If the Travel module is disabled in the household settings, all associated pages and actions return a
ModuleDisabledErroror 404/403 response.
Sources: src/lib/actions/trips.ts:38-45, CLAUDE.md:144-155, tests/unit/trip-commands.test.ts:125-135
AI Assistant Integration
The Travel module exposes read-only tools to the AI Assistant. This allows users to query their travel data using natural language.
| Tool Name | Description | Source |
|---|---|---|
list_trips | Returns all trips, optionally filtering for upcoming trips. | src/lib/chat/tools.ts |
search_contracts | Can be used to find travel-related insurance or booking contracts. | src/lib/chat/tools.ts |
Sources: src/lib/chat/tools.ts:168-180
The Travel module serves as a central hub for itinerary management, leveraging both local processing and external integrations to provide a detailed view of household travel activities.