Application Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The P4N Map application is a personal van trip planner designed to extend the capabilities of the Park4Night platform. It provides a specialized UI for planning multi-stop "A → B → C" routes, corridor-based spot searching, and hands-free voice assistance during travel. The architecture is built as a single-user web application that proxies requests to Park4Night private endpoints using a server-side Node.js environment.
Sources: README.md:1-12, src/app/layout.tsx
Core Technology Stack
The application utilizes a modern JavaScript/TypeScript stack centered around the Next.js framework.
| Component | Technology |
|---|---|
| Framework | Next.js 16 (App Router), React 19, TypeScript |
| Runtime | Node.js >= 22 |
| Mapping | MapLibre GL, OpenStreetMap (Raster tiles) |
| External APIs | OSRM (Routing), Nominatim (Geocoding), Overpass (Amenities) |
| Intelligence | Google Gemini (Voice assistant tool-choice) |
| Styling | Tailwind CSS 4.0 |
Sources: package.json:13-33, README.md:21-28
System Architecture & Data Flow
The application follows a client-server model where the Next.js server acts as a secure proxy and data processor. This prevents exposing sensitive session cookies (PHPSESSID) to the client and allows for complex spatial operations and caching that would be inefficient in the browser.
High-Level Component Interaction
This diagram illustrates how the User Interface interacts with the internal API and external services.
Sources: README.md:21-34, src/lib/client.ts, src/lib/cache.ts
Planning Process Flow
The planning logic follows a specific sequence to find and rank parking spots along a route.
- Routing: Stops are sent to OSRM to generate a planning polyline.
- Sampling: The polyline is sampled approximately every 20 km.
- Discovery: The system calls the Park4Night
/places/aroundendpoint for each sample point. - Filtering: Results are deduped and rejected if they exceed the
maxKmFromRoadcorridor setting. - Ranking: Spots are scored based on detour distance, rating, and proximity to amenities like dog parks.
Core Data Structures
The application relies on several key TypeScript interfaces to manage state and spatial data.
Place and Route Types
The ScoredPlace extends the standard Park4Night place data with calculated spatial metrics relative to the current trip.
export interface ScoredPlace extends P4nPlace {
kmFromRoad: number; // Perpendicular distance from route
progressKm: number; // Distance along route from start
dogPark?: { // Optional nearby amenity
name: string;
kmAway: number;
} | null;
score: number; // Composite ranking score
}
Sources: src/lib/types.ts:74-84
Planning Configuration
Configuration for the "Corridor Search" algorithm is managed via CorridorSettings and Specs.
| Field | Type | Description |
|---|---|---|
maxKmFromRoad | number | The perpendicular distance cutoff for spots. |
minRating | number | Minimum user rating (0-5) to include a spot. |
nearDogPark | boolean | If true, ranks parkings with nearby dog parks higher. |
requiredServices | string[] | List of service codes (e.g., 'point_eau', 'electricite') to highlight. |
Sources: src/lib/types.ts:108-132, src/app/settings/page.tsx:18-28
System Modules
1. Planner Engine (src/lib/planner.ts)
The deterministic core of the app. It implements the scoring algorithm where a lower score is better. The score is calculated as:
Base Detour (km) - Rating Bonus - Dog Park Bonus - Service Match Bonus.
- Rating Bonus: Up to 1.5 km-equivalent for a 5-star rating.
- Service Bonus: -0.4 km-equivalent per matched service.
Sources: src/lib/planner.ts:103-125
2. Durable Cache (src/lib/cache.ts)
To respect external API limits and improve performance, the server maintains a JSON-based file cache for Park4Night data.
- Location: Configurable via
P4N_CACHE_DIR(defaults to.p4n-cache). - Persistence: Uses a debounced write (800ms) to sync memory state to disk.
- Capacity: Limited to 20,000 entries; drops oldest 25% when full.
Sources: src/lib/cache.ts:22-50, src/lib/cache.ts:114-128
3. Navigation Management (src/components/Planner.tsx)
The application manages trip progress via a navStopIndex. While turn-by-turn navigation is handled by external apps (TomTom or Google Maps), the Planner tracks the current "leg" of the journey.
- TomTom Integration: Used for van-specific routing (height/length constraints).
- Navigation Flow: User selects a destination -> App generates a deep-link URL -> External app opens.
Sources: src/components/Planner.tsx:494-515, README.md:14-18
Conclusion
The P4N Map architecture emphasizes server-side processing of spatial data and proxying of private third-party APIs. By combining OSRM routing with Park4Night's spot database and OSM's amenity data, it creates a specialized planning corridor. The system's use of a durable JSON cache and structured scoring logic ensures that trip planning is both performant and tailored to the specific needs of van travelers.
Sources: src/lib/planner.ts, src/lib/cache.ts, README.md