Technology Stack
Relevant source files
The following files were used as context for generating this wiki page:
P4N Map is a specialized web application designed for planning van trips by wrapping Park4Night+ account data in a custom interface. The project is built as a private, single-user experiment that focuses on multi-stop route planning and hands-free navigation assistance.
The architecture follows a modern Full-stack TypeScript approach, leveraging Next.js 16 and React 19. It integrates several external services including OpenStreetMap (OSM) for mapping and amenities, OSRM for routing, and Google Gemini for voice-activated planning assistance.
Sources: README.md:1-25, package.json:14-23
Core Framework & Runtime
The application is built on the Next.js 16 framework using the App Router architecture. It requires Node.js 22 or higher for the server-side environment.
| Component | Technology | Version |
|---|---|---|
| Framework | Next.js (App Router) | ^16.0.0 |
| Library | React | ^19.0.0 |
| Language | TypeScript | ^5.7.0 |
| Runtime | Node.js | >=22 |
| Styling | Tailwind CSS | ^4.1.0 |
Sources: package.json:14-30, README.md:27-33
Frontend Architecture
The frontend is a React-based Single Page Application (SPA) designed primarily for desktop use with a secondary mobile-optimized voice interface.
Mapping and Geospatial Visualization
The map interface is powered by MapLibre GL, utilizing OpenStreetMap raster tiles. Unlike traditional DOM-based markers, the application uses GPU-rendered pins via GeoJSON sources for high-performance hit-testing and alignment.
This diagram illustrates how React state is synchronized with MapLibre's internal GeoJSON sources for efficient rendering.
User Interface Components
- Planner Component: Manages the main application state, including trip modes (
favourites,plan,onroad). - Detail Panel: Provides persistent information about selected spots, including reviews and service availability.
- Voice Assistant: A mobile-focused feature allowing hands-free interaction through speech-to-text and text-to-speech.
Sources: src/components/Planner.tsx:60-100, src/components/DetailPanel.tsx:1-40
Backend & API Services
The backend consists of Next.js Route Handlers (API routes) that serve as a proxy for the Park4Night private endpoints and integrate third-party data providers.
API Integration Layers
The system orchestrates data from multiple providers to build the trip corridor:
- Park4Night API: Accessed via the user's
PHPSESSID. The server-side proxy handles place discovery and bookmark management. - OSRM (Open Source Routing Machine): Used to generate the planning polyline for the trip geometry.
- Nominatim & Overpass: Used for geocoding and querying OSM amenities (fuel, supermarkets, dog parks) along the route.
- Google Gemini AI: Utilized exclusively for tool-choice in the voice assistant module; the AI identifies user intent and maps it to deterministic search actions.
Sequence of data flow during the trip planning process.
Sources: README.md:31-35, src/app/api/plan/route.ts:25-50, src/app/api/assistant/route.ts:40-80
Data Management & Persistence
Server-Side Caching
To optimize performance and reduce reliance on upstream APIs, the project implements a durable, refresh-only key/value cache.
- In-memory store: Mirrored to a JSON file (
.p4n-cache/p4n-cache.json). - Persistence: Designed to survive process restarts and redeploys by using a mounted volume (specifically optimized for Fly.io).
- Graceful Degradation: Falls back to memory-only if the filesystem is unavailable.
Sources: src/lib/cache.ts:1-25
Client-Side State
Application state, including van profiles and saved routes, is managed locally and persisted via browser storage.
- AppState: Contains user settings, van dimensions (for TomTom routing), and current corridor settings.
- SavedPlans: Snapshots of routes including polyline and scores, allowing reloads without new API requests.
Sources: src/lib/types.ts:130-160, src/components/Planner.tsx:120-150
External Navigation Hand-off
The application does not perform turn-by-turn navigation. Instead, it generates deep links to external navigation apps.
- TomTom GO: Used for professional van routing (respecting height and length constraints).
- Google Maps: Used as a general-purpose navigation fallback.
Sources: src/app/settings/page.tsx:150-170, README.md:20-25
Infrastructure & Deployment
The application is configured for deployment on Fly.io using a Dockerfile.
- Environment Variables: Used for sensitive data like
PHPSESSIDandGEMINI_API_KEY. - Security: HTTP Basic Authentication is implemented via
APP_GATE_USERandAPP_GATE_SECRETto protect the private instance.
Sources: README.md:67-80
Summary
The P4N Map technology stack is a specialized integration of geospatial tools and Next.js. By combining high-performance MapLibre rendering on the frontend with a cached server-side proxy for Park4Night and OSM data, the system provides a specialized planning environment for van travelers that exceeds the capabilities of standard mobile applications.