# muhammad-wasay/ev-map architecture

> Architecture diagram of the GitHub repository muhammad-wasay/ev-map, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/muhammad-wasay/ev-map
- Repository: https://github.com/muhammad-wasay/ev-map

## Overview

VoltPath is an EV trip-planning decision-support application. A driver configures a trip in the React dashboard; the app uses the FastAPI planner when available, while its client mock can provide a fallback. The backend loads network and EV data, prepares the road graph, finds a route, projects it into charging stages, and optimizes stops and energy allocation before returning a trip plan. The product also exposes network, vehicle, saved-trip analytics, incremental route repair, and sensitivity analysis. The graph follows README-documented flows where source excerpts do not expose the full wiring.

Main entry points: [`src/pipeline.py`](https://github.com/muhammad-wasay/ev-map/blob/main/src/pipeline.py) (Trip pipeline), [`frontend/src/App.jsx`](https://github.com/muhammad-wasay/ev-map/blob/main/frontend/src/App.jsx) (Dashboard app), [`src/api_client.py`](https://github.com/muhammad-wasay/ev-map/blob/main/src/api_client.py) (Network API adapter), [`api/server.py`](https://github.com/muhammad-wasay/ev-map/blob/main/api/server.py) (REST API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web application"]
  node_app["Dashboard app<br/>[App.jsx]"]
  node_station_view["Charging directory"]
  node_trip_view["Saved trip analytics"]
  node_vehicle_view["Vehicle telemetry"]
  node_pixel_card["Pixel card UI<br/>[PixelCard.jsx]"]
  node_client_mock["Client mock planner<br/>[mockFallback.js]"]
end

subgraph group_service["Planning service"]
  node_api["REST API<br/>[server.py]"]
  node_cli["CLI runner<br/>[main.py]"]
  node_map_dashboard["Route map dashboard<br/>[dashboard.py]"]
end

subgraph group_planning["Trip planning engine"]
  node_pipeline["Trip pipeline<br/>[pipeline.py]"]
  node_domain["Trip domain models<br/>[models.py]"]
  node_preprocessor["Graph preparation<br/>[preprocessor.py]"]
  node_astar["A* route search<br/>[astar_router.py]"]
  node_corridor["Charging corridor<br/>[corridor_bridge.py]"]
  node_optimizer["Charging optimizer<br/>[dp_charger.py]"]
end

subgraph group_data["Network data"]
  node_api_client["Network API adapter<br/>[api_client.py]"]
  node_network_data["Curated network data"]
end

node_driver(("EV driver"))
node_open_charge_map["OpenChargeMap"]
node_osrm["OSRM routing"]

node_driver -->|"plans trip"| node_app
node_app -->|"requests plans"| node_api
node_app -->|"falls back to"| node_client_mock
node_app -->|"renders"| node_station_view
node_app -->|"renders"| node_trip_view
node_app -->|"renders"| node_vehicle_view
node_station_view -->|"uses"| node_pixel_card
node_vehicle_view -->|"uses"| node_pixel_card
node_api -->|"runs planner"| node_pipeline
node_api -->|"loads network"| node_api_client
node_api -->|"prepares graph"| node_preprocessor
node_api -->|"repairs routes"| node_astar
node_pipeline -->|"loads network"| node_api_client
node_pipeline -->|"prepares graph"| node_preprocessor
node_pipeline -->|"finds route"| node_astar
node_pipeline -->|"projects route"| node_corridor
node_pipeline -->|"optimizes charging"| node_optimizer
node_api_client -->|"loads fallback"| node_network_data
node_api_client -.->|"queries chargers"| node_open_charge_map
node_api_client -.->|"queries routes"| node_osrm
node_api_client -->|"builds models"| node_domain
node_preprocessor -->|"uses models"| node_domain
node_astar -->|"uses models"| node_domain
node_corridor -->|"uses models"| node_domain
node_optimizer -->|"uses models"| node_domain
node_cli -->|"runs planner"| node_pipeline
node_cli -->|"uses dashboard"| node_map_dashboard

click node_app "https://github.com/muhammad-wasay/ev-map/blob/main/frontend/src/App.jsx"
click node_station_view "https://github.com/muhammad-wasay/ev-map/blob/main/frontend/src/ChargingNetworkView.jsx"
click node_trip_view "https://github.com/muhammad-wasay/ev-map/blob/main/frontend/src/SavedTripsAnalyticsView.jsx"
click node_vehicle_view "https://github.com/muhammad-wasay/ev-map/blob/main/frontend/src/VehicleSpecsTelemetryView.jsx"
click node_pixel_card "https://github.com/muhammad-wasay/ev-map/blob/main/frontend/src/components/PixelCard.jsx"
click node_client_mock "https://github.com/muhammad-wasay/ev-map/blob/main/frontend/src/mockFallback.js"
click node_api "https://github.com/muhammad-wasay/ev-map/blob/main/api/server.py"
click node_pipeline "https://github.com/muhammad-wasay/ev-map/blob/main/src/pipeline.py"
click node_api_client "https://github.com/muhammad-wasay/ev-map/blob/main/src/api_client.py"
click node_network_data "https://github.com/muhammad-wasay/ev-map/blob/main/data/highway_network.json"
click node_domain "https://github.com/muhammad-wasay/ev-map/blob/main/src/models.py"
click node_preprocessor "https://github.com/muhammad-wasay/ev-map/blob/main/src/preprocessor.py"
click node_astar "https://github.com/muhammad-wasay/ev-map/blob/main/src/astar_router.py"
click node_corridor "https://github.com/muhammad-wasay/ev-map/blob/main/src/corridor_bridge.py"
click node_optimizer "https://github.com/muhammad-wasay/ev-map/blob/main/src/dp_charger.py"
click node_cli "https://github.com/muhammad-wasay/ev-map/blob/main/main.py"
click node_map_dashboard "https://github.com/muhammad-wasay/ev-map/blob/main/ui/dashboard.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_station_view,node_trip_view,node_vehicle_view,node_pixel_card,node_client_mock toneBlue
class node_api,node_cli,node_map_dashboard toneAmber
class node_pipeline,node_domain,node_preprocessor,node_astar,node_corridor,node_optimizer toneMint
class node_api_client,node_network_data toneRose
class node_driver,node_open_charge_map,node_osrm toneIndigo
```

## Components

### Web application

- [Dashboard app](https://github.com/muhammad-wasay/ev-map/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Charging directory](https://github.com/muhammad-wasay/ev-map/blob/main/frontend/src/ChargingNetworkView.jsx): `frontend/src/ChargingNetworkView.jsx`
- [Saved trip analytics](https://github.com/muhammad-wasay/ev-map/blob/main/frontend/src/SavedTripsAnalyticsView.jsx): `frontend/src/SavedTripsAnalyticsView.jsx`
- [Vehicle telemetry](https://github.com/muhammad-wasay/ev-map/blob/main/frontend/src/VehicleSpecsTelemetryView.jsx): `frontend/src/VehicleSpecsTelemetryView.jsx`
- [Pixel card UI](https://github.com/muhammad-wasay/ev-map/blob/main/frontend/src/components/PixelCard.jsx): `frontend/src/components/PixelCard.jsx`
- [Client mock planner](https://github.com/muhammad-wasay/ev-map/blob/main/frontend/src/mockFallback.js): `frontend/src/mockFallback.js`

### Planning service

- [REST API](https://github.com/muhammad-wasay/ev-map/blob/main/api/server.py): `api/server.py`
- [CLI runner](https://github.com/muhammad-wasay/ev-map/blob/main/main.py): `main.py`
- [Route map dashboard](https://github.com/muhammad-wasay/ev-map/blob/main/ui/dashboard.py): `ui/dashboard.py`

### Trip planning engine

- [Trip pipeline](https://github.com/muhammad-wasay/ev-map/blob/main/src/pipeline.py): `src/pipeline.py`
- [Trip domain models](https://github.com/muhammad-wasay/ev-map/blob/main/src/models.py): `src/models.py`
- [Graph preparation](https://github.com/muhammad-wasay/ev-map/blob/main/src/preprocessor.py): `src/preprocessor.py`
- [A* route search](https://github.com/muhammad-wasay/ev-map/blob/main/src/astar_router.py): `src/astar_router.py`
- [Charging corridor](https://github.com/muhammad-wasay/ev-map/blob/main/src/corridor_bridge.py): `src/corridor_bridge.py`
- [Charging optimizer](https://github.com/muhammad-wasay/ev-map/blob/main/src/dp_charger.py): `src/dp_charger.py`

### Network data

- [Network API adapter](https://github.com/muhammad-wasay/ev-map/blob/main/src/api_client.py): `src/api_client.py`
- [Curated network data](https://github.com/muhammad-wasay/ev-map/blob/main/data/highway_network.json): `data/highway_network.json`

### Other components

- **EV driver**
- **OpenChargeMap**
- **OSRM routing**

## Connections

- EV driver → Dashboard app: plans trip (evidence: `README.md`)
- Dashboard app → REST API: requests plans (evidence: `README.md`)
- Dashboard app → Client mock planner: falls back to (evidence: `frontend/src/App.jsx`)
- Dashboard app → Charging directory: renders (evidence: `frontend/src/App.jsx`)
- Dashboard app → Saved trip analytics: renders (evidence: `frontend/src/App.jsx`)
- Dashboard app → Vehicle telemetry: renders (evidence: `frontend/src/App.jsx`)
- Charging directory → Pixel card UI: uses (evidence: `frontend/src/ChargingNetworkView.jsx`)
- Vehicle telemetry → Pixel card UI: uses (evidence: `frontend/src/VehicleSpecsTelemetryView.jsx`)
- REST API → Trip pipeline: runs planner (evidence: `README.md`)
- REST API → Network API adapter: loads network (evidence: `api/server.py`)
- REST API → Graph preparation: prepares graph (evidence: `api/server.py`)
- REST API → A* route search: repairs routes (evidence: `api/server.py`)
- Trip pipeline → Network API adapter: loads network (evidence: `src/pipeline.py`)
- Trip pipeline → Graph preparation: prepares graph (evidence: `README.md`)
- Trip pipeline → A* route search: finds route (evidence: `README.md`)
- Trip pipeline → Charging corridor: projects route (evidence: `README.md`)
- Trip pipeline → Charging optimizer: optimizes charging (evidence: `README.md`)
- Network API adapter → Curated network data: loads fallback (evidence: `README.md`)
- Network API adapter → OpenChargeMap: queries chargers (evidence: `src/api_client.py`)
- Network API adapter → OSRM routing: queries routes (evidence: `src/api_client.py`)
- Network API adapter → Trip domain models: builds models (evidence: `src/api_client.py`)
- Graph preparation → Trip domain models: uses models (evidence: `src/preprocessor.py`)
- A* route search → Trip domain models: uses models (evidence: `src/astar_router.py`)
- Charging corridor → Trip domain models: uses models (evidence: `src/corridor_bridge.py`)
- Charging optimizer → Trip domain models: uses models (evidence: `src/dp_charger.py`)
- CLI runner → Trip pipeline: runs planner (evidence: `main.py`)
- CLI runner → Route map dashboard: uses dashboard (evidence: `main.py`)