How komoot/photon works
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.