# ziguss-ds/osrm-backend architecture

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

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

## Overview

##### Main components
- Preprocessing / Data Extraction Pipeline: This involves the “extractor”, “contractor”, “partitioner” (for MLD) and “customizer” modules under both the “src” and “include” directories. These modules transform raw OSM data into internal graph representations, perform edge expansion and preprocess the network for fast query times.
- Core Routing Engine: Found under “src/engine”, “src/contractor”, “src/guidance”, “src/partitioner” and related directories. It implements various routing algorithms (shortest path, map matching, route leg assembly, etc.) and includes the datafacade (which abstracts memory mapped or shared data) that feeds the core logic.
- HTTP API Server / Service Layer: The “src/server” directory contains the HTTP server implementation and the API definitions (including service handlers, parameter parsing, and connection management) for processing requests such as routing queries.
- Language Bindings & Node.js Wrapper: The “lib/binding”, “src/nodejs”, and “include/nodejs” directories hold the Node.js integration components, which expose a read-only interface to the routing engine.
- External Interfaces & Profiles: The “profiles” directory includes Lua scripts that define vehicle profiles (car, bicycle, foot, etc.) and various customization hooks, while Docker-related files and the “docker” directory support containerization and deployment.
- Testing & Documentation: Numerous “unit_tests” and “test” directories indicate an extensive test suite. In addition, documentation under “docs” and “README.md” explain API endpoints, usage patterns, and guidelines for data processing pipelines.

##### Relationships and interactions
- Data Flow: Raw OSM data is input into the extraction module. The extractor generates an internal graph representation that is then passed through the contractor, partitioner, and customizer steps to preprocess and optimize the network for routing.
- Core Engine Interaction: The processed data is loaded into the engine through the datafacade. Routing algorithms (found in “src/engine/routing_algorithms”) operate on this data to respond to route, match, nearest, trip, table, and tile queries.
- API Layer: The HTTP server (osrm-routed) exposes these functionalities via RESTful endpoints. Internally, it delegates to service layers defined in “src/server/service” which communicate with the core engine.
- Language Bindings: The Node.js bindings wrap the core C++ library functions to allow JavaScript applications to interface with OSRM. They use the same underlying engine to answer queries.

##### Architectural patterns and design principles
- Layered Architecture / Modular Design: The project cleanly separates data ingestion, preprocessing, core engine logic, and external API exposure. Each set of functionalities is encapsulated in its own module or directory.
- Abstraction: The datafacade abstracts the differences between memory and file-based data. There is clear use of interface boundaries between routing algorithms, customization logic, and API request handling.
- Extensibility via Profiles: The use of Lua profiles allows for customizable vehicle and routing characteristics and acts as extension points.
- Testing & CI/CD: The integration of GitHub workflows and a comprehensive test suite indicates emphasis on continuous integration and code reliability.

##### Relevant technologies, frameworks, and integrations
- C++ with CMake as the build system and use of modern C++ libraries (Boost, TBB, Lua, etc.).
- Docker for containerized deployment (with Dockerfiles and container registry support).
- Node.js for language bindings, with a dedicated “package.json”, and pre-built binaries where appropriate.
- External libraries such as FlatBuffers (included in “third_party”) for efficient API communication, and several third-party dependencies for JSON parsing (RapidJSON) and others.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A("Raw OSM Data") 
    B("Data Extraction & Preprocessing"):::offline
    C("Core Routing Engine"):::engine
    D("HTTP API Service"):::api
    E("Node.js Bindings"):::nodejs
    F("External Interfaces & Profiles"):::external
    G("Testing & Documentation"):::testing

    A --> B
    B --> C
    C --> D
    C --> E
    C --> F
    F --> G

    click B "https://github.com/ziguss-ds/osrm-backend/tree/master/src/extractor"
    click B "https://github.com/ziguss-ds/osrm-backend/tree/master/src/contractor"
    click B "https://github.com/ziguss-ds/osrm-backend/tree/master/src/customize"
    click B "https://github.com/ziguss-ds/osrm-backend/tree/master/src/partitioner"
    click B "https://github.com/ziguss-ds/osrm-backend/tree/master/include/extractor"
    click B "https://github.com/ziguss-ds/osrm-backend/tree/master/include/contractor"
    click B "https://github.com/ziguss-ds/osrm-backend/tree/master/include/customizer"
    click B "https://github.com/ziguss-ds/osrm-backend/tree/master/include/partitioner"

    click C "https://github.com/ziguss-ds/osrm-backend/tree/master/src/engine"
    click C "https://github.com/ziguss-ds/osrm-backend/tree/master/src/osrm"
    click C "https://github.com/ziguss-ds/osrm-backend/tree/master/include/engine"

    click D "https://github.com/ziguss-ds/osrm-backend/tree/master/src/server"
    click D "https://github.com/ziguss-ds/osrm-backend/tree/master/include/server"

    click E "https://github.com/ziguss-ds/osrm-backend/tree/master/src/nodejs"
    click E "https://github.com/ziguss-ds/osrm-backend/tree/master/lib/binding"
    click E "https://github.com/ziguss-ds/osrm-backend/tree/master/include/nodejs"

    click F "https://github.com/ziguss-ds/osrm-backend/tree/master/profiles"
    click F "https://github.com/ziguss-ds/osrm-backend/tree/master/docker"
    click F "https://github.com/ziguss-ds/osrm-backend/tree/master/docs"

    click G "https://github.com/ziguss-ds/osrm-backend/tree/master/unit_tests"
    click G "https://github.com/ziguss-ds/osrm-backend/tree/master/test"
    click G "https://github.com/ziguss-ds/osrm-backend/tree/master/docs"

    classDef offline fill:#f9d6a5,stroke:#333,stroke-width:2px
    classDef engine fill:#a5d6f9,stroke:#333,stroke-width:2px
    classDef api fill:#d6a5f9,stroke:#333,stroke-width:2px
    classDef nodejs fill:#a5f9d6,stroke:#333,stroke-width:2px
    classDef external fill:#f9a5d6,stroke:#333,stroke-width:2px
    classDef testing fill:#f9f1a5,stroke:#333,stroke-width:2px
```
