# pelias/api architecture

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

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

## Overview

##### Project Type and Purpose
- This is a Node.js/Express API server (Pelias API) providing HTTP endpoints for geocoding and reverse-geocoding.
- It receives REST requests (autocomplete, search, reverse, place), processes them via a modular pipeline, queries Elasticsearch, and enriches results by calling other Pelias microservices (libpostal, placeholder, pip, interpolation).
- It’s an open-source search engine that returns GeoJSON results.

##### File Structure Analysis
- Top-level files:
- app.js / index.js – Express app entry-point
- bin/ – startup scripts (generate docs, start server, register unit tests)
- Dockerfile / .github – CI and container configuration
- Core directories:
- routes/ – defines API routes (v1 endpoints, default routes)
- middleware/ – Express middleware chain (CORS, logging, parsing, normalization, scoring, trimming, JSONP, error handling)
- controller/ – orchestrates per-endpoint logic, applies predicates, transforms Markdown, calls query builder
- query/ – builds Elasticsearch query bodies, includes parsers and default parameter files, view helpers
- service/ – high-level operations: configuration discovery, multi-get, search wrapper
- sanitizer/ – input validation and sanitization for each endpoint
- helper/ – utility functions (type mapping, geojson conversion, logging, unicode)
- test/ – unit tests and functional (CIAO) tests with fixtures
- Configuration:
- Uses pelias-config via environment variable or pelias.json
- package.json scripts (start, test, ciao, docs, coverage, config)

