# aspekts/urban-ev-pathfinding architecture

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

- Interactive diagram: https://gitdiagram.com/aspekts/urban-ev-pathfinding
- Repository: https://github.com/aspekts/urban-ev-pathfinding

## Overview

##### Project Type and Purpose
- This is a standalone Python‐based pathfinding engine with a GUI front end. It reads geospatial and tabular datasets, builds a graph representation of an urban road network, applies search algorithms (A*, BFS, UCS) considering traffic and charging station data, and visualizes results via a Tkinter GUI.
- The primary goal is to optimize EV routes in urban environments by modeling congestion, energy usage, and charging stops.

##### File Structure Analysis
- Top-Level “data/” directory: raw inputs (shapefiles for nodes, links, junctions; CSV for traffic counts and charging stations).
- Root Python modules:
- data_processing.py – loading & cleaning geospatial and CSV data
- graph.py – graph construction logic using NetworkX
- main.py – orchestrates the end-to-end workflow
- test_data.py / dataset_test.py – sample scenarios, unit tests, visualization helpers
- example/ – any sample inputs or usage demos
- Config/dependency file: requirements.txt
- No deployment scripts – runs locally as a Python application.

##### Key Components
A. Data Ingestion Layer
- Data sources:
- Road network shapefiles (RoadNode, RoadLink, MotorwayJunction)
- Traffic CSV (AADF)
- Charging station CSV (NCR)
- Modules: data_processing.py functions
B. Data Processing & Enrichment
- Shapefile parsers → DataFrames/GeoDataFrames
- Traffic join → congestion metrics
- Charging filter → station metadata
C. Graph Construction
- build_graph() in graph.py
- Directed NetworkX graph with nodes (intersections, chargers) and weighted edges (distance + congestion cost)
D. Pathfinding Engine
- a_star_search(), BFS, UCS implementations
- Heuristic module: geodesic distance + charging proximity
E. Calculation Module
- calculate_total_distance_and_time()
F. Visualization & GUI
- test_and_visualize() for plots via matplotlib
- PathfindingApp (Tkinter) for user input and real‐time rendering
G. Orchestration
- main.py: calls ingestion → graph build → search → visualization

##### Relationships & Data Flows
- main.py sits at the top of the flow, invoking each stage in sequence.
- Test modules wrap around the graph and search components for validation.

##### Architectural Patterns & Principles
- Pipeline architecture: distinct phases for ingestion, transformation, analysis, visualization.
- Single Responsibility: each module handles one concern.
- Modularity and extensibility: easy to swap in new algorithms or data sources.
- Layered design: Data Layer → Business Logic (graph & algorithms) → Presentation Layer (GUI/plots).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Layer
    subgraph "Data Layer" 
        direction TB
        RN[(TQ_RoadNode.*)]:::datastore
        click RN "https://github.com/aspekts/urban-ev-pathfinding/blob/main/data/TQ_RoadNode.*"
        RL[(TQ_RoadLink.*)]:::datastore
        click RL "https://github.com/aspekts/urban-ev-pathfinding/blob/main/data/TQ_RoadLink.*"
        MJ[(TQ_MotorwayJunction.*)]:::datastore
        click MJ "https://github.com/aspekts/urban-ev-pathfinding/blob/main/data/TQ_MotorwayJunction.*"
        CSV1[(dft_traffic_counts_aadf.csv)]:::datastore
        click CSV1 "https://github.com/aspekts/urban-ev-pathfinding/blob/main/data/dft_traffic_counts_aadf.csv"
        CSV2[(national-charge-point-registry.csv)]:::datastore
        click CSV2 "https://github.com/aspekts/urban-ev-pathfinding/blob/main/data/national-charge-point-registry.csv"
    end

    %% Processing Layer
    subgraph "Processing & Logic Layer"
        direction TB
        DP["Data Ingestion & Cleaning\ndata_processing.py"]:::module
        click DP "https://github.com/aspekts/urban-ev-pathfinding/blob/main/data_processing.py"
        GB["Graph Construction\nbuild_graph() in graph.py"]:::module
        SE["Search Engine\na_star_search(), BFS, UCS"]:::module
        CALC["Distance & Time Calculation\ncalculate_total_distance_and_time()"]:::module
    end

    %% Presentation Layer
    subgraph "Presentation & Testing Layer"
        direction TB
        VIS["Visualization\ntest_and_visualize()\n(test_data.py)"]:::module
        click VIS "https://github.com/aspekts/urban-ev-pathfinding/blob/main/test_data.py"
        DT["Dataset Tests\n(dataset_test.py)"]:::module
        click DT "https://github.com/aspekts/urban-ev-pathfinding/blob/main/dataset_test.py"
        GUI["GUI Application & Orchestration\nPathfindingApp in main.py"]:::module
        click GUI "https://github.com/aspekts/urban-ev-pathfinding/blob/main/main.py"
        EX["Example Usage & Demos\n(example/)"]:::module
        click EX "https://github.com/aspekts/urban-ev-pathfinding/tree/main/example/"
        REQ["Dependencies\nrequirements.txt"]:::module
        click REQ "https://github.com/aspekts/urban-ev-pathfinding/blob/main/requirements.txt"
    end

    %% Data Flow
    RN -->|GeoDataFrame of nodes| DP
    RL -->|GeoDataFrame of links| DP
    MJ -->|GeoDataFrame of junctions| DP
    CSV1 -->|Traffic CSV Data| DP
    CSV2 -->|Charging Station CSV Data| DP

    DP -->|Cleaned GeoDataFrames| GB
    GB -->|"NetworkX DiGraph"| SE
    SE -->|Routes & Heuristics| CALC
    CALC -->|Distance & Time Metrics| VIS
    CALC -->|Metrics for UI| GUI

    %% Orchestration
    GUI -->|calls| DP
    GUI -->|calls| GB
    GUI -->|calls| SE
    GUI -->|calls| VIS

    %% Testing Hooks
    DT -->|validates| DP
    DT -->|validates| GB
    DT -->|validates| SE

    %% Styles
    classDef datastore fill:#f2e6ff,stroke:#666,stroke-width:1px
    classDef module fill:#e5f0ff,stroke:#333,stroke-width:1px
    classDef dataLayer fill:#e5ffe5
    classDef processing fill:#e5f0ff
    classDef presentation fill:#ffe9cc

    class RN,RL,MJ,CSV1,CSV2 datastore
    class DP,GB,SE,CALC module
    class VIS,DT,GUI,EX,REQ module
```
