How mapotempo/router-api works
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)