How chandu8861/basic-navigation-project works
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: App.jsx App shell · main.py API · bangalore_map.json Bengaluru graph · algorithms.py Search engine
Components 11
Backend
Python API, search engine, and city graph data.
- API · Exposes search endpoints and returns route plus metrics payloads.
backend/main.py - Search engine · Implements A* and Greedy Best-First Search over the Bengaluru graph.
backend/algorithms.py - Bengaluru graph · Static landmark and adjacency data defining the searchable state space.
backend/bangalore_map.json - Rebuild graph · Regenerates or normalizes the graph dataset offline.
backend/rebuild_graph.py - Validate graph · Checks graph consistency before the dataset is used by the API.
backend/validate_graph.py
Frontend
React app shell and visual comparison views.
- Bootstraps · Starts the frontend application.
frontend/src/main.jsx - App shell · Manages endpoints, triggers searches, and distributes backend results.
frontend/src/App.jsx - Map view · Renders geographic routes, coordinates, and path comparison on the city map.
frontend/src/components/MapView.jsx - Graph view · Shows the abstract search space and exploration behavior as a graph.
frontend/src/components/GraphView.jsx - Dashboard · Displays comparative analytics such as path length, distance, and nodes explored.
frontend/src/components/Dashboard.jsx
Other components
- Search result · Shared route-and-metrics payload consumed by the UI layers.
Connections 15
- 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.