# project-osrm/osrm-backend architecture

> Architecture diagram of the GitHub repository project-osrm/osrm-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/project-osrm/osrm-backend
- Repository: https://github.com/project-osrm/osrm-backend

## Overview

##### Project type and purpose
- This is OSRM-backend, a high-performance C++ routing engine on OpenStreetMap data.
- It provides both batch preprocessing tools (extract, partition, customize) and a runtime HTTP server (osrm-routed), plus C++ and Node.js library interfaces.

##### File structure
- Top-level “src” and “include” house the C++ modules:
- src/extractor + include/extractor → OSM data parsing & graph building
- src/contractor, src/partitioner, src/customize → CH/MLD pipelines
- src/engine + include/engine → core routing, map-matching, guidance
- src/server + include/server → HTTP parsing, services (route, nearest, match, table, trip, tile)
- src/updater → timezone/GPS data updaters
- lib/binding* & src/nodejs → Node.js bindings
- “docker/” contains Dockerfiles packaging backend & frontend
- “profiles/” stores Lua profiles customizing routing behaviors
- “tests/”, “features/”, “unit_tests/” cover BDD, unit, fuzz tests
- “third_party/” has FlatBuffers, fmt, RapidJSON, libosmium, protozero, vtzero, etc.

##### README for additional insights
- Services: Nearest, Route, Table, Match, Trip, Tile – each backed by a plugin in engine/plugins
- Two preprocessing pipelines: Contraction Hierarchies (CH) vs Multi-Level Dijkstra (MLD)
- Three interfaces: HTTP API (osrm-routed), C++ libosrm, Node.js package
- Build system: CMake + optional Conan; Node.js via npm; Docker images provided.

##### Elements
- Clear labels per component (e.g., “osrm-extract”, “DataFacade”, “route_service”)
- Batch tools (grey rectangles)
- Server layer (green cloud)
- Library bindings (purple)
- External clients (yellow)

##### Be very detailed—capture all essential elements
- Storage formats (.osrm files, shared memory) explicitly
- Lua profiles as input to extract/customize
- CI/test layer off to the side (scripts/, features/, unit_tests/) to show coverage and validation

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Batch Preprocessing"
        direction TB
        ExtractTool["osrm-extract"]:::batch
        PartTool["osrm-partition"]:::batch
        CustTool["osrm-customize"]:::batch
        ContractTool["osrm-contract"]:::batch
        Profiles["Lua profiles"]:::config
    end

    subgraph "Storage Layer"
        Storage[".osrm files / shared memory"]:::storage
    end

    subgraph "Engine Core"
        direction TB
        DataFacade["DataFacade"]:::engine
        Routing["Routing Algorithms (CH & MLD)"]:::engine
        Guidance["Guidance Pipeline"]:::engine
        MapMatch["Map-Matching & Trip"]:::engine
        Plugins["Service Plugins"]:::engine
    end

    subgraph "HTTP Server"
        direction TB
        ServerCore["osrm-routed Server"]:::server
        Handlers["Service Handlers (route, match, table, tile, trip)"]:::server
    end

    subgraph "Library Interfaces"
        direction TB
        CppLib["libosrm C++ API"]:::lib
        NodeBind["Node.js Bindings"]:::lib
    end

    subgraph "External Clients"
        direction TB
        HTTPClient["HTTP Clients (curl, apps)"]:::client
        InProc["In-Process Lib Calls"]:::client
    end

    subgraph "Build & CI"
        direction TB
        Build["CMake / Conan / Docker"]:::ci
        Tests["Tests & BDD"]:::ci
    end

    Profiles -->|drives| ExtractTool
    ExtractTool -->|graph data| PartTool
    PartTool -->|weights| CustTool
    ContractTool -->|contracted graph| Storage
    CustTool -->|customized data| Storage
    PartTool -->|partitioned data| Storage
    ExtractTool -->|raw graph| Storage

    Storage -->|loaded via| DataFacade
    DataFacade -->|provides data| Routing
    DataFacade --> Guidance
    DataFacade --> MapMatch
    Routing -->|used by| Plugins
    Guidance -->|used by| Plugins
    MapMatch -->|used by| Plugins

    Plugins -->|plugin registration| ServerCore
    ServerCore -->|routes requests| Handlers
    Handlers -->|responses| HTTPClient

    HTTPClient -->|HTTP| ServerCore
    InProc -->|direct calls| CppLib
    InProc -->|direct calls| NodeBind

    CppLib -->|uses| Plugins
    NodeBind -->|wraps| CppLib

    Build -->|build scripts| ExtractTool
    Build --> PartTool
    Build --> CustTool
    Build --> ContractTool
    Build --> CppLib
    Build --> NodeBind

    Tests -->|validate| ExtractTool
    Tests --> PartTool
    Tests --> CustTool
    Tests --> ContractTool
    Tests --> Plugins
    Tests --> ServerCore

    click ExtractTool "https://github.com/project-osrm/osrm-backend/blob/master/src/tools/extract.cpp"
    click PartTool "https://github.com/project-osrm/osrm-backend/blob/master/src/tools/partition.cpp"
    click CustTool "https://github.com/project-osrm/osrm-backend/blob/master/src/tools/customize.cpp"
    click ContractTool "https://github.com/project-osrm/osrm-backend/blob/master/src/tools/contract.cpp"
    click Storage "https://github.com/project-osrm/osrm-backend/blob/master/src/storage/storage.cpp"
    click DataFacade "https://github.com/project-osrm/osrm-backend/tree/master/include/engine/datafacade/"
    click Routing "https://github.com/project-osrm/osrm-backend/tree/master/include/engine/routing_algorithms/"
    click Guidance "https://github.com/project-osrm/osrm-backend/tree/master/include/engine/guidance/"
    click MapMatch "https://github.com/project-osrm/osrm-backend/tree/master/include/engine/map_matching/"
    click Plugins "https://github.com/project-osrm/osrm-backend/blob/master/include/engine/plugins/route.hpp"
    click ServerCore "https://github.com/project-osrm/osrm-backend/blob/master/src/server/server.hpp"
    click Handlers "https://github.com/project-osrm/osrm-backend/blob/master/src/server/service/route_service.cpp"
    click CppLib "https://github.com/project-osrm/osrm-backend/blob/master/src/osrm/osrm.cpp"
    click NodeBind "https://github.com/project-osrm/osrm-backend/blob/master/src/nodejs/node_osrm.cpp"
    click Build "https://github.com/project-osrm/osrm-backend/blob/master/CMakeLists.txt"
    click Tests "https://github.com/project-osrm/osrm-backend/tree/master/unit_tests/"

    classDef batch fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef storage fill:#FFF0F5,stroke:#000,stroke-width:1px
    classDef engine fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef server fill:#98FB98,stroke:#000,stroke-width:1px
    classDef lib fill:#DDA0DD,stroke:#000,stroke-width:1px
    classDef client fill:#FFFFE0,stroke:#000,stroke-width:1px
    classDef config fill:#F0E68C,stroke:#000,stroke-width:1px
    classDef ci fill:#E6E6FA,stroke:#000,stroke-width:1px
```
