# mapotempo/router-api architecture

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

- Interactive diagram: https://gitdiagram.com/mapotempo/router-api
- Repository: https://github.com/mapotempo/router-api

## Overview

##### Project Type and Purpose
- This is a back-end-focused, full-stack routing API service (“Router API”), built in Ruby using the Grape framework, served via Puma/Rack.
- It exposes HTTP endpoints (route, routes, matrix, isoline) that unify multiple routing engines (OSRM, OTP, HERE, etc.) behind a single Swagger-defined interface.
- Clients (JS front-ends or other systems) consume GeoJSON responses for mapping and analysis.

##### File Structure
Top level:
- api/        → Grape endpoint definitions and entity serializers
- wrappers/   → Adapters for external routing engines (osrm, otp, crow, here, here8)
- lib/        → Core helpers (cache manager, earth distance logic)
- config/     → Environment configs, initializers (i18n, REST client)
- docker/ & docker-compose*.yml → Definitions for running OSRM, OTP, Redis, PostGIS, quota, tooling via Docker
- public/     → Static assets and example HTML for client maps (Leaflet)
- router_wrapper.rb → Entry-point orchestrating wrapper selection by area/mode
- test/       → Unit/integration tests for each API piece and wrapper
Look for patterns:
- API layer (Grape) → Business logic (router_wrapper, wrappers) → Entities → GeoJSON formatter
- Microservices via Docker containers for each routing engine and data store.

##### Extract Insights from the README
- Swagger-driven REST API on port 8082.
- Endpoints: /0.1/capability, route.json, routes.json, etc.
- Docker Compose orchestrates:
– osrm service (built with custom scripts)
– otp service (Graph builder scripts)
– PostGIS (landuse data)
– Redis (quota counting, cache build)
- External HTTP-based wrappers (Here, Crow) are invoked via REST client.
- GeoJSON formatting of results.

