RouteMaster Logistics

Operations

Original Idea

Delivery Route Planner A web app dispatcher that optimizes routes and pushes stops to a driver mobile view.

Product Requirements Document (PRD): RouteMaster Logistics

1. Executive Summary

RouteMaster Logistics is a next-generation fleet management and route optimization platform designed to bridge the gap between back-office dispatchers and last-mile drivers. By leveraging high-performance optimization engines and a local-first mobile architecture, the platform reduces fuel costs by up to 20% and eliminates manual sequencing errors. The system provides a real-time, high-density map for dispatchers and a resilient, offline-capable PWA for drivers to ensure seamless delivery execution even in zero-signal environments.

2. Problem Statement

Current delivery operations suffer from:

  • Manual Inefficiency: Dispatchers spend hours manually sequencing stops.
  • High Operational Costs: Poorly planned routes increase fuel consumption and vehicle wear.
  • Information Silos: Drivers lack real-time updates, and dispatchers have no visibility into delivery progress or precise driver location.
  • Connectivity Fragility: Existing mobile tools fail when drivers enter "dead zones," leading to lost proof-of-delivery data.

3. Goals & Success Metrics

  • Route Efficiency: Reduce total fleet mileage by 15% within the first 6 months.
  • Operational Speed: Optimization of 100+ stops must take less than 5 seconds.
  • Data Integrity: 100% successful sync rate for Proof of Delivery (PoD) using background sync protocols.
  • Driver Adoption: Maintain a >90% daily active user rate among assigned drivers.
  • On-Time Delivery: Increase successful first-time delivery rate to 98%.

4. User Personas

4.1 Logistics Dispatcher ("Dispatcher Dan")

  • Context: Works in a central hub, managing 20-50 drivers.
  • Needs: High-speed bulk upload, automated sequencing, and "birds-eye" real-time tracking.
  • Pain Points: Handling sudden route changes and verifying driver locations.

4.2 Delivery Driver ("Driver Dave")

  • Context: Spends 8-10 hours on the road; uses a mobile device (often mid-range).
  • Needs: Clear sequence of stops, one-tap navigation, and easy PoD capture.
  • Pain Points: App crashes in low-signal areas and battery drain from GPS.

4.3 Fleet Operations Manager ("Manager Maria")

  • Context: Reviews weekly performance and fuel costs.
  • Needs: Analytics on driver performance and delivery success rates.

5. User Stories

  • As a Dispatcher, I want to upload a CSV of 500 addresses so that I don't have to enter them manually.
  • As a Dispatcher, I want to see all 50 drivers on one map without lag so that I can monitor the entire fleet at once.
  • As a Driver, I want the app to work offline so that I can capture signatures in basements or rural areas.
  • As a Driver, I want to tap a button to open my preferred navigation app (Google/Waze) so that I can get turn-by-turn directions.
  • As a Manager, I want to verify that a delivery photo was actually taken at the customer's location to prevent fraud.

6. Functional Requirements

6.1 Dispatcher Web Dashboard

  • Bulk Ingestion: Support for CSV/Excel uploads with automated geocoding using worker threads for non-blocking validation.
  • Route Optimization: Implementation of VROOM engine to solve Traveling Salesman (TSP) and Vehicle Routing Problems (VRP) with capacity constraints.
  • High-Density Map: Mapbox GL JS implementation showing 500+ markers using WebGL layers for sub-second panning/zooming.
  • Real-time Telemetry: Live GPS updates from drivers via WebSockets (Socket.io).

6.2 Driver Mobile PWA

  • Local-First Persistence: SQLite via WASM + OPFS to store all route data locally.
  • Status Management: One-tap updates for "Arrived," "Completed," and "Failed."
  • Proof of Delivery:
    • Digital signature capture with high-fidelity pointer events.
    • Photo capture with AVIF compression and C2PA cryptographic provenance.
  • Offline Sync: Background Sync API to auto-upload queued actions when 4G/5G returns.

6.3 Administrative Features

  • User Management: RBAC (Role-Based Access Control) for Dispatchers vs. Drivers.
  • Vehicle Profiles: Management of load capacity and fuel efficiency parameters.

7. Technical Requirements

7.1 Core Stack (2026 Standards)

  • Frontend: React v19.2.3 (utilizing Server Components and React Compiler).
  • Styling: Tailwind CSS v4.1.18 (Rust-based engine).
  • Backend: Node.js v24.13.0 (LTS "Krypton").
  • Database: PostgreSQL 17 + PostGIS for spatial queries.
  • Mobile Engine: Progressive Web App (PWA) with Service Workers.

