# opensupplyhub/open-supply-hub architecture

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

- Interactive diagram: https://gitdiagram.com/opensupplyhub/open-supply-hub
- Repository: https://github.com/opensupplyhub/open-supply-hub

## Overview

Open Supply Hub identifies and maintains production facilities through public search, contributor submissions, claims and moderation, candidate review, and partner-data ingestion. The README documents the principal list workflow: upload, parse, approve, geocode, then match; partner spreadsheets have a separate processing path. The graph also includes the React interface, facility data/search, candidate handling, and ContriBot’s list automation. Several backend subsystems are represented at their existing directory paths because their implementation files were not sampled; edges are limited to README statements and indexed or excerpted references.

Main entry points: [`src/contribot/process_list/handler.py`](https://github.com/opensupplyhub/open-supply-hub/blob/main/src/contribot/process_list/handler.py) (Process facility lists), [`src/django/api/models/facility/facility.py`](https://github.com/opensupplyhub/open-supply-hub/blob/main/src/django/api/models/facility/facility.py) (Facility records), [`src/django/api/management/commands/batch_process.py`](https://github.com/opensupplyhub/open-supply-hub/blob/main/src/django/api/management/commands/batch_process.py) (List processing command), [`src/django/api/partner_data_file_upload`](https://github.com/opensupplyhub/open-supply-hub/tree/main/src/django/api/partner_data_file_upload) (Partner upload processing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_react["React application<br/>[App.jsx]"]
  node_routes["Route handling<br/>[Routes.jsx]"]
  node_candidate_review["Candidate review"]
end

subgraph group_facility["Facility platform"]
  node_django_api["Django API"]
  node_facility_records[("Facility records<br/>[facility.py]")]
  node_facility_index[("Facility index<br/>[facility_index.py]")]
  node_facility_search["Facility search"]
  node_processing_query["Processing filters"]
end

subgraph group_ingestion["Data ingestion"]
  node_list_processing["List processing command<br/>[batch_process.py]"]
  node_partner_upload["Partner upload processing"]
  node_satellite_ingest["Satellite detections"]
end

subgraph group_automation["List automation"]
  node_contribot_fetch["Fetch facility lists<br/>[handler.py]"]
  node_contribot_process["Process facility lists<br/>[handler.py]"]
  node_list_state[("List state repository")]
  node_upload_storage["Upload file storage<br/>[s3_storage.py]"]
  node_os_hub_api_client["OS Hub API client<br/>[os_hub_api.py]"]
end

subgraph group_matching["Deduplication"]
  node_dedupe_api["Dedupe service<br/>[main.py]"]
  node_facility_matcher["Facility matcher"]
end

node_user(("Contributors and moderators"))
node_kafka["Kafka"]
node_earth_index["Earth Index"]

node_user -->|"uses"| node_react
node_react -->|"renders routes"| node_routes
node_user -->|"uploads and approves"| node_list_processing
node_list_processing -->|"parses, geocodes, matches"| node_list_processing
node_user -->|"submits spreadsheet"| node_partner_upload
node_partner_upload -->|"processes upload"| node_partner_upload
node_django_api -.->|"serves facility data"| node_facility_records
node_facility_search -->|"builds filter"| node_processing_query
node_facility_search -->|"queries"| node_facility_index
node_facility_records -->|"references"| node_facility_index
node_satellite_ingest -->|"fetches detections"| node_earth_index
node_satellite_ingest -->|"creates candidates"| node_facility_records
node_contribot_fetch -->|"reads and updates"| node_list_state
node_contribot_process -->|"updates state"| node_list_state
node_contribot_process -->|"downloads uploads"| node_upload_storage
node_contribot_process -->|"calls API"| node_os_hub_api_client
node_dedupe_api -->|"initializes matcher"| node_facility_matcher
node_dedupe_api -->|"consumes and publishes"| node_kafka

click node_react "https://github.com/opensupplyhub/open-supply-hub/blob/main/src/react/src/App.jsx"
click node_routes "https://github.com/opensupplyhub/open-supply-hub/blob/main/src/react/src/Routes.jsx"
click node_candidate_review "https://github.com/opensupplyhub/open-supply-hub/blob/main/src/react/src/components/Candidate/CandidateReviewPage.jsx"
click node_django_api "https://github.com/opensupplyhub/open-supply-hub/tree/main/src/django/api"
click node_facility_records "https://github.com/opensupplyhub/open-supply-hub/blob/main/src/django/api/models/facility/facility.py"
click node_facility_index "https://github.com/opensupplyhub/open-supply-hub/blob/main/src/django/api/models/facility/facility_index.py"
click node_facility_search "https://github.com/opensupplyhub/open-supply-hub/blob/main/src/django/api/models/facility/facility_manager.py"
click node_processing_query "https://github.com/opensupplyhub/open-supply-hub/tree/main/src/django/api/services"
click node_list_processing "https://github.com/opensupplyhub/open-supply-hub/blob/main/src/django/api/management/commands/batch_process.py"
click node_partner_upload "https://github.com/opensupplyhub/open-supply-hub/tree/main/src/django/api/partner_data_file_upload"
click node_satellite_ingest "https://github.com/opensupplyhub/open-supply-hub/blob/main/src/django/api/management/commands/ingest_satellite_detections.py"
click node_contribot_fetch "https://github.com/opensupplyhub/open-supply-hub/blob/main/src/contribot/fetch_lists/handler.py"
click node_contribot_process "https://github.com/opensupplyhub/open-supply-hub/blob/main/src/contribot/process_list/handler.py"
click node_list_state "https://github.com/opensupplyhub/open-supply-hub/blob/main/src/contribot/lib/lists_repository.py"
click node_upload_storage "https://github.com/opensupplyhub/open-supply-hub/blob/main/src/contribot/lib/s3_storage.py"
click node_os_hub_api_client "https://github.com/opensupplyhub/open-supply-hub/blob/main/src/contribot/lib/os_hub_api.py"
click node_dedupe_api "https://github.com/opensupplyhub/open-supply-hub/blob/main/src/dedupe-hub/api/app/main.py"
click node_facility_matcher "https://github.com/opensupplyhub/open-supply-hub/blob/main/src/dedupe-hub/api/app/matching/facilities_matcher.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_react,node_routes,node_candidate_review toneBlue
class node_django_api,node_facility_records,node_facility_index,node_facility_search,node_processing_query toneAmber
class node_list_processing,node_partner_upload,node_satellite_ingest toneMint
class node_contribot_fetch,node_contribot_process,node_list_state,node_upload_storage,node_os_hub_api_client toneRose
class node_dedupe_api,node_facility_matcher,node_user,node_kafka,node_earth_index toneIndigo
```

## Components

### User interface

- [React application](https://github.com/opensupplyhub/open-supply-hub/blob/main/src/react/src/App.jsx): `src/react/src/App.jsx`
- [Route handling](https://github.com/opensupplyhub/open-supply-hub/blob/main/src/react/src/Routes.jsx): `src/react/src/Routes.jsx`
- [Candidate review](https://github.com/opensupplyhub/open-supply-hub/blob/main/src/react/src/components/Candidate/CandidateReviewPage.jsx): `src/react/src/components/Candidate/CandidateReviewPage.jsx`

### Facility platform

- [Django API](https://github.com/opensupplyhub/open-supply-hub/tree/main/src/django/api): `src/django/api`
- [Facility records](https://github.com/opensupplyhub/open-supply-hub/blob/main/src/django/api/models/facility/facility.py): `src/django/api/models/facility/facility.py`
- [Facility index](https://github.com/opensupplyhub/open-supply-hub/blob/main/src/django/api/models/facility/facility_index.py): `src/django/api/models/facility/facility_index.py`
- [Facility search](https://github.com/opensupplyhub/open-supply-hub/blob/main/src/django/api/models/facility/facility_manager.py): `src/django/api/models/facility/facility_manager.py`
- [Processing filters](https://github.com/opensupplyhub/open-supply-hub/tree/main/src/django/api/services): `src/django/api/services`

### Data ingestion

- [List processing command](https://github.com/opensupplyhub/open-supply-hub/blob/main/src/django/api/management/commands/batch_process.py): `src/django/api/management/commands/batch_process.py`
- [Partner upload processing](https://github.com/opensupplyhub/open-supply-hub/tree/main/src/django/api/partner_data_file_upload): `src/django/api/partner_data_file_upload`
- [Satellite detections](https://github.com/opensupplyhub/open-supply-hub/blob/main/src/django/api/management/commands/ingest_satellite_detections.py): `src/django/api/management/commands/ingest_satellite_detections.py`

### List automation

- [Fetch facility lists](https://github.com/opensupplyhub/open-supply-hub/blob/main/src/contribot/fetch_lists/handler.py): `src/contribot/fetch_lists/handler.py`
- [Process facility lists](https://github.com/opensupplyhub/open-supply-hub/blob/main/src/contribot/process_list/handler.py): `src/contribot/process_list/handler.py`
- [List state repository](https://github.com/opensupplyhub/open-supply-hub/blob/main/src/contribot/lib/lists_repository.py): `src/contribot/lib/lists_repository.py`
- [Upload file storage](https://github.com/opensupplyhub/open-supply-hub/blob/main/src/contribot/lib/s3_storage.py): `src/contribot/lib/s3_storage.py`
- [OS Hub API client](https://github.com/opensupplyhub/open-supply-hub/blob/main/src/contribot/lib/os_hub_api.py): `src/contribot/lib/os_hub_api.py`

### Deduplication

- [Dedupe service](https://github.com/opensupplyhub/open-supply-hub/blob/main/src/dedupe-hub/api/app/main.py): `src/dedupe-hub/api/app/main.py`
- [Facility matcher](https://github.com/opensupplyhub/open-supply-hub/blob/main/src/dedupe-hub/api/app/matching/facilities_matcher.py): `src/dedupe-hub/api/app/matching/facilities_matcher.py`

### Other components

- **Contributors and moderators**
- **Kafka**
- **Earth Index**

## Connections

- Contributors and moderators → React application: uses (evidence: `README.md`)
- React application → Route handling: renders routes (evidence: `src/react/src/App.jsx`)
- Contributors and moderators → List processing command: uploads and approves (evidence: `README.md`)
- List processing command → List processing command: parses, geocodes, matches (evidence: `README.md`)
- Contributors and moderators → Partner upload processing: submits spreadsheet (evidence: `README.md`)
- Partner upload processing → Partner upload processing: processes upload (evidence: `README.md`)
- Django API → Facility records: serves facility data (evidence: `src/django/api/models/facility/facility_manager.py`)
- Facility search → Processing filters: builds filter (evidence: `src/django/api/models/facility/facility_manager.py`)
- Facility search → Facility index: queries (evidence: `src/django/api/models/facility/facility_manager.py`)
- Facility records → Facility index: references (evidence: `src/django/api/models/facility/facility.py`)
- Satellite detections → Earth Index: fetches detections (evidence: `src/django/api/management/commands/ingest_satellite_detections.py`)
- Satellite detections → Facility records: creates candidates (evidence: `src/django/api/management/commands/ingest_satellite_detections.py`)
- Fetch facility lists → List state repository: reads and updates (evidence: `src/contribot/fetch_lists/handler.py`)
- Process facility lists → List state repository: updates state (evidence: `src/contribot/process_list/handler.py`)
- Process facility lists → Upload file storage: downloads uploads (evidence: `src/contribot/process_list/handler.py`)
- Process facility lists → OS Hub API client: calls API (evidence: `src/contribot/process_list/handler.py`)
- Dedupe service → Facility matcher: initializes matcher (evidence: `src/dedupe-hub/api/app/main.py`)
- Dedupe service → Kafka: consumes and publishes (evidence: `src/dedupe-hub/api/app/main.py`)