##### Main Components
a. API Layer (Ruby/Puma/Grape/Rack)
– config.ru, api/**, Rakefile, Gemfile
b. Business Logic Layer
– router_wrapper.rb
– wrappers/ (adapter pattern for each engine)
– lib/cache_manager.rb
c. Data & Cache Stores
– Redis (quota counting, caching build data)
– PostGIS (landuse database)
d. External/Internal Routing Engines
– OSRM container
– OTP container
– External HTTP APIs (HERE, Crow)
e. Presentation Layer (Static assets)
– public/js, public/css (Leaflet, routing-machine)
– Optional Swagger-UI client
f. DevOps / Infrastructure
– Docker Compose orchestrator
– docker-compose.yml, docker-compose-*.yml
– .env for secrets, config/environments for ENV profiles

##### Relationships & Data Flows
1. Client → HTTP request → Puma (Rack)
2. Grape router (api/root.rb → api/v01/*)
3. Parameter normalization → router_wrapper
4. router_wrapper selects wrapper by mode/area → invokes wrapper
- OSRM/OTP via local HTTP inside Docker
- External wrappers via REST client
5. Wrapper returns raw router response → converted into Entities (geo_json_geometry, route_result, metrics, etc.)
6. Entities fed into geojson_formatter → serialized JSON
7. Response sent back through Grape → Client
8. At the same time, wrappers or cache_manager may read/write to:
- Redis (cache, quota counters)

##### Architectural Patterns
- Adapter Pattern (wrappers/) – uniform interface to disparate routing engines
- Presenter/Serializer (Grape Entities) – separate domain objects from HTTP representation
- Service Isolation via Docker – independent containers for each engine, data store, tooling
- Configuration-as-Code – environment-specific Ruby config, .env templates, Docker Compose overrides

[ ] API Tier
– Puma/Rack + Grape
– API modules (api/v01 routes, entities)
– GeoJSON Formatter
[ ] Business Logic
– router_wrapper
– wrappers (OSRM, OTP, HERE, Crow)
– cache_manager
[ ] Data Stores
– Redis (cache, quota)
– PostGIS (landuse)
[ ] Routing Engines
– OSRM (Docker)
– OTP (Docker)
[ ] External Services
– HERE API
– Crow API
[ ] DevOps
– Docker Compose orchestrator
– Build scripts (osrm-build.sh, otp-rebuild.sh)
[ ] Client / Presentation
– Static HTML/JS (Leaflet, Swagger-UI)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Tier
    subgraph "Application Tier"
        subgraph "HTTP/API Layer"
            ClientReq["Client Request"]:::external -->|HTTP| apiLayer["Grape API (Ruby/Puma)"]:::api
            apiLayer --> configRU
            apiLayer --> apiRoot
            apiLayer --> apiApiV01
            apiLayer --> apiV01Api
            apiLayer --> apiV01Base
            apiLayer --> formatter
        end

        subgraph "Business Logic Layer"
            apiLayer --> routerWrapper
            routerWrapper --> wrappersDir
            wrappersDir --> osrmWrapper
            wrappersDir --> otpWrapper
            wrappersDir --> hereWrapper
            wrappersDir --> here8Wrapper
            wrappersDir --> crowWrapper
            wrappersDir --> wrapperBase
            routerWrapper --> cacheManager
            routerWrapper --> earth
        end

        subgraph "Entity & Serializer Layer"
            wrappersDir --> entities
            entities --> formatter
            formatter --> apiLayer
        end

        subgraph "Configuration Layer"
            configRU --> configEnvDev
            configRU --> configEnvTest
            configRU --> configEnvProd
            configRU --> initializerI18n
            configRU --> initializerRest
            configRU --> configAccess
        end

        subgraph "Static Presentation Layer"
            ClientReq --> publicCSS1
            ClientReq --> publicCSS2
            ClientReq --> publicJS
            ClientReq --> publicIso
            ClientReq --> publicRoute
        end

        subgraph "DevOps / Build Tooling"
            apiLayer --> dockerfileAPI
            apiLayer --> envTemplate
            apiLayer --> rakefile
            apiLayer --> gemfile
            apiLayer --> rubocop
        end

        subgraph "Tests"
            apiLayer --> testAPI
            wrappersDir --> testWrappers
            apiLayer --> testHelper
        end
    end

    %% Infrastructure Tier
    subgraph "Infrastructure Tier"
        subgraph "Docker Host"
            dockerCompose --> OSRMContainer
            dockerComposeOSRM --> OSRMContainer
            dockerOSRMDir --> OSRMContainer

            dockerCompose --> OTPContainer
            composeOTP --> OTPContainer
            dockerOTPDir --> OTPContainer

            dockerRedisDir --> Redis
            dockerCompose --> Redis

            dockerCompose --> PostGIS

            composeTools --> DockerComposeTools

            DockerComposeTools --> dockerSnippets
            DockerComposeTools --> composeQuota
        end

        wrappersDir -->|HTTP inside Docker| OSRMContainer
        wrappersDir -->|HTTP inside Docker| OTPContainer
        wrappersDir -->|calls REST| externalAPIs
        wrappersDir --> Redis
        wrappersDir --> PostGIS
    end

    %% External Systems
    externalAPIs --> wrappersDir

    %% Click Events
    click configRU "https://github.com/mapotempo/router-api/blob/dev/config.ru"
    click apiRoot "https://github.com/mapotempo/router-api/blob/dev/api/root.rb"
    click apiApiV01 "https://github.com/mapotempo/router-api/blob/dev/api/api_v01.rb"
    click apiV01Api "https://github.com/mapotempo/router-api/blob/dev/api/v01/api.rb"
    click apiV01Base "https://github.com/mapotempo/router-api/blob/dev/api/v01/api_base.rb"
    click formatter "https://github.com/mapotempo/router-api/blob/dev/api/geojson_formatter.rb"
    click entities "https://github.com/mapotempo/router-api/tree/dev/api/v01/entities"
    click routerWrapper "https://github.com/mapotempo/router-api/blob/dev/router_wrapper.rb"
    click osrmWrapper "https://github.com/mapotempo/router-api/blob/dev/wrappers/osrm.rb"
    click otpWrapper "https://github.com/mapotempo/router-api/blob/dev/wrappers/otp.rb"
    click hereWrapper "https://github.com/mapotempo/router-api/blob/dev/wrappers/here.rb"
    click here8Wrapper "https://github.com/mapotempo/router-api/blob/dev/wrappers/here8.rb"
    click crowWrapper "https://github.com/mapotempo/router-api/blob/dev/wrappers/crow.rb"
    click wrapperBase "https://github.com/mapotempo/router-api/blob/dev/wrappers/wrapper.rb"
    click cacheManager "https://github.com/mapotempo/router-api/blob/dev/lib/cache_manager.rb"
    click earth "https://github.com/mapotempo/router-api/blob/dev/lib/earth.rb"
    click configEnvDev "https://github.com/mapotempo/router-api/blob/dev/config/environments/development.rb"
    click configEnvTest "https://github.com/mapotempo/router-api/blob/dev/config/environments/test.rb"
    click configEnvProd "https://github.com/mapotempo/router-api/blob/dev/config/environments/production.rb"
    click initializerI18n "https://github.com/mapotempo/router-api/blob/dev/config/initializers/i18n.rb"
    click initializerRest "https://github.com/mapotempo/router-api/blob/dev/config/initializers/rest-client.rb"
    click configAccess "https://github.com/mapotempo/router-api/blob/dev/config/access.rb"
    click publicCSS1 "https://github.com/mapotempo/router-api/blob/dev/public/css/leaflet-routing-machine.css"
    click publicCSS2 "https://github.com/mapotempo/router-api/blob/dev/public/css/router.css"
    click publicJS "https://github.com/mapotempo/router-api/tree/dev/public/js"
    click publicIso "https://github.com/mapotempo/router-api/blob/dev/public/isoline.html.erb"
    click publicRoute "https://github.com/mapotempo/router-api/blob/dev/public/route.html.erb"
    click dockerCompose "https://github.com/mapotempo/router-api/blob/dev/docker-compose.yml"
    click composeOSRM "https://github.com/mapotempo/router-api/blob/dev/docker-compose-osrm.yml"
    click composeOTP "https://github.com/mapotempo/router-api/blob/dev/docker-compose-otp.yml"
    click composeQuota "https://github.com/mapotempo/router-api/blob/dev/docker-compose-quota.yml"
    click composeTools "https://github.com/mapotempo/router-api/blob/dev/docker-compose-tools.yml"
    click dockerOSRMDir "https://github.com/mapotempo/router-api/tree/dev/docker/osrm"
    click dockerOTPDir "https://github.com/mapotempo/router-api/tree/dev/docker/otp"
    click dockerRedisDir "https://github.com/mapotempo/router-api/tree/dev/docker/redis-count"
    click dockerSnippets "https://github.com/mapotempo/router-api/tree/dev/docker/snippets"
    click dockerfileAPI "https://github.com/mapotempo/router-api/tree/dev/Dockerfile"
    click envTemplate "https://github.com/mapotempo/router-api/blob/dev/.env.template"
    click rakefile "https://github.com/mapotempo/router-api/tree/dev/Rakefile"
    click gemfile "https://github.com/mapotempo/router-api/blob/dev/Gemfile/Gemfile.lock"
    click rubocop "https://github.com/mapotempo/router-api/blob/dev/.rubocop.yml"
    click testAPI "https://github.com/mapotempo/router-api/tree/dev/test/api"
    click testWrappers "https://github.com/mapotempo/router-api/tree/dev/test/wrappers"
    click testHelper "https://github.com/mapotempo/router-api/blob/dev/test/test_helper.rb"

    %% Styles
    classDef api fill:#B3C7E6,stroke:#333,stroke-width:1px
    classDef logic fill:#A6CEE3,stroke:#333,stroke-width:1px
    classDef entity fill:#1F78B4,stroke:#333,stroke-width:1px
    classDef config fill:#FB9A99,stroke:#333,stroke-width:1px
    classDef presentation fill:#FDBF6F,stroke:#333,stroke-width:1px
    classDef devops fill:#CAB2D6,stroke:#333,stroke-width:1px
    classDef test fill:#B2DF8A,stroke:#333,stroke-width:1px
    classDef external fill:#DDDDDD,stroke:#333,stroke-width:1px
    classDef engine fill:#FF7F00,stroke:#333,stroke-width:1px
    classDef data fill:#33A02C,stroke:#333,stroke-width:1px
    classDef devopsInfra fill:#CAB2D6,stroke:#333,stroke-width:1px
```
