External Navigation Handoff
Relevant source files
The following files were used as context for generating this wiki page:
The External Navigation Handoff system is a core architectural feature of P4N Map that delegates real-time, turn-by-turn navigation to specialized third-party mobile applications. While the P4N Map application handles complex multi-stop planning, corridor geometry, and spot discovery, it deliberately offloads the driving experience to apps like Google Maps or TomTom GO.
This handoff ensures that the user benefits from professional navigation features—such as live traffic updates and vehicle-specific routing (e.g., van height and length restrictions)—without the P4N Map application needing to implement a custom turn-by-turn engine.
Sources: README.md:14-16, src/app/settings/page.tsx:162-164
Architecture and Integration
The handoff logic is centralized in a utility library and triggered by various UI components or voice commands. The application maintains a persistent user preference for the target navigation app within the global state.
Supported Navigation Providers
The system currently supports two primary providers, defined by the NavApp type:
| Provider | Description | Technical Implementation |
|---|---|---|
| Google Maps | General purpose navigation. | Standard https://www.google.com/maps/dir/ URL. |
| TomTom | Professional navigation that respects van dimensions. | tomtomgo:// deep link protocol. |
Sources: src/lib/nav.ts:1-10, src/app/settings/page.tsx:150-161
Data Flow for Handoff
The following diagram illustrates how a user action on the map or via voice leads to the external application launch:
The handoff process translates internal coordinate data and van profiles into a format compatible with external URI schemes.
Sources: src/components/Planner.tsx:556-560, src/app/api/assistant/route.ts:124-128
Implementation Details
The navUrl Logic
The primary engine for handoff is the navUrl function. It constructs the appropriate URL or deep link based on the selected provider and the target destination's latitude and longitude.
For TomTom GO, the system includes van profile data (height and length) in the deep link, allowing the external app to calculate routes that avoid low bridges or tight turns. Google Maps integration uses a standard web URL that defaults to the user's current location as the starting point.
// Example logic structure from src/lib/nav.ts
export function navUrl(app: NavApp, dest: { lat: number, lng: number }, van: VanProfile) {
if (app === "tomtom") {
return `tomtomgo://x-callback-url/navigate?destination=${dest.lat},${dest.lng}`;
}
return `https://www.google.com/maps/dir/?api=1&destination=${dest.lat},${dest.lng}`;
}
Sources: src/lib/nav.ts:1-25 (Approximate logic based on file context)
Van Profile Configuration
Users can configure their vehicle's physical dimensions in the Settings page. This data is stored in the AppState and passed to the navigation utility during the handoff.
- Height (m): Used to avoid low obstacles.
- Length (m): Used for maneuverability calculations in TomTom.
Sources: src/app/settings/page.tsx:167-202
Multi-Stop Trip Handoff
In "Plan day" mode, the application manages an ordered list of stops (A → B → C). The handoff system manages these sequentially via the navStopIndex. Users can navigate to specific legs of the trip using the "Next leg" interface.
- Go To Stop: Launches navigation to a specific index in the trip.
- Advance Nav: Marks the current stop as arrived and prepares the next leg for handoff.
Sources: src/components/Planner.tsx:566-586, src/components/Planner.tsx:1030-1065
Voice-Activated Handoff
The Assistant module allows for hands-free navigation initiation. When a user says "Navigate to number one" or "Drive to the nearest fuel station," the askAssistant API identifies the navigate action.
- The Assistant identifies the coordinates of the chosen spot from the current shortlist.
- It returns a
navigatedecision to the client. - The client executes the
openNavfunction automatically.
Summary of Integration Points
| Component | Responsibility | Source |
|---|---|---|
SettingsPage | Defines the global navApp preference and VanProfile. | src/app/settings/page.tsx |
DetailPanel | Provides a direct "Navigation" button for a selected spot. | src/components/DetailPanel.tsx |
StopEditor | Handles leg-by-leg navigation for multi-stop routes. | src/components/Planner.tsx |
Assistant API | Processes natural language to trigger navigation actions. | src/app/api/assistant/route.ts |
nav.ts | Utility for generating provider-specific URIs. | src/lib/nav.ts |
The external navigation handoff system represents a modular approach to travel technology, leveraging the specialized strengths of existing navigation giants while providing a unique discovery and planning interface.
Sources: src/components/Planner.tsx:556-560, src/components/DetailPanel.tsx:135-137