# guilherme15990/cycling-router-engine architecture

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

- Interactive diagram: https://gitdiagram.com/guilherme15990/cycling-router-engine
- Repository: https://github.com/guilherme15990/cycling-router-engine

## Overview

This is an offline cycling route-planning engine. The principal workflow accepts a planning request, prepares and snaps a route graph, searches for Pareto-optimal candidates, then evaluates and classifies routes before returning route data. The architecture also includes OSM/elevation ingestion, profile-based ranking, physiological and effort prediction, and CLI/API entry points. Edges are limited to relationships visible in excerpts, the source index, or README; unsampled implementation details are not assumed.

Main entry points: [`src/router/app/planning.py`](https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/app/planning.py) (Route orchestration), [`src/router/core/evaluation/assessment.py`](https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/core/evaluation/assessment.py) (Route assessment), [`src/router/core/search/astar.py`](https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/core/search/astar.py) (Pareto search), [`src/router/interfaces/cli/parser.py`](https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/interfaces/cli/parser.py) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Interfaces"]
  node_cli["CLI<br/>[parser.py]"]
  node_api["Python API<br/>[api.py]"]
end

subgraph group_data["Offline map data"]
  node_ingest["OSM ingestion<br/>[ingest.py]"]
  node_elevation["Elevation sources<br/>[elevation.py]"]
  node_graph["Graph operations<br/>[graph.py]"]
end

subgraph group_routing["Route planning"]
  node_offline["Offline planning entry<br/>[planning.py]"]
  node_orchestrator["Route orchestration<br/>[planning.py]"]
  node_search["Pareto search<br/>[astar.py]"]
  node_pipeline["Profile ranking<br/>[pipeline.py]"]
  node_approx["Approximate traversal<br/>[approximate.py]"]
end

subgraph group_assessment["Physics and assessment"]
  node_physics["Physical simulation<br/>[traversal.py]"]
  node_physics_models["Physics results<br/>[models.py]"]
  node_assessment["Route assessment<br/>[assessment.py]"]
  node_classification["Route classification<br/>[classification.py]"]
  node_safety["Safety checks<br/>[safety.py]"]
end

subgraph group_contracts["Prediction and contracts"]
  node_intensity["Intensity estimate<br/>[intensity.py]"]
  node_ml["Effort prediction<br/>[ml.py]"]
  node_physiology["Physiology contracts<br/>[prediction.py]"]
  node_route_contract["Route contract<br/>[route.py]"]
  node_model_store["Prediction model store<br/>[model_store.py]"]
end

node_cyclist(("Cyclist"))

node_cyclist -.->|"submits request"| node_cli
node_cli -->|"dispatches planning"| node_offline
node_api -.->|"calls facade"| node_orchestrator
node_api -->|"uses integration"| node_offline
node_offline -.->|"starts planning"| node_orchestrator
node_ingest -.->|"builds graph"| node_graph
node_elevation -.->|"adds elevation"| node_graph
node_orchestrator -->|"requests candidates"| node_search
node_orchestrator -->|"assesses routes"| node_assessment
node_orchestrator -->|"classifies routes"| node_classification
node_orchestrator -->|"checks safety"| node_safety
node_orchestrator -->|"estimates intensity"| node_intensity
node_orchestrator -.->|"returns route data"| node_route_contract
node_search -.->|"evaluates transitions"| node_physics
node_search -.->|"may use estimate"| node_approx
node_pipeline -->|"runs search"| node_search
node_pipeline -.->|"selects route output"| node_route_contract
node_assessment -->|"simulates route"| node_physics
node_assessment -->|"predicts effort"| node_ml
node_assessment -->|"estimates intensity"| node_intensity
node_physics -->|"produces results"| node_physics_models
node_classification -->|"uses assessment"| node_assessment
node_ml -->|"uses physiology types"| node_physiology
node_model_store -.->|"loads predictors"| node_ml
node_cli -->|"uses graph tools"| node_graph

