# matdesbois/openretailmap architecture

> Architecture diagram of the GitHub repository matdesbois/openretailmap, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/matdesbois/openretailmap
- Repository: https://github.com/matdesbois/openretailmap

## Overview

OpenRetailMap is a French commerce observatory: its main user workflow is viewing and filtering a map, inspecting or editing a shop, and optionally validating its OSM–SIRENE match. Nightly jobs refresh source data, match records, and regenerate commercial poles; API routes serve tiles, exports, quality information, and edits. README capabilities also include press monitoring and RTK field validation, but the supplied tree has no clearly dedicated implementation for them, so those are not presented as verified runtime components.

Main entry points: [`backend/main.py`](https://github.com/matdesbois/openretailmap/blob/master/backend/main.py) (FastAPI application), [`backend/routes/osm_edit.py`](https://github.com/matdesbois/openretailmap/blob/master/backend/routes/osm_edit.py) (Shop edit API), [`backend/routes/tiles.py`](https://github.com/matdesbois/openretailmap/blob/master/backend/routes/tiles.py) (Vector tile API), [`backend/scripts/nightly_pipeline.py`](https://github.com/matdesbois/openretailmap/blob/master/backend/scripts/nightly_pipeline.py) (Nightly orchestrator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Map and workflows"]
  node_map["Commerce map<br/>[main.fusion.js]"]
  node_search["Search and filters<br/>[search.js]"]
  node_shop_edit_ui["Shop editor<br/>[shop_edit.js]"]
  node_poles_ui["Pole views<br/>[poles_realtime.js]"]
  node_quality_ui["Quality dashboard"]
end

subgraph group_api["Application API"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_auth_api["Access gate API<br/>[auth_gate.py]"]
  node_edit_api["Shop edit API<br/>[osm_edit.py]"]
  node_tile_api["Vector tile API<br/>[tiles.py]"]
  node_sirene_api["SIRENE matching API<br/>[sirene.py]"]
  node_export_api["Data exports<br/>[export.py]"]
  node_quality_api["Quality API<br/>[quality.py]"]
end

subgraph group_data["Data and analysis"]
  node_shop_model["Shop data model<br/>[shop.py]"]
  node_similarity["Similarity scoring<br/>[similarity.py]"]
  node_poles["Pole generation<br/>[poles_generator.py]"]
  node_postgres[("PostgreSQL / PostGIS<br/>[db_pool.py]")]
  node_redis[("Redis tile cache<br/>[cache.py]")]
end

subgraph group_ops["Data refresh"]
  node_osm_import["OSM import<br/>[osm_import.py]"]
  node_nightly["Nightly orchestrator"]
end

node_users(("Territorial users"))
node_osm_sync{{"OSM service"}}
node_sirene_source{{"SIRENE source"}}

node_users -->|"views"| node_map
node_map -.->|"requests tiles"| node_tile_api
node_search -.->|"filters map"| node_map
node_users -->|"edits shops"| node_shop_edit_ui
node_shop_edit_ui -.->|"submits edits"| node_edit_api
node_users -->|"explores poles"| node_poles_ui
node_users -.->|"reviews quality"| node_quality_ui
node_api_app -->|"registers routes"| node_auth_api
node_api_app -->|"registers routes"| node_edit_api
node_api_app -->|"registers routes"| node_tile_api
node_api_app -->|"registers routes"| node_sirene_api
node_api_app -->|"registers routes"| node_export_api
node_api_app -->|"registers routes"| node_quality_api
node_edit_api -->|"validates edits"| node_shop_model
node_edit_api -->|"invalidates tiles"| node_redis
node_tile_api -->|"reads features"| node_postgres
node_tile_api -->|"caches tiles"| node_redis
node_sirene_api -->|"scores matches"| node_similarity
node_poles -->|"reads and writes"| node_postgres
node_osm_import -->|"imports records"| node_postgres
node_nightly -->|"runs matching job"| node_similarity
node_nightly -->|"flushes tile cache"| node_redis
node_osm_sync -.->|"provides OSM data"| node_osm_import
node_sirene_source -.->|"supplies updates"| node_nightly

click node_map "https://github.com/matdesbois/openretailmap/blob/master/js/main.fusion.js"
click node_search "https://github.com/matdesbois/openretailmap/blob/master/js/search.js"
click node_shop_edit_ui "https://github.com/matdesbois/openretailmap/blob/master/js/shop_edit.js"
click node_poles_ui "https://github.com/matdesbois/openretailmap/blob/master/js/poles_realtime.js"
click node_quality_ui "https://github.com/matdesbois/openretailmap/blob/master/js/quality_dashboard.js"
click node_api_app "https://github.com/matdesbois/openretailmap/blob/master/backend/main.py"
click node_auth_api "https://github.com/matdesbois/openretailmap/blob/master/backend/routes/auth_gate.py"
click node_edit_api "https://github.com/matdesbois/openretailmap/blob/master/backend/routes/osm_edit.py"
click node_tile_api "https://github.com/matdesbois/openretailmap/blob/master/backend/routes/tiles.py"
click node_sirene_api "https://github.com/matdesbois/openretailmap/blob/master/backend/routes/sirene.py"
click node_export_api "https://github.com/matdesbois/openretailmap/blob/master/backend/routes/export.py"
click node_quality_api "https://github.com/matdesbois/openretailmap/blob/master/backend/routes/quality.py"
click node_shop_model "https://github.com/matdesbois/openretailmap/blob/master/backend/models/shop.py"
click node_similarity "https://github.com/matdesbois/openretailmap/blob/master/backend/matching/similarity.py"
click node_poles "https://github.com/matdesbois/openretailmap/blob/master/backend/poles_generator.py"
click node_osm_import "https://github.com/matdesbois/openretailmap/blob/master/backend/osm_import.py"
click node_nightly "https://github.com/matdesbois/openretailmap/blob/master/backend/scripts/nightly_pipeline.py"
click node_postgres "https://github.com/matdesbois/openretailmap/blob/master/backend/db_pool.py"
click node_redis "https://github.com/matdesbois/openretailmap/blob/master/backend/cache.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_map,node_search,node_shop_edit_ui,node_poles_ui,node_quality_ui,node_users toneBlue
class node_api_app,node_auth_api,node_edit_api,node_tile_api,node_sirene_api,node_export_api,node_quality_api toneAmber
class node_shop_model,node_similarity,node_poles,node_postgres,node_redis toneMint
class node_osm_import,node_nightly toneRose
class node_osm_sync,node_sirene_source toneIndigo
```

## Components

### Map and workflows

- [Commerce map](https://github.com/matdesbois/openretailmap/blob/master/js/main.fusion.js): `js/main.fusion.js`
- [Search and filters](https://github.com/matdesbois/openretailmap/blob/master/js/search.js): `js/search.js`
- [Shop editor](https://github.com/matdesbois/openretailmap/blob/master/js/shop_edit.js): `js/shop_edit.js`
- [Pole views](https://github.com/matdesbois/openretailmap/blob/master/js/poles_realtime.js): `js/poles_realtime.js`
- [Quality dashboard](https://github.com/matdesbois/openretailmap/blob/master/js/quality_dashboard.js): `js/quality_dashboard.js`

### Application API

- [FastAPI application](https://github.com/matdesbois/openretailmap/blob/master/backend/main.py): `backend/main.py`
- [Access gate API](https://github.com/matdesbois/openretailmap/blob/master/backend/routes/auth_gate.py): `backend/routes/auth_gate.py`
- [Shop edit API](https://github.com/matdesbois/openretailmap/blob/master/backend/routes/osm_edit.py): `backend/routes/osm_edit.py`
- [Vector tile API](https://github.com/matdesbois/openretailmap/blob/master/backend/routes/tiles.py): `backend/routes/tiles.py`
- [SIRENE matching API](https://github.com/matdesbois/openretailmap/blob/master/backend/routes/sirene.py): `backend/routes/sirene.py`
- [Data exports](https://github.com/matdesbois/openretailmap/blob/master/backend/routes/export.py): `backend/routes/export.py`
- [Quality API](https://github.com/matdesbois/openretailmap/blob/master/backend/routes/quality.py): `backend/routes/quality.py`

### Data and analysis

- [Shop data model](https://github.com/matdesbois/openretailmap/blob/master/backend/models/shop.py): `backend/models/shop.py`
- [Similarity scoring](https://github.com/matdesbois/openretailmap/blob/master/backend/matching/similarity.py): `backend/matching/similarity.py`
- [Pole generation](https://github.com/matdesbois/openretailmap/blob/master/backend/poles_generator.py): `backend/poles_generator.py`
- [PostgreSQL / PostGIS](https://github.com/matdesbois/openretailmap/blob/master/backend/db_pool.py): `backend/db_pool.py`
- [Redis tile cache](https://github.com/matdesbois/openretailmap/blob/master/backend/cache.py): `backend/cache.py`

### Data refresh

- [OSM import](https://github.com/matdesbois/openretailmap/blob/master/backend/osm_import.py): `backend/osm_import.py`
- [Nightly orchestrator](https://github.com/matdesbois/openretailmap/blob/master/backend/scripts/nightly_pipeline.py): `backend/scripts/nightly_pipeline.py`

### Other components

- **Territorial users**
- **OSM service**
- **SIRENE source**

## Connections

- Territorial users → Commerce map: views
- Commerce map → Vector tile API: requests tiles
- Search and filters → Commerce map: filters map
- Territorial users → Shop editor: edits shops
- Shop editor → Shop edit API: submits edits
- Territorial users → Pole views: explores poles
- Territorial users → Quality dashboard: reviews quality
- FastAPI application → Access gate API: registers routes (evidence: `backend/main.py`)
- FastAPI application → Shop edit API: registers routes (evidence: `backend/main.py`)
- FastAPI application → Vector tile API: registers routes (evidence: `backend/main.py`)
- FastAPI application → SIRENE matching API: registers routes (evidence: `backend/main.py`)
- FastAPI application → Data exports: registers routes (evidence: `backend/main.py`)
- FastAPI application → Quality API: registers routes (evidence: `backend/main.py`)
- Shop edit API → Shop data model: validates edits (evidence: `backend/routes/osm_edit.py`)
- Shop edit API → Redis tile cache: invalidates tiles (evidence: `backend/routes/osm_edit.py`)
- Vector tile API → PostgreSQL / PostGIS: reads features (evidence: `backend/routes/tiles.py`)
- Vector tile API → Redis tile cache: caches tiles (evidence: `backend/routes/tiles.py`)
- SIRENE matching API → Similarity scoring: scores matches (evidence: `backend/routes/sirene.py`)
- Pole generation → PostgreSQL / PostGIS: reads and writes (evidence: `backend/poles_generator.py`)
- OSM import → PostgreSQL / PostGIS: imports records (evidence: `backend/osm_import.py`)
- Nightly orchestrator → Similarity scoring: runs matching job (evidence: `backend/scripts/nightly_pipeline.py`)
- Nightly orchestrator → Redis tile cache: flushes tile cache (evidence: `backend/scripts/nightly_pipeline.py`)
- OSM service → OSM import: provides OSM data
- SIRENE source → Nightly orchestrator: supplies updates