# chandu8861/basic-navigation-project architecture

> Architecture diagram of the GitHub repository chandu8861/basic-navigation-project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chandu8861/basic-navigation-project
- Repository: https://github.com/chandu8861/basic-navigation-project

## Overview

1. **Repository purpose**
   - This is a two-part AI search visualization tool for Bengaluru geography.
   - The core architecture compares two route-finding strategies on the same city graph: **A\*** and **Greedy Best-First Search**.

2. **Primary system boundary**
   - The repo is split into a **Python backend** that owns the graph/search logic and a **React frontend** that owns visualization and user interaction.
   - The frontend does not appear to compute routes itself; it consumes results from the backend.

3. **Backend: search and graph domain**
   - `backend/algorithms.py` is the algorithm engine, implementing the pathfinding logic and likely the heuristic scoring used by both strategies.
   - The backend is the source of truth for path optimality, explored-node counts, and other metrics shown in the UI.

4. **Backend: data model**
   - `backend/bangalore_map.json` is the city graph dataset: landmark nodes with coordinates plus connectivity/adjacency information.
   - This file is the static input that defines the searchable state space across 150+ Bengaluru landmarks.

5. **Backend API layer**
   - `backend/main.py` is the FastAPI entrypoint and route definition layer.
   - It likely exposes endpoints for running searches and returning path/metrics payloads to the frontend.
   - FastAPI also provides the interactive API docs surface mentioned in the README.

6. **Backend support scripts**
   - `backend/rebuild_graph.py` and `backend/validate_graph.py` are offline maintenance tools.
   - These indicate a separate data-preparation boundary: one script regenerates or normalizes the graph, and the other checks consistency/quality before the map is used by the API.

7. **Frontend application shell**
   - `frontend/src/main.jsx` bootstraps the React app, while `frontend/src/App.jsx` is the stateful coordinator for the whole UI.
   - `App.jsx` likely manages source/destination selection, triggering searches, and distributing the backend response to the visual components.

8. **Map visualization subsystem**
   - `frontend/src/components/MapView.jsx` renders the geographic view using Leaflet.
   - This view visualizes real coordinates, route polylines, and color-coded results for A\* vs. Greedy paths.

9. **Graph visualization subsystem**
   - `frontend/src/components/GraphView.jsx` renders the abstract graph using D3.
   - This component is the “state-space” view: nodes, edges, and search behavior as a force-directed simulation rather than a map.

10. **Metrics/dashboard subsystem**
    - `frontend/src/components/Dashboard.jsx` presents the comparative analytics: path length, distance, and nodes explored.
    - This is the main feedback surface for the algorithm trade-off story, not just a decorative panel.

11. **Data flow through the system**
    - User picks endpoints in the frontend.
    - The frontend sends the query to the FastAPI backend.
    - The backend loads/uses the Bangalore graph, runs both algorithms, and returns route + metric results.
    - The frontend then renders those results simultaneously in the map, graph, and dashboard views.

12. **Visualization semantics**
    - The UI uses a consistent comparison model across views: A\* path, Greedy path, and shared segments are visually distinguished.
    - This means the repo is organized around a single shared result model consumed by multiple presentation layers.

13. **Runtime and tooling**
    - Backend: Python 3.10+ with FastAPI.
    - Frontend: React with Vite, plus Leaflet for maps and D3 for graph layout.
    - The build/run setup is intentionally lightweight: no separate database or external orchestration layer is present in the tree.

14. **Architectural takeaway for a diagram**
    - Draw three main layers: **graph data + search engine** in the backend, **API boundary** in the middle, and **dual visualization UI** in the frontend.
    - Emphasize that the repository is a comparative AI demonstration: one dataset, two algorithms, three synchronized visual outputs.