7.2 Architecture & Infrastructure

  • Optimization Engine: VROOM via vroom-express for millisecond-latency VRP solving.
  • Worker Threads: Piscina for offloading CSV parsing and address validation.
  • Spatial Indexing: GiST indexes on geography columns; fillfactor set to 80 for HOT (Heap Only Tuple) optimization.
  • Caching: Redis for real-time location "Last Known" state (using UNLOGGED tables in Postgres for secondary persistence).

7.3 Integrations

  • Mapbox: Mapbox GL JS for web; Mapbox Navigation SDK for traffic-aware routing.
  • Twilio: Automated SMS notifications via Twilio Messaging API.
  • Identity: Auth0 for OIDC/JWT-based authentication.

8. Data Model

| Entity | Primary Key | Key Attributes | Relationships | | :--- | :--- | :--- | :--- | | User | UUIDv7 | email, role, phone, password_hash | 1:M with Routes | | Vehicle | UUIDv7 | capacity_kg, fuel_type, license_plate | 1:1 with Driver | | Route | UUIDv7 | driver_id, status (active/done), optimized_poly | 1:M with Stops | | Stop | UUIDv7 | route_id, location (GEOMETRY), seq_num, status | M:1 with Route | | PoD | UUIDv7 | stop_id, sig_blob, photo_url, c2pa_manifest | 1:1 with Stop |

9. API Specification (Key Endpoints)

9.1 Route Optimization

POST /api/v1/routes/optimize

  • Request: { stops: [{lat, lng, id}], vehicle_capacity: 500 }
  • Response: { optimized_sequence: [id_3, id_1, id_2], total_distance: 12.4km }

9.2 Driver Telemetry

POST /api/v1/telemetry/location

  • Request: { driver_id, coords: {lat, lng}, timestamp: "UUIDv7" }
  • Notes: Idempotent endpoint; handles out-of-order pings.

10. UI/UX Requirements

  • Dispatcher Map:
    • Sidebar for "Unassigned Stops."
    • Cluster markers for zoomed-out views; individual vehicle icons for zoomed-in views.
  • Driver Mobile:
    • "Fat-finger" friendly buttons (min 48x48px).
    • Dark mode support for night driving.
    • Persistent "Sync Status" indicator (Green/Orange/Red).

11. Non-Functional Requirements

  • Security: AES-256 Envelope Encryption for customer addresses. TLS 1.3 only.
  • Privacy: GDPR/CCPA 2026 compliant; auto-deletion of precise GPS breadcrumbs after 90 days.
  • Performance: UI must remain responsive (60fps) even with 1,000 active map markers.
  • Accessibility: WCAG 2.1 AA compliance for web dashboard.

12. Out of Scope

  • Inventory management/Warehousing.
  • In-app messaging (will use Slack/WhatsApp integration).
  • Vehicle maintenance scheduling.

13. Risks & Mitigations

| Risk | Mitigation | | :--- | :--- | | API Rate Limiting (Geocoding) | Implement Bottleneck for queuing and local cache for frequent addresses. | | GPS Battery Drain | Use Distance Thresholding (don't ping if moved <10m). | | Data Conflicts | Use UUIDv7 and LWW (Last-Write-Wins) for stop status updates. |

14. Implementation Tasks

Phase 1: Project Setup

  • [ ] Initialize project with React v19.2.3 and Tailwind v4.1.18.
  • [ ] Set up Node.js v24.13.0 environment with TypeScript.
  • [ ] Configure PostGIS database with GiST spatial indexing.
  • [ ] Set up CI/CD pipeline with security scanning for 2026 CVEs.

Phase 2: Route Optimization & Geocoding

  • [ ] Implement bulk CSV uploader with Busboy streaming.
  • [ ] Set up Piscina worker threads for address validation logic.
  • [ ] Integrate VROOM engine via vroom-express for TSP solving.
  • [ ] Build dispatcher stop-assignment UI with react-map-gl.

Phase 3: Mobile PWA & Offline Engine

  • [ ] Configure Service Worker for asset caching.
  • [ ] Implement SQLite (WASM) + OPFS for local-first storage.
  • [ ] Build "Durable Outbox" for status updates and GPS pings.
  • [ ] Integrate Background Sync API for PoD uploads.

Phase 4: Proof of Delivery & Security

  • [ ] Build Signature Capture component using Pointer Events API.
  • [ ] Implement AVIF photo compression in a Web Worker.
  • [ ] Add C2PA cryptographic metadata to delivery photos.
  • [ ] Conduct GDPR/CCPA 2026 compliance audit (Data Minimization check).

Phase 5: Dashboard Optimization

  • [ ] Optimize Mapbox layers for 500+ markers using GeoJSON sources.
  • [ ] Implement WebSockets for real-time fleet movement.
  • [ ] Finalize "Manager Maria" analytics views (D3.js or Tremor).
  • [ ] End-to-end stress test with 1,000 simulated stops.