# komoot/photon architecture

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

- Interactive diagram: https://gitdiagram.com/komoot/photon
- Repository: https://github.com/komoot/photon

## Overview

Based on our analysis of the file tree and README content, this project is an open source geocoder built around OpenStreetMap data. It features two primary implementations, one that uses an embedded Elasticsearch instance (in app/es_embedded) and an experimental variant built against OpenSearch (in app/opensearch). In addition, there is a traditional Photon core (in src/) that handles query processing, data import from Nominatim, and REST API endpoints for search and reverse geocoding. There is also a website directory providing a front-end demo and integration with the leaflet plugin.

##### Main Components
- Photon API Server: Represent the core Java application (from src/) handling HTTP requests. Label submodules that handle search, reverse geocoding, structured search, and various query parameters.
- Indexing/Search Engine Integration:
- Embedded Elasticsearch Module: Represent the es_embedded module which has its own Java packages defining index settings, mappings, document converters, and updaters.
- OpenSearch Module: Similarly, show the experimental OpenSearch integration from app/opensearch with equivalent classes and functionalities (like Importer, IndexMapping, and ReverseHandler).
- Nominatim Importer/Updater: Include a block to represent the modules that handle data import from a Nominatim database, enabling continuous updates (with scripts like continuously_update_from_nominatim.sh and the specialized nominatim packages). This component interacts with external PostgreSQL databases.
- Client/User Interface: Include the website front-end (with static files such as HTML, JS using leaflet.photon), which consumes the API for map-based display and search results.

##### Relationships and Data Flows
- API Server routing requests to the corresponding Request Handlers.

##### Architectural Patterns and Technologies
- Separation of concerns:
- The front-end UI (website)
- The Photon API Server (core business logic)
- The search engine integration (via Elasticsearch or OpenSearch)
- The background importer/updater tasks (handling Nominatim data ingestion)
- That the design uses a modular approach where similar functionalities are split into separate modules (e.g., different packages for each search engine integration).
- Mention that key technologies include Java (JDK 11+), Gradle for builds, Elasticsearch/OpenSearch for indexing and search, and PostgreSQL for the Nominatim backend.
- If desired, note that there is support for structured queries and multilingual search, which can be highlighted within the request processing module.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Layer"
        Client["Client/Website UI"]:::frontend
    end

    subgraph "Backend Services"
        PhotonAPIServer["Photon API Server"]:::backend
        QueryHandlers["Query & Request Handlers"]:::backend
    end

    subgraph "Search Engine Integration"
        EmbeddedES["Embedded Elasticsearch Module"]:::search
        OpenSearch["OpenSearch Experimental Module"]:::search
    end

    subgraph "Data Ingestion"
        NominatimImporter["Nominatim Importer/Updater"]:::updater
    end

    ExternalData["External Data Sources (Nominatim/PostgreSQL,GraphHopper)"]:::external

    Client -->|"HTTP_Request"| PhotonAPIServer
    PhotonAPIServer -->|"Route_Request"| QueryHandlers
    QueryHandlers -->|"process_query"| EmbeddedES
    QueryHandlers -->|"process_query"| OpenSearch
    ExternalData -->|"data_import"| NominatimImporter
    NominatimImporter -->|"index_update"| EmbeddedES
    NominatimImporter -->|"index_update"| OpenSearch

    click PhotonAPIServer "https://github.com/komoot/photon/blob/master/src/main/java/de/komoot/photon/App.java"
    click QueryHandlers "https://github.com/komoot/photon/blob/master/src/main/java/de/komoot/photon/SearchRequestHandler.java"
    click EmbeddedES "https://github.com/komoot/photon/tree/master/app/es_embedded"
    click OpenSearch "https://github.com/komoot/photon/tree/master/app/opensearch"
    click NominatimImporter "https://github.com/komoot/photon/tree/master/src/main/java/de/komoot/photon/nominatim"
    click Client "https://github.com/komoot/photon/blob/master/website/photon/index.html"

    classDef frontend fill:#FFD700,stroke:#DAA520,stroke-width:2px;
    classDef backend fill:#ADD8E6,stroke:#00008B,stroke-width:2px;
    classDef search fill:#98FB98,stroke:#2E8B57,stroke-width:2px;
    classDef updater fill:#FFB6C1,stroke:#CD5C5C,stroke-width:2px;
    classDef external fill:#D3D3D3,stroke:#696969,stroke-width:2px;
```