Main entry points: [`frontend/src/App.jsx`](https://github.com/chandu8861/basic-navigation-project/blob/main/frontend/src/App.jsx) (App shell), [`backend/main.py`](https://github.com/chandu8861/basic-navigation-project/blob/main/backend/main.py) (API), [`backend/bangalore_map.json`](https://github.com/chandu8861/basic-navigation-project/blob/main/backend/bangalore_map.json) (Bengaluru graph), [`backend/algorithms.py`](https://github.com/chandu8861/basic-navigation-project/blob/main/backend/algorithms.py) (Search engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_main["API<br/>[main.py]"]
  node_backend_algorithms["Search engine<br/>pathfinding logic<br/>[algorithms.py]"]
  node_backend_map[("Bengaluru graph<br/>city dataset<br/>[bangalore_map.json]")]
  node_backend_rebuild["Rebuild graph<br/>maintenance script<br/>[rebuild_graph.py]"]
  node_backend_validate["Validate graph<br/>quality check<br/>[validate_graph.py]"]
end

subgraph group_frontend["Frontend"]
  node_frontend_main["Bootstraps<br/>React entrypoint<br/>[main.jsx]"]
  node_frontend_app["App shell<br/>UI coordinator<br/>[App.jsx]"]
  node_frontend_map["Map view<br/>Leaflet visualization<br/>[MapView.jsx]"]
  node_frontend_graph["Graph view<br/>D3 visualization<br/>[GraphView.jsx]"]
  node_frontend_dash["Dashboard<br/>metrics panel<br/>[Dashboard.jsx]"]
end

node_search_result["Search result<br/>response contract"]

node_frontend_main -->|"mounts"| node_frontend_app
node_frontend_app -->|"queries"| node_backend_main
node_backend_main -->|"runs"| node_backend_algorithms
node_backend_main -->|"loads"| node_backend_map
node_backend_algorithms -->|"reads"| node_backend_map
node_backend_rebuild -.->|"generates"| node_backend_map
node_backend_validate -.->|"checks"| node_backend_map
node_backend_main -->|"returns"| node_search_result
node_search_result -->|"consumed by"| node_frontend_app
node_frontend_app -->|"feeds"| node_frontend_map
node_frontend_app -->|"feeds"| node_frontend_graph
node_frontend_app -->|"feeds"| node_frontend_dash
node_search_result -->|"renders"| node_frontend_map
node_search_result -->|"renders"| node_frontend_graph
node_search_result -->|"renders"| node_frontend_dash

click node_backend_main "https://github.com/chandu8861/basic-navigation-project/blob/main/backend/main.py"
click node_backend_algorithms "https://github.com/chandu8861/basic-navigation-project/blob/main/backend/algorithms.py"
click node_backend_map "https://github.com/chandu8861/basic-navigation-project/blob/main/backend/bangalore_map.json"
click node_backend_rebuild "https://github.com/chandu8861/basic-navigation-project/blob/main/backend/rebuild_graph.py"
click node_backend_validate "https://github.com/chandu8861/basic-navigation-project/blob/main/backend/validate_graph.py"
click node_frontend_main "https://github.com/chandu8861/basic-navigation-project/blob/main/frontend/src/main.jsx"
click node_frontend_app "https://github.com/chandu8861/basic-navigation-project/blob/main/frontend/src/App.jsx"
click node_frontend_map "https://github.com/chandu8861/basic-navigation-project/blob/main/frontend/src/components/MapView.jsx"
click node_frontend_graph "https://github.com/chandu8861/basic-navigation-project/blob/main/frontend/src/components/GraphView.jsx"
click node_frontend_dash "https://github.com/chandu8861/basic-navigation-project/blob/main/frontend/src/components/Dashboard.jsx"

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_backend_main,node_backend_algorithms,node_backend_map,node_backend_rebuild,node_backend_validate toneBlue
class node_frontend_main,node_frontend_app,node_frontend_map,node_frontend_graph,node_frontend_dash toneAmber
class node_search_result toneNeutral
```

## Components

### Backend

Python API, search engine, and city graph data.

- [API](https://github.com/chandu8861/basic-navigation-project/blob/main/backend/main.py): FastAPI entrypoint · Exposes search endpoints and returns route plus metrics payloads. · `backend/main.py`
- [Search engine](https://github.com/chandu8861/basic-navigation-project/blob/main/backend/algorithms.py): pathfinding logic · Implements A* and Greedy Best-First Search over the Bengaluru graph. · `backend/algorithms.py`
- [Bengaluru graph](https://github.com/chandu8861/basic-navigation-project/blob/main/backend/bangalore_map.json): city dataset · Static landmark and adjacency data defining the searchable state space. · `backend/bangalore_map.json`
- [Rebuild graph](https://github.com/chandu8861/basic-navigation-project/blob/main/backend/rebuild_graph.py): maintenance script · Regenerates or normalizes the graph dataset offline. · `backend/rebuild_graph.py`
- [Validate graph](https://github.com/chandu8861/basic-navigation-project/blob/main/backend/validate_graph.py): quality check · Checks graph consistency before the dataset is used by the API. · `backend/validate_graph.py`

### Frontend

React app shell and visual comparison views.

- [Bootstraps](https://github.com/chandu8861/basic-navigation-project/blob/main/frontend/src/main.jsx): React entrypoint · Starts the frontend application. · `frontend/src/main.jsx`
- [App shell](https://github.com/chandu8861/basic-navigation-project/blob/main/frontend/src/App.jsx): UI coordinator · Manages endpoints, triggers searches, and distributes backend results. · `frontend/src/App.jsx`
- [Map view](https://github.com/chandu8861/basic-navigation-project/blob/main/frontend/src/components/MapView.jsx): Leaflet visualization · Renders geographic routes, coordinates, and path comparison on the city map. · `frontend/src/components/MapView.jsx`
- [Graph view](https://github.com/chandu8861/basic-navigation-project/blob/main/frontend/src/components/GraphView.jsx): D3 visualization · Shows the abstract search space and exploration behavior as a graph. · `frontend/src/components/GraphView.jsx`
- [Dashboard](https://github.com/chandu8861/basic-navigation-project/blob/main/frontend/src/components/Dashboard.jsx): metrics panel · Displays comparative analytics such as path length, distance, and nodes explored. · `frontend/src/components/Dashboard.jsx`

### Other components

- **Search result**: response contract · Shared route-and-metrics payload consumed by the UI layers.

## Connections

- Bootstraps → App shell: mounts · Bootstraps the React application.
- App shell → API: queries · Sends origin and destination requests to the API.
- API → Search engine: runs · Invokes the pathfinding strategies for each request.
- API → Bengaluru graph: loads · Uses the Bengaluru graph as the search domain.
- Search engine → Bengaluru graph: reads · Traverses the static city graph and coordinates.
- Rebuild graph → Bengaluru graph: generates · Produces or normalizes the graph dataset offline.
- Validate graph → Bengaluru graph: checks · Verifies dataset consistency and quality.
- API → Search result: returns · Produces a unified path and metrics payload.
- Search result → App shell: consumed by · App state receives the backend response.
- App shell → Map view: feeds · Passes routes and comparison state to the map view.
- App shell → Graph view: feeds · Passes routes and exploration state to the graph view.
- App shell → Dashboard: feeds · Passes metrics for the comparison dashboard.
- Search result → Map view: renders · Map view visualizes the returned route set.
- Search result → Graph view: renders · Graph view visualizes the returned search state.
- Search result → Dashboard: renders · Dashboard summarizes the returned metrics.