# osm-search/nominatim architecture

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

- Interactive diagram: https://gitdiagram.com/osm-search/nominatim
- Repository: https://github.com/osm-search/nominatim

## Overview

##### Main components
- API/Web Server Layer – Found in the src/nominatim_api directory. This layer contains submodules such as “search”, “lookup”, “reverse”, “query_preprocessing”, and “server” implementations (both Falcon‑based and Starlette‑based). They are the entry points for client requests.
- Database Layer – Represented by src/nominatim_db, along with embedded SQL files (in lib-sql) and Lua scripts (in lib-lua) that handle functions, indexing, triggers, and extension points. This layer deals with database connection, query pooling, SQL preprocessor, indexing & tokenization (look in src/nominatim_db/indexer and tokenizer).
- Data Import and Indexing Tools – These include the command line commands (under src/nominatim_db/clicmd and src/nominatim_db/tools) as well as various scripts (Makefile, Vagrantfile, and contents in docs/* concerning installation, update, and migration). They are used to import OSM data, build indexes, and keep the database up-to-date.
- Configuration & Customization – Many configuration files are scattered through directories (e.g., settings/ for country names and ICU rules, .flake8, .mypy.ini, and various docs). This layer also includes Lua theme scripts (in lib-lua/themes/nominatim) used for customizing OSM2PGSQL import procedures.

##### Relationships and interactions
- Client Requests and API Layer: A client (or web front end) sends HTTP requests which are received by one of the API server implementations (either Falcon or Starlette). Highlight how the “server/asgi_adaptor.py” routes incoming requests to the appropriate modules in the “search”, “lookup”, or “reverse” directories.
- Data Import and Indexing Workflows: When performing an import (via the CLI “nominatim import”) or refresh, commands trigger functions in src/nominatim_db/clicmd and then execute the necessary indexing and tokenization routines (located in the “indexer” and “tokenizer” directories). This process feeds new or updated OpenStreetMap data into the database.
- Utility and Deployment: Separately, include infrastructure components such as Vagrant configurations (for test or development environments), GitHub workflows (for CI/CD), and packaging scripts. These support installation, testing, and deployment rather than the runtime geocoding process.

##### Important architectural patterns and design principles
- Separation of Concerns: Notice how the project separates API request handling (nominatim_api) from database management and data import (nominatim_db). This emphasizes modularity.
- Extensibility: The use of Lua for configuration and SQL customization, as well as the clear separation of packaging for API and DB components, suggests that the system is built to be extended and customized.
- Interoperability: The API layer supports different server frameworks (Falcon and Starlette), enabling flexibility in deployment.

##### Technologies, frameworks, or libraries
- Python (CLI tools, API implementations, database connectors)
- PostgreSQL (the underlying database, with its SQL configuration and indices)
- Falcon / Starlette (for API server implementations)
- Uvicorn (as demonstrated in the installation steps for running the server)
- SQL and Lua (for database functions and OSM2PGSQL customizations)

##### Additional details to capture
- Areas of extensibility such as areas for custom tokenizer configuration and Lua themes.
- Testing pipelines (noting directories such as test/ and GitHub workflows) to show the integrated CI/CD mechanism.
- Components with brief notes on responsibilities (e.g., “Handles normalization and parsing of search queries” near the query_preprocessing module).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    A["Client/Web Frontend"]:::client

    %% API/Web Server Layer
    subgraph "API/Web Server Layer"
        B["API Base"]:::api
        C["Server (Falcon/Starlette)"]:::api
        D["Search Module"]:::api
        E["Query Preprocessing Module"]:::api
        B --> C
        B --> D
        B --> E
    end

    %% Database Layer
    subgraph "Database Layer"
        F["Database (PostgreSQL)"]:::db
        G["Indexer"]:::db
        H["Tokenizer"]:::db
        G --> F
        H --> F
    end

    %% Data Import & Indexing Tools
    subgraph "Data Import & Indexing Tools"
        I["CLI Import"]:::tools
        J["Import Tools"]:::tools
        I --> G
        J --> G
    end

    %% Configuration & Customization
    subgraph "Configuration & Customization"
        K["Settings"]:::config
        L["Lua Themes"]:::config
    end

    %% Packaging & Deployment
    subgraph "Packaging & Deployment"
        M["Packaging API"]:::pack
        N["Packaging DB"]:::pack
        O["CI/CD Workflows"]:::pack
        P["Vagrant"]:::pack
    end

    %% Connections between layers
    A -->|"HTTP_Request"| B
    C -->|"Routes_queries"| F

    %% Styles
    classDef client fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef api fill:#ccffcc,stroke:#006600,stroke-width:2px;
    classDef db fill:#cce5ff,stroke:#003399,stroke-width:2px;
    classDef tools fill:#ffffcc,stroke:#999900,stroke-width:2px;
    classDef config fill:#e6ccff,stroke:#6600cc,stroke-width:2px;
    classDef pack fill:#ffd9b3,stroke:#cc6600,stroke-width:2px;

    %% Click Events for API/Web Server Layer
    click B "https://github.com/osm-search/nominatim/tree/master/src/nominatim_api"
    click C "https://github.com/osm-search/nominatim/tree/master/src/nominatim_api/server"
    click D "https://github.com/osm-search/nominatim/tree/master/src/nominatim_api/search"
    click E "https://github.com/osm-search/nominatim/tree/master/src/nominatim_api/query_preprocessing"

    %% Click Events for Database Layer
    click F "https://github.com/osm-search/nominatim/tree/master/src/nominatim_db"
    click G "https://github.com/osm-search/nominatim/tree/master/src/nominatim_db/indexer"
    click H "https://github.com/osm-search/nominatim/tree/master/src/nominatim_db/tokenizer"

    %% Click Events for Data Import and Indexing Tools
    click I "https://github.com/osm-search/nominatim/tree/master/src/nominatim_db/clicmd"
    click J "https://github.com/osm-search/nominatim/tree/master/src/nominatim_db/tools"

    %% Click Events for Configuration & Customization
    click K "https://github.com/osm-search/nominatim/tree/master/settings"
    click L "https://github.com/osm-search/nominatim/tree/master/lib-lua/themes/nominatim"

    %% Click Events for Packaging & Deployment
    click M "https://github.com/osm-search/nominatim/tree/master/packaging/nominatim-api"
    click N "https://github.com/osm-search/nominatim/tree/master/packaging/nominatim-db"
    click O "https://github.com/osm-search/nominatim/tree/master/.github/workflows"
    click P "https://github.com/osm-search/nominatim/tree/master/Vagrantfile"
```