a. Clients and Load Balancers
- External HTTP clients (web/mobile/other servers)
- Optional: reverse proxy/load balancer (NGINX, HAProxy)
b. API Server (Node.js / Express)
- Entry-point: app.js initializes Express, mounts routes
- Routes layer: routes/v1.js, default.js define endpoint paths
- Middleware pipeline: every request passes sequential middleware modules (cors → access_log → parseBBox → confidenceScore → … → sendJSON → 404/500 handlers)
- Controllers: one per endpoint (search.js, autocomplete.js, reverse.js, place.js, structured_libpostal.js, coarse_reverse.js)
- Sanitizer: input validation modules invoked before controllers
- Query builder: query/*.js builds Elasticsearch DSL based on sanitized input
- Service layer: service/search.js, service/mget.js abstracts calls to Elasticsearch; service/configurations for auto-discovery of sources/layers
- Microservice clients: via service/configurations or helper modules, HTTP calls to Pelias services:
– libpostal (address parser)
– placeholder (fill missing address components)
– pip-service (point-in-polygon lookup for administrative hierarchies)
– interpolation (street number interpolation)
- Elasticsearch cluster: stores and indexes place data
- Response formatter: helper/geojsonify* builds GeoJSON output
c. External Dependencies
- Elasticsearch cluster (could be a cluster of nodes behind a load balancer)
- Pelias microservices (libpostal, placeholder, pip, interpolation)
- Optional: Monitoring/logging services

##### Relationships and Data Flow
1. HTTP Client → Load Balancer → API Server (app.js)
2. API Server:
- routes → middleware sequence (authentication, logging, validation, normalization, scoring, dedupe, trimming)
- controller (decide which query to run) → sanitizer (validate input) → query builder (compose ES DSL)
- service layer → Elasticsearch (HTTP JSON)
- optionally call external Pelias microservices (HTTP JSON)
- service layer merges results → controller formats → middleware sendJSON → HTTP response
3. API Server logs and error handlers manage failures and diagnostics

##### Architectural Patterns and Design Principles
- Layered architecture: clear separation (routes → middleware → controllers → services → datastore)
- Modular, pluggable middleware for cross-cutting concerns
- Predicate-based controllers (controller/predicates) drive conditional logic
- Dependency inversion: service/configurations abstract external service URLs and retries
- Auto-discovery pattern for dynamic configuration of Elasticsearch sources and layers

##### Technologies and Frameworks
- Node.js and Express.js for server framework
- Elasticsearch (RESTful JSON API) as primary datastore
- Pelias microservices: libpostal, placeholder, pip, interpolation (HTTP services)
- Docker for containerization and Dockerfile in repo
- pelias-config for centralized configuration management
- Mocha/CoffeeScript/CIAO for unit and HTTP functional testing

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients and Load Balancer
    Client["External HTTP Client"]:::client
    LB["Load Balancer / Reverse Proxy"]:::client
    Client -->|"HTTP Request"| LB

    %% API Server Entry
    subgraph "API Server (Node.js / Express)"
        direction TB

        subgraph "Entry Point"
            direction TB
            App["app.js"]:::api
            Index["index.js"]:::api
        end

        subgraph "Routes Layer"
            direction TB
            V1["routes/v1.js"]:::api
            DefaultRoutes["routes/default.js"]:::api
        end

        subgraph "Middleware Pipeline"
            direction TB
            CORS["cors.js"]:::middleware
            AccessLog["access_log.js"]:::middleware
            ParseBBox["parseBBox.js"]:::middleware
            Confidence["confidenceScore.js"]:::middleware
            JSONP["jsonp.js"]:::middleware
            SendJSON["sendJSON.js"]:::middleware
            Handler404["404.js"]:::middleware
            Handler500["500.js"]:::middleware
        end

        subgraph "Controllers"
            direction TB
            SearchCtrl["controller/search.js"]:::controller
            CoarseReverse["controller/coarse_reverse.js"]:::controller
            StructuredLibpostal["controller/structured_libpostal.js"]:::controller
            PlaceCtrl["controller/place.js"]:::controller
            LibpostalCtrl["controller/libpostal.js"]:::controller
            PlaceholderCtrl["controller/placeholder.js"]:::controller
            StatusCtrl["controller/status.js"]:::controller
        end

        subgraph "Sanitizer"
            direction TB
            SanitizeAll["sanitizeAll.js"]:::sanitizer
            SearchSan["search.js"]:::sanitizer
            AutocompleteSan["autocomplete.js"]:::sanitizer
            ReverseSan["reverse.js"]:::sanitizer
            PlaceSan["place.js"]:::sanitizer
            StructuredSan["structured_geocoding.js"]:::sanitizer
        end

        subgraph "Query Builders"
            direction TB
            QuerySearch["query/search.js"]:::query
            QueryAuto["query/autocomplete.js"]:::query
            QueryReverse["query/reverse.js"]:::query
            QueryStruct["query/structured_geocoding.js"]:::query
        end

        subgraph "Service Layer"
            direction TB
            ServiceSearch["service/search.js"]:::service
            ServiceMget["service/mget.js"]:::service
            ConfigLibpostal["Libpostal.js"]:::service
            ConfigPlaceholder["PlaceHolder.js"]:::service
            ConfigPIP["PointInPolygon.js"]:::service
            ConfigInterp["Interpolation.js"]:::service
        end

        subgraph "Helpers"
            direction TB
            GeoJSONify["geojsonify.js"]:::helper
            DecodeGID["decode_gid.js"]:::helper
            TypeMap["TypeMapping.js"]:::helper
            LoggingHelper["logging.js"]:::helper
        end
    end

    %% External Services and Datastore
    subgraph "External Dependencies"
        direction TB
        LibpostalMS["libpostal"]:::external
        PlaceholderMS["placeholder"]:::external
        PIPMS["pip-service"]:::external
        InterpMS["interpolation"]:::external
    end

    ES["Elasticsearch Cluster"]:::datastore

    %% Data Flow
    LB -->|"Route to app.js"| App
    App -->|"mount routes"| V1
    V1 --> CORS
    CORS --> AccessLog
    AccessLog --> ParseBBox
    ParseBBox --> Confidence
    Confidence --> JSONP
    JSONP --> SearchCtrl
    SearchCtrl --> SanitizeAll
    SanitizeAll --> QuerySearch
    QuerySearch --> ServiceSearch
    ServiceSearch --> ES
    ServiceSearch --> ConfigLibpostal
    ServiceSearch --> ConfigPlaceholder
    ServiceSearch --> ConfigPIP
    ServiceSearch --> ConfigInterp
    ConfigLibpostal --> LibpostalMS
    ConfigPlaceholder --> PlaceholderMS
    ConfigPIP --> PIPMS
    ConfigInterp --> InterpMS
    ES --> ServiceSearch
    ServiceSearch --> GeoJSONify
    GeoJSONify --> SendJSON
    SendJSON -->|"HTTP Response"| LB

    %% Click Events
    click App "https://github.com/pelias/api/blob/master//app.js"
    click Index "https://github.com/pelias/api/blob/master//index.js"
    click V1 "https://github.com/pelias/api/blob/master//routes/v1.js"
    click DefaultRoutes "https://github.com/pelias/api/blob/master//routes/default.js"
    click CORS "https://github.com/pelias/api/blob/master//middleware/cors.js"
    click AccessLog "https://github.com/pelias/api/blob/master//middleware/access_log.js"
    click ParseBBox "https://github.com/pelias/api/blob/master//middleware/parseBBox.js"
    click Confidence "https://github.com/pelias/api/blob/master//middleware/confidenceScore.js"
    click JSONP "https://github.com/pelias/api/blob/master//middleware/jsonp.js"
    click SendJSON "https://github.com/pelias/api/blob/master//middleware/sendJSON.js"
    click Handler404 "https://github.com/pelias/api/blob/master//middleware/404.js"
    click Handler500 "https://github.com/pelias/api/blob/master//middleware/500.js"
    click SearchCtrl "https://github.com/pelias/api/blob/master//controller/search.js"
    click CoarseReverse "https://github.com/pelias/api/blob/master//controller/coarse_reverse.js"
    click StructuredLibpostal "https://github.com/pelias/api/blob/master//controller/structured_libpostal.js"
    click PlaceCtrl "https://github.com/pelias/api/blob/master//controller/place.js"
    click LibpostalCtrl "https://github.com/pelias/api/blob/master//controller/libpostal.js"
    click PlaceholderCtrl "https://github.com/pelias/api/blob/master//controller/placeholder.js"
    click StatusCtrl "https://github.com/pelias/api/blob/master//controller/status.js"
    click SanitizeAll "https://github.com/pelias/api/blob/master//sanitizer/sanitizeAll.js"
    click SearchSan "https://github.com/pelias/api/blob/master//sanitizer/search.js"
    click AutocompleteSan "https://github.com/pelias/api/blob/master//sanitizer/autocomplete.js"
    click ReverseSan "https://github.com/pelias/api/blob/master//sanitizer/reverse.js"
    click PlaceSan "https://github.com/pelias/api/blob/master//sanitizer/place.js"
    click StructuredSan "https://github.com/pelias/api/blob/master//sanitizer/structured_geocoding.js"
    click QuerySearch "https://github.com/pelias/api/blob/master//query/search.js"
    click QueryAuto "https://github.com/pelias/api/blob/master//query/autocomplete.js"
    click QueryReverse "https://github.com/pelias/api/blob/master//query/reverse.js"
    click QueryStruct "https://github.com/pelias/api/blob/master//query/structured_geocoding.js"
    click ServiceSearch "https://github.com/pelias/api/blob/master//service/search.js"
    click ServiceMget "https://github.com/pelias/api/blob/master//service/mget.js"
    click ConfigLibpostal "https://github.com/pelias/api/blob/master//service/configurations/Libpostal.js"
    click ConfigPlaceholder "https://github.com/pelias/api/blob/master//service/configurations/PlaceHolder.js"
    click ConfigPIP "https://github.com/pelias/api/blob/master//service/configurations/PointInPolygon.js"
    click ConfigInterp "https://github.com/pelias/api/blob/master//service/configurations/Interpolation.js"
    click GeoJSONify "https://github.com/pelias/api/blob/master//helper/geojsonify.js"
    click DecodeGID "https://github.com/pelias/api/blob/master//helper/decode_gid.js"
    click TypeMap "https://github.com/pelias/api/blob/master//helper/TypeMapping.js"
    click LoggingHelper "https://github.com/pelias/api/blob/master//helper/logging.js"

    %% Styles
    classDef client fill:#E0F7FA,stroke:#006064,stroke-width:1px,shape:cloud
    classDef api fill:#BBDEFB,stroke:#1E88E5,stroke-width:1px
    classDef middleware fill:#FFF9C4,stroke:#FBC02D,stroke-width:1px
    classDef controller fill:#FFE0B2,stroke:#FB8C00,stroke-width:1px
    classDef sanitizer fill:#E1BEE7,stroke:#8E24AA,stroke-width:1px
    classDef query fill:#C8E6C9,stroke:#43A047,stroke-width:1px
    classDef service fill:#B2EBF2,stroke:#0097A7,stroke-width:1px
    classDef helper fill:#ECEFF1,stroke:#546E7A,stroke-width:1px
    classDef external fill:#C5E1A5,stroke:#558B2F,stroke-width:1px,shape:roundrect
    classDef datastore fill:#FFCCBC,stroke:#D84315,stroke-width:1px,shape:cylinder
```
