# thiennguyen62/map-search architecture

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

- Interactive diagram: https://gitdiagram.com/thiennguyen62/map-search
- Repository: https://github.com/thiennguyen62/map-search

## Overview

Map Search is a metro route-finding web app. A user selects source and destination stations, chooses Dijkstra or A*, requests a route, and views its route details on a map. The backend loads station and edge data into a graph, resolves station names, computes routes, and exposes JSON APIs. Separate account and admin capabilities include authentication, user management, login history, and admin-state storage. The README documents A* selection, but the sampled pathfinding service calls Dijkstra; unsampled frontend wiring and admin-data updates are not assumed.

Main entry points: [`backend/app.py`](https://github.com/thiennguyen62/map-search/blob/main/backend/app.py) (Web application), [`backend/models/graph.py`](https://github.com/thiennguyen62/map-search/blob/main/backend/models/graph.py) (Graph loader), [`frontend/js/script.js`](https://github.com/thiennguyen62/map-search/blob/main/frontend/js/script.js) (Route search), [`backend/api/routes.py`](https://github.com/thiennguyen62/map-search/blob/main/backend/api/routes.py) (JSON API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web interface"]
  node_search_ui["Route search<br/>[script.js]"]
  node_map_ui["Map display<br/>[diagram.js]"]
  node_login_ui["Login and signup<br/>[login.js]"]
  node_user_ui["User profile<br/>[user.js]"]
  node_history_ui["Login history<br/>[user_history.js]"]
  node_admin_ui["Admin interface<br/>[admin.html]"]
end

subgraph group_routing["Route computation"]
  node_flask_app["Web application<br/>[app.py]"]
  node_api["JSON API<br/>[routes.py]"]
  node_path_service["Route service"]
  node_dijkstra["Dijkstra search<br/>[dijkstra.py]"]
  node_astar["A* search<br/>[astar.py]"]
end

subgraph group_accounts["Accounts and admin"]
  node_user_service["User service<br/>[user.py]"]
  node_user_db[("User database<br/>[users.db]")]
  node_admin_data["Admin state<br/>[admin.json]"]
end

subgraph group_data["Transit data"]
  node_graph_model["Graph loader<br/>[graph.py]"]
  node_station_model["Station model<br/>[station.py]"]
  node_edge_model["Edge model<br/>[edge.py]"]
  node_station_data["Station records<br/>[stations.json]"]
  node_edge_data["Connection records<br/>[edges.json]"]
end

node_traveler(("Traveler"))

node_traveler -->|"chooses stations"| node_search_ui
node_search_ui -->|"requests route"| node_api
node_api -->|"calls find_path"| node_path_service
node_path_service -->|"loads graph"| node_graph_model
node_path_service -->|"calls fallback"| node_dijkstra
node_api -->|"returns route JSON"| node_search_ui
node_search_ui -->|"displays route"| node_map_ui
node_graph_model -->|"reads stations"| node_station_data
node_graph_model -->|"reads connections"| node_edge_data
node_graph_model -->|"creates stations"| node_station_model
node_graph_model -->|"creates edges"| node_edge_model
node_traveler -->|"authenticates"| node_login_ui
node_flask_app -->|"registers routes"| node_api
node_flask_app -->|"uses account operations"| node_user_service
node_user_service -->|"reads and writes"| node_user_db
node_login_ui -.->|"uses auth API"| node_flask_app
node_user_ui -.->|"uses account API"| node_flask_app
node_history_ui -.->|"requests history"| node_flask_app
node_admin_ui -.->|"uses admin API"| node_flask_app
node_admin_ui -.->|"admin state"| node_admin_data
node_traveler -.->|"can select A*"| node_astar

click node_search_ui "https://github.com/thiennguyen62/map-search/blob/main/frontend/js/script.js"
click node_map_ui "https://github.com/thiennguyen62/map-search/blob/main/frontend/js/diagram.js"
click node_login_ui "https://github.com/thiennguyen62/map-search/blob/main/frontend/js/login.js"
click node_user_ui "https://github.com/thiennguyen62/map-search/blob/main/frontend/js/user.js"
click node_history_ui "https://github.com/thiennguyen62/map-search/blob/main/frontend/js/user_history.js"
click node_admin_ui "https://github.com/thiennguyen62/map-search/blob/main/frontend/html/admin.html"
click node_flask_app "https://github.com/thiennguyen62/map-search/blob/main/backend/app.py"
click node_api "https://github.com/thiennguyen62/map-search/blob/main/backend/api/routes.py"
click node_path_service "https://github.com/thiennguyen62/map-search/blob/main/backend/services/pathfinding_service.py"
click node_dijkstra "https://github.com/thiennguyen62/map-search/blob/main/backend/algorithms/dijkstra.py"
click node_astar "https://github.com/thiennguyen62/map-search/blob/main/backend/algorithms/astar.py"
click node_graph_model "https://github.com/thiennguyen62/map-search/blob/main/backend/models/graph.py"
click node_station_model "https://github.com/thiennguyen62/map-search/blob/main/backend/models/station.py"
click node_edge_model "https://github.com/thiennguyen62/map-search/blob/main/backend/models/edge.py"
click node_station_data "https://github.com/thiennguyen62/map-search/blob/main/data/stations.json"
click node_edge_data "https://github.com/thiennguyen62/map-search/blob/main/data/edges.json"
click node_user_service "https://github.com/thiennguyen62/map-search/blob/main/backend/services/user.py"
click node_user_db "https://github.com/thiennguyen62/map-search/blob/main/backend/users.db"
click node_admin_data "https://github.com/thiennguyen62/map-search/blob/main/data/admin.json"

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_search_ui,node_map_ui,node_login_ui,node_user_ui,node_history_ui,node_admin_ui toneBlue
class node_flask_app,node_api,node_path_service,node_dijkstra,node_astar toneAmber
class node_user_service,node_user_db,node_admin_data toneMint
class node_graph_model,node_station_model,node_edge_model,node_station_data,node_edge_data toneRose
class node_traveler toneIndigo
```

## Components

### Web interface

- [Route search](https://github.com/thiennguyen62/map-search/blob/main/frontend/js/script.js): `frontend/js/script.js`
- [Map display](https://github.com/thiennguyen62/map-search/blob/main/frontend/js/diagram.js): `frontend/js/diagram.js`
- [Login and signup](https://github.com/thiennguyen62/map-search/blob/main/frontend/js/login.js): `frontend/js/login.js`
- [User profile](https://github.com/thiennguyen62/map-search/blob/main/frontend/js/user.js): `frontend/js/user.js`
- [Login history](https://github.com/thiennguyen62/map-search/blob/main/frontend/js/user_history.js): `frontend/js/user_history.js`
- [Admin interface](https://github.com/thiennguyen62/map-search/blob/main/frontend/html/admin.html): `frontend/html/admin.html`

### Route computation

- [Web application](https://github.com/thiennguyen62/map-search/blob/main/backend/app.py): `backend/app.py`
- [JSON API](https://github.com/thiennguyen62/map-search/blob/main/backend/api/routes.py): `backend/api/routes.py`
- [Route service](https://github.com/thiennguyen62/map-search/blob/main/backend/services/pathfinding_service.py): `backend/services/pathfinding_service.py`
- [Dijkstra search](https://github.com/thiennguyen62/map-search/blob/main/backend/algorithms/dijkstra.py): `backend/algorithms/dijkstra.py`
- [A* search](https://github.com/thiennguyen62/map-search/blob/main/backend/algorithms/astar.py): `backend/algorithms/astar.py`

### Accounts and admin

- [User service](https://github.com/thiennguyen62/map-search/blob/main/backend/services/user.py): `backend/services/user.py`
- [User database](https://github.com/thiennguyen62/map-search/blob/main/backend/users.db): `backend/users.db`
- [Admin state](https://github.com/thiennguyen62/map-search/blob/main/data/admin.json): `data/admin.json`

### Transit data

- [Graph loader](https://github.com/thiennguyen62/map-search/blob/main/backend/models/graph.py): `backend/models/graph.py`
- [Station model](https://github.com/thiennguyen62/map-search/blob/main/backend/models/station.py): `backend/models/station.py`
- [Edge model](https://github.com/thiennguyen62/map-search/blob/main/backend/models/edge.py): `backend/models/edge.py`
- [Station records](https://github.com/thiennguyen62/map-search/blob/main/data/stations.json): `data/stations.json`
- [Connection records](https://github.com/thiennguyen62/map-search/blob/main/data/edges.json): `data/edges.json`

### Other components

- **Traveler**

## Connections

- Traveler → Route search: chooses stations (evidence: `README.md`)
- Route search → JSON API: requests route (evidence: `README.md`)
- JSON API → Route service: calls find_path (evidence: `backend/api/routes.py`)
- Route service → Graph loader: loads graph (evidence: `backend/services/pathfinding_service.py`)
- Route service → Dijkstra search: calls fallback (evidence: `backend/services/pathfinding_service.py`)
- JSON API → Route search: returns route JSON (evidence: `README.md`)
- Route search → Map display: displays route (evidence: `README.md`)
- Graph loader → Station records: reads stations
- Graph loader → Connection records: reads connections
- Graph loader → Station model: creates stations (evidence: `backend/models/graph.py`)
- Graph loader → Edge model: creates edges (evidence: `backend/models/graph.py`)
- Traveler → Login and signup: authenticates (evidence: `README.md`)
- Web application → JSON API: registers routes (evidence: `backend/app.py`)
- Web application → User service: uses account operations (evidence: `backend/app.py`)
- User service → User database: reads and writes (evidence: `backend/services/user.py`)
- Login and signup → Web application: uses auth API
- User profile → Web application: uses account API
- Login history → Web application: requests history
- Admin interface → Web application: uses admin API
- Admin interface → Admin state: admin state
- Traveler → A* search: can select A*