click node_cli "https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/interfaces/cli/parser.py"
click node_api "https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/interfaces/api.py"
click node_ingest "https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/app/tooling/ingest.py"
click node_elevation "https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/app/tooling/elevation.py"
click node_graph "https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/app/tooling/graph.py"
click node_offline "https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/app/tooling/planning.py"
click node_orchestrator "https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/app/planning.py"
click node_search "https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/core/search/astar.py"
click node_pipeline "https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/core/search/pipeline.py"
click node_approx "https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/core/search/approximate.py"
click node_physics "https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/core/physics/traversal.py"
click node_physics_models "https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/core/physics/models.py"
click node_assessment "https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/core/evaluation/assessment.py"
click node_classification "https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/core/evaluation/classification.py"
click node_safety "https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/core/evaluation/safety.py"
click node_intensity "https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/core/prediction/intensity.py"
click node_ml "https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/core/prediction/ml.py"
click node_physiology "https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/core/physiology/prediction.py"
click node_route_contract "https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/contracts/route.py"
click node_model_store "https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/core/prediction/model_store.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_cli,node_api toneBlue
class node_ingest,node_elevation,node_graph toneAmber
class node_offline,node_orchestrator,node_search,node_pipeline,node_approx toneMint
class node_physics,node_physics_models,node_assessment,node_classification,node_safety toneRose
class node_intensity,node_ml,node_physiology,node_route_contract,node_model_store,node_cyclist toneIndigo
```

## Components

### Interfaces

- [CLI](https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/interfaces/cli/parser.py): `src/router/interfaces/cli/parser.py`
- [Python API](https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/interfaces/api.py): `src/router/interfaces/api.py`

### Offline map data

- [OSM ingestion](https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/app/tooling/ingest.py): `src/router/app/tooling/ingest.py`
- [Elevation sources](https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/app/tooling/elevation.py): `src/router/app/tooling/elevation.py`
- [Graph operations](https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/app/tooling/graph.py): `src/router/app/tooling/graph.py`

### Route planning

- [Offline planning entry](https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/app/tooling/planning.py): `src/router/app/tooling/planning.py`
- [Route orchestration](https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/app/planning.py): `src/router/app/planning.py`
- [Pareto search](https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/core/search/astar.py): `src/router/core/search/astar.py`
- [Profile ranking](https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/core/search/pipeline.py): `src/router/core/search/pipeline.py`
- [Approximate traversal](https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/core/search/approximate.py): `src/router/core/search/approximate.py`

### Physics and assessment

- [Physical simulation](https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/core/physics/traversal.py): `src/router/core/physics/traversal.py`
- [Physics results](https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/core/physics/models.py): `src/router/core/physics/models.py`
- [Route assessment](https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/core/evaluation/assessment.py): `src/router/core/evaluation/assessment.py`
- [Route classification](https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/core/evaluation/classification.py): `src/router/core/evaluation/classification.py`
- [Safety checks](https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/core/evaluation/safety.py): `src/router/core/evaluation/safety.py`

### Prediction and contracts

- [Intensity estimate](https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/core/prediction/intensity.py): `src/router/core/prediction/intensity.py`
- [Effort prediction](https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/core/prediction/ml.py): `src/router/core/prediction/ml.py`
- [Physiology contracts](https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/core/physiology/prediction.py): `src/router/core/physiology/prediction.py`
- [Route contract](https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/contracts/route.py): `src/router/contracts/route.py`
- [Prediction model store](https://github.com/guilherme15990/cycling-router-engine/blob/main/src/router/core/prediction/model_store.py): `src/router/core/prediction/model_store.py`

### Other components

- **Cyclist**

## Connections

- Cyclist → CLI: submits request
- CLI → Offline planning entry: dispatches planning (evidence: `src/router/interfaces/cli/parser.py`)
- Python API → Route orchestration: calls facade
- Python API → Offline planning entry: uses integration (evidence: `src/router/interfaces/api.py`)
- Offline planning entry → Route orchestration: starts planning
- OSM ingestion → Graph operations: builds graph
- Elevation sources → Graph operations: adds elevation
- Route orchestration → Pareto search: requests candidates (evidence: `src/router/app/planning.py`)
- Route orchestration → Route assessment: assesses routes (evidence: `src/router/app/planning.py`)
- Route orchestration → Route classification: classifies routes (evidence: `src/router/app/planning.py`)
- Route orchestration → Safety checks: checks safety (evidence: `src/router/app/planning.py`)
- Route orchestration → Intensity estimate: estimates intensity (evidence: `src/router/app/planning.py`)
- Route orchestration → Route contract: returns route data
- Pareto search → Physical simulation: evaluates transitions
- Pareto search → Approximate traversal: may use estimate (evidence: `src/router/core/search/approximate.py`)
- Profile ranking → Pareto search: runs search (evidence: `src/router/core/search/pipeline.py`)
- Profile ranking → Route contract: selects route output
- Route assessment → Physical simulation: simulates route (evidence: `src/router/core/evaluation/assessment.py`)
- Route assessment → Effort prediction: predicts effort (evidence: `src/router/core/evaluation/assessment.py`)
- Route assessment → Intensity estimate: estimates intensity (evidence: `src/router/core/evaluation/assessment.py`)
- Physical simulation → Physics results: produces results (evidence: `src/router/core/physics/traversal.py`)
- Route classification → Route assessment: uses assessment (evidence: `src/router/core/evaluation/classification.py`)
- Effort prediction → Physiology contracts: uses physiology types (evidence: `src/router/core/prediction/ml.py`)
- Prediction model store → Effort prediction: loads predictors
- CLI → Graph operations: uses graph tools