# jl115/valhalla architecture

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

- Interactive diagram: https://gitdiagram.com/jl115/valhalla
- Repository: https://github.com/jl115/valhalla

## Overview

Valhalla is an OpenStreetMap-based routing engine and network-analysis library. Its main request workflow accepts a route request, correlates locations to graph tiles, computes a path using mode- and time-dependent costs, builds maneuver guidance, and serializes a response. Separate capabilities include graph-tile construction, transit ingestion, matrix and isochrone analysis, elevation sampling, map matching, and tour optimization. The README documents the major module handoffs; sampled source excerpts are partial, so links for unsampled feature implementations are limited to documented ownership.

Main entry points: [`src/tyr/actor.cc`](https://github.com/jl115/valhalla/blob/master/src/tyr/actor.cc) (Request API), [`src/thor/worker.cc`](https://github.com/jl115/valhalla/blob/master/src/thor/worker.cc) (Path algorithms), [`valhalla/baldr/graphtile.h`](https://github.com/jl115/valhalla/blob/master/valhalla/baldr/graphtile.h) (Hierarchical graph tiles), [`src/mjolnir/graphbuilder.cc`](https://github.com/jl115/valhalla/blob/master/src/mjolnir/graphbuilder.cc) (Graph builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Graph data"]
  node_mjolnir["Graph builder<br/>[graphbuilder.cc]"]
  node_transit_ingest["Transit ingestion<br/>[ingest_transit.cc]"]
  node_tiles[("Hierarchical graph tiles<br/>[graphtile.h]")]
end

subgraph group_request["Request handling"]
  node_service["HTTP service"]
  node_tyr["Request API<br/>[actor.cc]"]
  node_parse["Request parsing<br/>[worker.cc]"]
end

subgraph group_analysis["Routing analysis"]
  node_loki["Location search<br/>[worker.cc]"]
  node_costing["Dynamic costing<br/>[dynamiccost.cc]"]
  node_thor["Path algorithms<br/>[worker.cc]"]
  node_matrix["Matrix analysis<br/>[costmatrix.cc]"]
  node_isochrone["Reachability<br/>[isochrone.cc]"]
  node_meili["Map matching<br/>[map_matcher.cc]"]
  node_elevation["Elevation sampling<br/>[sample.cc]"]
  node_optimizer["Tour optimization<br/>[optimizer.cc]"]
end

subgraph group_output["Guidance output"]
  node_odin["Maneuvers<br/>[worker.cc]"]
  node_serializer["Response formatting<br/>[serializers.cc]"]
end

node_osm["OSM data"]
node_gtfs["Transit feeds"]
node_client(("API client"))

node_osm -->|"builds from"| node_mjolnir
node_gtfs -->|"ingests"| node_transit_ingest
node_transit_ingest -->|"adds transit"| node_tiles
node_mjolnir -->|"writes tiles"| node_tiles
node_client -->|"sends request"| node_service
node_service -->|"dispatches"| node_tyr
node_tyr -->|"parses request"| node_parse
node_tyr -->|"correlates locations"| node_loki
node_loki -->|"searches"| node_tiles
node_tyr -->|"requests analysis"| node_thor
node_thor -->|"reads graph"| node_tiles
node_thor -->|"applies costs"| node_costing
node_thor -->|"provides path"| node_odin
node_odin -->|"provides guidance"| node_serializer
node_tyr -->|"formats response"| node_serializer
node_tyr -->|"requests matrix"| node_matrix
node_tyr -->|"requests contours"| node_isochrone
node_tyr -->|"requests matching"| node_meili
node_tyr -->|"requests sampling"| node_elevation
node_tyr -->|"requests optimization"| node_optimizer

click node_mjolnir "https://github.com/jl115/valhalla/blob/master/src/mjolnir/graphbuilder.cc"
click node_transit_ingest "https://github.com/jl115/valhalla/blob/master/src/mjolnir/ingest_transit.cc"
click node_tiles "https://github.com/jl115/valhalla/blob/master/valhalla/baldr/graphtile.h"
click node_service "https://github.com/jl115/valhalla/blob/master/src/valhalla_service.cc"
click node_tyr "https://github.com/jl115/valhalla/blob/master/src/tyr/actor.cc"
click node_parse "https://github.com/jl115/valhalla/blob/master/src/worker.cc"
click node_loki "https://github.com/jl115/valhalla/blob/master/src/loki/worker.cc"
click node_costing "https://github.com/jl115/valhalla/blob/master/src/sif/dynamiccost.cc"
click node_thor "https://github.com/jl115/valhalla/blob/master/src/thor/worker.cc"
click node_matrix "https://github.com/jl115/valhalla/blob/master/src/thor/costmatrix.cc"
click node_isochrone "https://github.com/jl115/valhalla/blob/master/src/thor/isochrone.cc"
click node_meili "https://github.com/jl115/valhalla/blob/master/src/meili/map_matcher.cc"
click node_elevation "https://github.com/jl115/valhalla/blob/master/src/skadi/sample.cc"
click node_optimizer "https://github.com/jl115/valhalla/blob/master/src/thor/optimizer.cc"
click node_odin "https://github.com/jl115/valhalla/blob/master/src/odin/worker.cc"
click node_serializer "https://github.com/jl115/valhalla/blob/master/src/tyr/serializers.cc"

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_mjolnir,node_transit_ingest,node_tiles,node_client toneBlue
class node_service,node_tyr,node_parse toneAmber
class node_loki,node_costing,node_thor,node_matrix,node_isochrone,node_meili,node_elevation,node_optimizer toneMint
class node_odin,node_serializer toneRose
class node_osm,node_gtfs toneIndigo
```

## Components

### Graph data

- [Graph builder](https://github.com/jl115/valhalla/blob/master/src/mjolnir/graphbuilder.cc): `src/mjolnir/graphbuilder.cc`
- [Transit ingestion](https://github.com/jl115/valhalla/blob/master/src/mjolnir/ingest_transit.cc): `src/mjolnir/ingest_transit.cc`
- [Hierarchical graph tiles](https://github.com/jl115/valhalla/blob/master/valhalla/baldr/graphtile.h): `valhalla/baldr/graphtile.h`

### Request handling

- [HTTP service](https://github.com/jl115/valhalla/blob/master/src/valhalla_service.cc): `src/valhalla_service.cc`
- [Request API](https://github.com/jl115/valhalla/blob/master/src/tyr/actor.cc): `src/tyr/actor.cc`
- [Request parsing](https://github.com/jl115/valhalla/blob/master/src/worker.cc): `src/worker.cc`

### Routing analysis

- [Location search](https://github.com/jl115/valhalla/blob/master/src/loki/worker.cc): `src/loki/worker.cc`
- [Dynamic costing](https://github.com/jl115/valhalla/blob/master/src/sif/dynamiccost.cc): `src/sif/dynamiccost.cc`
- [Path algorithms](https://github.com/jl115/valhalla/blob/master/src/thor/worker.cc): `src/thor/worker.cc`
- [Matrix analysis](https://github.com/jl115/valhalla/blob/master/src/thor/costmatrix.cc): `src/thor/costmatrix.cc`
- [Reachability](https://github.com/jl115/valhalla/blob/master/src/thor/isochrone.cc): `src/thor/isochrone.cc`
- [Map matching](https://github.com/jl115/valhalla/blob/master/src/meili/map_matcher.cc): `src/meili/map_matcher.cc`
- [Elevation sampling](https://github.com/jl115/valhalla/blob/master/src/skadi/sample.cc): `src/skadi/sample.cc`
- [Tour optimization](https://github.com/jl115/valhalla/blob/master/src/thor/optimizer.cc): `src/thor/optimizer.cc`

### Guidance output

- [Maneuvers](https://github.com/jl115/valhalla/blob/master/src/odin/worker.cc): `src/odin/worker.cc`
- [Response formatting](https://github.com/jl115/valhalla/blob/master/src/tyr/serializers.cc): `src/tyr/serializers.cc`

### Other components

- **OSM data**
- **Transit feeds**
- **API client**

## Connections

- OSM data → Graph builder: builds from
- Transit feeds → Transit ingestion: ingests
- Transit ingestion → Hierarchical graph tiles: adds transit
- Graph builder → Hierarchical graph tiles: writes tiles
- API client → HTTP service: sends request
- HTTP service → Request API: dispatches
- Request API → Request parsing: parses request
- Request API → Location search: correlates locations
- Location search → Hierarchical graph tiles: searches
- Request API → Path algorithms: requests analysis
- Path algorithms → Hierarchical graph tiles: reads graph
- Path algorithms → Dynamic costing: applies costs
- Path algorithms → Maneuvers: provides path
- Maneuvers → Response formatting: provides guidance
- Request API → Response formatting: formats response
- Request API → Matrix analysis: requests matrix
- Request API → Reachability: requests contours
- Request API → Map matching: requests matching
- Request API → Elevation sampling: requests sampling
- Request API → Tour optimization: requests optimization