# stanislavorlov/geo-maps architecture

> Architecture diagram of the GitHub repository stanislavorlov/geo-maps, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stanislavorlov/geo-maps
- Repository: https://github.com/stanislavorlov/geo-maps

## Overview

geo-maps serves map pages, geocoding, and road routing over an OpenStreetMap-derived graph. The main route workflow accepts coordinates and travel preferences, loads a nearby mode-filtered road graph, snaps endpoints to nodes, selects a routing algorithm, and returns route metrics; its WebSocket variant also streams progress. The map interface, parser/import path, and database-backed location search are separate meaningful capabilities. Edges reflect explicit excerpts, the source index, or README; unshown wiring is omitted.

Main entry points: [`app/api/directions.py`](https://github.com/stanislavorlov/geo-maps/blob/master/app/api/directions.py) (Directions API), [`app/graph/graph.py`](https://github.com/stanislavorlov/geo-maps/blob/master/app/graph/graph.py) (Road graph), [`app/routing_algorithms/astar_routing.py`](https://github.com/stanislavorlov/geo-maps/blob/master/app/routing_algorithms/astar_routing.py) (A-star routing), [`app/main.py`](https://github.com/stanislavorlov/geo-maps/blob/master/app/main.py) (FastAPI app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_webpage["Map page<br/>[index.html]"]
  node_browser["Map client<br/>[main.js]"]
end

subgraph group_api["API and search"]
  node_application["FastAPI app<br/>[main.py]"]
  node_pages["Page routes<br/>[pages.py]"]
  node_directions["Directions API<br/>[directions.py]"]
  node_geocoding["Geocoding API<br/>[geocoding.py]"]
  node_searchmodels["Search requests<br/>[search_model.py]"]
  node_geocodeservice["Geocode service<br/>[geocode_service.py]"]
end

subgraph group_routing["Routing"]
  node_graphfactory["Graph factory<br/>[graph_factory.py]"]
  node_graph["Road graph<br/>[graph.py]"]
  node_spatialindex["Spatial indexes<br/>[kd_tree.py]"]
  node_routingfactory["Algorithm selector<br/>[routing_factory.py]"]
  node_routebase["Routing contract"]
  node_astar["A-star routing<br/>[astar_routing.py]"]
  node_dijkstra["Dijkstra routing"]
  node_bidir["Bidirectional routing"]
  node_speed["Mode access rules"]
  node_traveltime["Travel-time calculator"]
  node_notifications["Route progress"]
end

subgraph group_storage["Road data"]
  node_locationrepo["Location lookup"]
  node_dbdeps["DB dependencies<br/>[dependencies.py]"]
  node_database[("Database session<br/>[database.py]")]
  node_entities["Road entities<br/>[models.py]"]
  node_graphrepo["Route graph query"]
  node_parser["OSM parser<br/>[osm_parser.py]"]
end

node_user(("Map user"))

node_user -->|"uses"| node_browser
node_browser -.->|"requests pages"| node_application
node_application -.->|"routes pages"| node_pages
node_application -->|"registers routes"| node_directions
node_application -->|"registers routes"| node_geocoding
node_application -->|"initializes"| node_database
node_user -->|"requests route"| node_directions
node_directions -->|"validates request"| node_searchmodels
node_directions -->|"loads graph"| node_graphrepo
node_directions -->|"selects algorithm"| node_routingfactory
node_directions -->|"snaps endpoints"| node_graph
node_directions -.->|"streams progress"| node_browser
node_geocoding -->|"uses requests"| node_searchmodels
node_geocoding -->|"looks up locations"| node_locationrepo
node_geocoding -->|"geocodes"| node_geocodeservice
node_dbdeps -->|"opens sessions"| node_database
node_dbdeps -->|"provides repository"| node_graphrepo
node_dbdeps -->|"provides repository"| node_locationrepo
node_locationrepo -->|"queries"| node_entities
node_graphrepo -->|"queries roads"| node_entities
node_graphrepo -->|"filters road types"| node_speed
node_graphrepo -->|"builds graph"| node_graphfactory
node_graphfactory -->|"creates"| node_graph
node_graph -.->|"indexes nodes"| node_spatialindex
node_routingfactory -->|"selects"| node_astar
node_routingfactory -->|"selects"| node_dijkstra
node_routingfactory -->|"selects"| node_bidir
node_astar -->|"implements"| node_routebase
node_dijkstra -->|"implements"| node_routebase
node_bidir -->|"implements"| node_routebase
node_astar -->|"traverses"| node_graph
node_dijkstra -->|"traverses"| node_graph
node_bidir -->|"traverses"| node_graph
node_astar -->|"checks access"| node_speed
node_bidir -->|"checks access"| node_speed
node_astar -->|"calculates time"| node_traveltime
node_astar -->|"emits progress"| node_notifications
node_bidir -->|"emits progress"| node_notifications
node_parser -->|"builds map graph"| node_graph
node_parser -->|"uses entities"| node_entities

click node_webpage "https://github.com/stanislavorlov/geo-maps/blob/master/app/templates/index.html"
click node_browser "https://github.com/stanislavorlov/geo-maps/blob/master/app/templates/js/main.js"
click node_application "https://github.com/stanislavorlov/geo-maps/blob/master/app/main.py"
click node_pages "https://github.com/stanislavorlov/geo-maps/blob/master/app/api/pages.py"
click node_directions "https://github.com/stanislavorlov/geo-maps/blob/master/app/api/directions.py"
click node_geocoding "https://github.com/stanislavorlov/geo-maps/blob/master/app/api/geocoding.py"
click node_searchmodels "https://github.com/stanislavorlov/geo-maps/blob/master/app/models/search_model.py"
click node_geocodeservice "https://github.com/stanislavorlov/geo-maps/blob/master/app/services/geocode_service.py"
click node_locationrepo "https://github.com/stanislavorlov/geo-maps/blob/master/app/database/location_repository.py"
click node_dbdeps "https://github.com/stanislavorlov/geo-maps/blob/master/app/api/dependencies.py"
click node_database "https://github.com/stanislavorlov/geo-maps/blob/master/app/database/database.py"
click node_entities "https://github.com/stanislavorlov/geo-maps/blob/master/app/database/models.py"
click node_graphrepo "https://github.com/stanislavorlov/geo-maps/blob/master/app/database/graph_repository.py"
click node_graphfactory "https://github.com/stanislavorlov/geo-maps/blob/master/app/graph/graph_factory.py"
click node_graph "https://github.com/stanislavorlov/geo-maps/blob/master/app/graph/graph.py"
click node_spatialindex "https://github.com/stanislavorlov/geo-maps/blob/master/app/graph/kd_tree.py"
click node_routingfactory "https://github.com/stanislavorlov/geo-maps/blob/master/app/routing_algorithms/routing_factory.py"
click node_routebase "https://github.com/stanislavorlov/geo-maps/blob/master/app/routing_algorithms/abstract_routing.py"
click node_astar "https://github.com/stanislavorlov/geo-maps/blob/master/app/routing_algorithms/astar_routing.py"
click node_dijkstra "https://github.com/stanislavorlov/geo-maps/blob/master/app/routing_algorithms/dijkstra_routing.py"
click node_bidir "https://github.com/stanislavorlov/geo-maps/blob/master/app/routing_algorithms/bidirectional_dijkstra_routing.py"
click node_speed "https://github.com/stanislavorlov/geo-maps/blob/master/app/services/speed_limit_service.py"
click node_traveltime "https://github.com/stanislavorlov/geo-maps/blob/master/app/services/travel_time_service.py"
click node_notifications "https://github.com/stanislavorlov/geo-maps/blob/master/app/models/notification_model.py"
click node_parser "https://github.com/stanislavorlov/geo-maps/blob/master/data/parser/osm_parser.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_webpage,node_browser,node_user toneBlue
class node_application,node_pages,node_directions,node_geocoding,node_searchmodels,node_geocodeservice toneAmber
class node_graphfactory,node_graph,node_spatialindex,node_routingfactory,node_routebase,node_astar,node_dijkstra,node_bidir,node_speed,node_traveltime,node_notifications toneMint
class node_locationrepo,node_dbdeps,node_database,node_entities,node_graphrepo,node_parser toneRose
```

## Components

### User interface

- [Map page](https://github.com/stanislavorlov/geo-maps/blob/master/app/templates/index.html): `app/templates/index.html`
- [Map client](https://github.com/stanislavorlov/geo-maps/blob/master/app/templates/js/main.js): `app/templates/js/main.js`

### API and search

- [FastAPI app](https://github.com/stanislavorlov/geo-maps/blob/master/app/main.py): `app/main.py`
- [Page routes](https://github.com/stanislavorlov/geo-maps/blob/master/app/api/pages.py): `app/api/pages.py`
- [Directions API](https://github.com/stanislavorlov/geo-maps/blob/master/app/api/directions.py): `app/api/directions.py`
- [Geocoding API](https://github.com/stanislavorlov/geo-maps/blob/master/app/api/geocoding.py): `app/api/geocoding.py`
- [Search requests](https://github.com/stanislavorlov/geo-maps/blob/master/app/models/search_model.py): `app/models/search_model.py`
- [Geocode service](https://github.com/stanislavorlov/geo-maps/blob/master/app/services/geocode_service.py): `app/services/geocode_service.py`

### Routing

- [Graph factory](https://github.com/stanislavorlov/geo-maps/blob/master/app/graph/graph_factory.py): `app/graph/graph_factory.py`
- [Road graph](https://github.com/stanislavorlov/geo-maps/blob/master/app/graph/graph.py): `app/graph/graph.py`
- [Spatial indexes](https://github.com/stanislavorlov/geo-maps/blob/master/app/graph/kd_tree.py): `app/graph/kd_tree.py`
- [Algorithm selector](https://github.com/stanislavorlov/geo-maps/blob/master/app/routing_algorithms/routing_factory.py): `app/routing_algorithms/routing_factory.py`
- [Routing contract](https://github.com/stanislavorlov/geo-maps/blob/master/app/routing_algorithms/abstract_routing.py): `app/routing_algorithms/abstract_routing.py`
- [A-star routing](https://github.com/stanislavorlov/geo-maps/blob/master/app/routing_algorithms/astar_routing.py): `app/routing_algorithms/astar_routing.py`
- [Dijkstra routing](https://github.com/stanislavorlov/geo-maps/blob/master/app/routing_algorithms/dijkstra_routing.py): `app/routing_algorithms/dijkstra_routing.py`
- [Bidirectional routing](https://github.com/stanislavorlov/geo-maps/blob/master/app/routing_algorithms/bidirectional_dijkstra_routing.py): `app/routing_algorithms/bidirectional_dijkstra_routing.py`
- [Mode access rules](https://github.com/stanislavorlov/geo-maps/blob/master/app/services/speed_limit_service.py): `app/services/speed_limit_service.py`
- [Travel-time calculator](https://github.com/stanislavorlov/geo-maps/blob/master/app/services/travel_time_service.py): `app/services/travel_time_service.py`
- [Route progress](https://github.com/stanislavorlov/geo-maps/blob/master/app/models/notification_model.py): `app/models/notification_model.py`

### Road data

- [Location lookup](https://github.com/stanislavorlov/geo-maps/blob/master/app/database/location_repository.py): `app/database/location_repository.py`
- [DB dependencies](https://github.com/stanislavorlov/geo-maps/blob/master/app/api/dependencies.py): `app/api/dependencies.py`
- [Database session](https://github.com/stanislavorlov/geo-maps/blob/master/app/database/database.py): `app/database/database.py`
- [Road entities](https://github.com/stanislavorlov/geo-maps/blob/master/app/database/models.py): `app/database/models.py`
- [Route graph query](https://github.com/stanislavorlov/geo-maps/blob/master/app/database/graph_repository.py): `app/database/graph_repository.py`
- [OSM parser](https://github.com/stanislavorlov/geo-maps/blob/master/data/parser/osm_parser.py): `data/parser/osm_parser.py`

### Other components

- **Map user**

## Connections

- Map user → Map client: uses (evidence: `app/templates/js/main.js`)
- Map client → FastAPI app: requests pages
- FastAPI app → Page routes: routes pages (evidence: `app/main.py`)
- FastAPI app → Directions API: registers routes (evidence: `app/main.py`)
- FastAPI app → Geocoding API: registers routes (evidence: `app/main.py`)
- FastAPI app → Database session: initializes (evidence: `app/main.py`)
- Map user → Directions API: requests route (evidence: `app/api/directions.py`)
- Directions API → Search requests: validates request (evidence: `app/api/directions.py`)
- Directions API → Route graph query: loads graph (evidence: `app/api/directions.py`)
- Directions API → Algorithm selector: selects algorithm (evidence: `app/api/directions.py`)
- Directions API → Road graph: snaps endpoints (evidence: `app/api/directions.py`)
- Directions API → Map client: streams progress
- Geocoding API → Search requests: uses requests (evidence: `app/api/geocoding.py`)
- Geocoding API → Location lookup: looks up locations (evidence: `app/api/geocoding.py`)
- Geocoding API → Geocode service: geocodes (evidence: `app/api/geocoding.py`)
- DB dependencies → Database session: opens sessions (evidence: `app/api/dependencies.py`)
- DB dependencies → Route graph query: provides repository (evidence: `app/api/dependencies.py`)
- DB dependencies → Location lookup: provides repository (evidence: `app/api/dependencies.py`)
- Location lookup → Road entities: queries (evidence: `app/database/location_repository.py`)
- Route graph query → Road entities: queries roads (evidence: `app/database/graph_repository.py`)
- Route graph query → Mode access rules: filters road types (evidence: `app/database/graph_repository.py`)
- Route graph query → Graph factory: builds graph (evidence: `app/database/graph_repository.py`)
- Graph factory → Road graph: creates (evidence: `app/graph/graph_factory.py`)
- Road graph → Spatial indexes: indexes nodes
- Algorithm selector → A-star routing: selects (evidence: `app/routing_algorithms/routing_factory.py`)
- Algorithm selector → Dijkstra routing: selects (evidence: `app/routing_algorithms/routing_factory.py`)
- Algorithm selector → Bidirectional routing: selects (evidence: `app/routing_algorithms/routing_factory.py`)
- A-star routing → Routing contract: implements (evidence: `app/routing_algorithms/astar_routing.py`)
- Dijkstra routing → Routing contract: implements (evidence: `app/routing_algorithms/dijkstra_routing.py`)
- Bidirectional routing → Routing contract: implements (evidence: `app/routing_algorithms/bidirectional_dijkstra_routing.py`)
- A-star routing → Road graph: traverses (evidence: `app/routing_algorithms/astar_routing.py`)
- Dijkstra routing → Road graph: traverses (evidence: `app/routing_algorithms/dijkstra_routing.py`)
- Bidirectional routing → Road graph: traverses (evidence: `app/routing_algorithms/bidirectional_dijkstra_routing.py`)
- A-star routing → Mode access rules: checks access (evidence: `app/routing_algorithms/astar_routing.py`)
- Bidirectional routing → Mode access rules: checks access (evidence: `app/routing_algorithms/bidirectional_dijkstra_routing.py`)
- A-star routing → Travel-time calculator: calculates time (evidence: `app/routing_algorithms/astar_routing.py`)
- A-star routing → Route progress: emits progress (evidence: `app/routing_algorithms/astar_routing.py`)
- Bidirectional routing → Route progress: emits progress (evidence: `app/routing_algorithms/bidirectional_dijkstra_routing.py`)
- OSM parser → Road graph: builds map graph (evidence: `data/parser/osm_parser.py`)
- OSM parser → Road entities: uses entities (evidence: `data/parser/osm_parser.py`)
