# blsq/iaso architecture

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

- Interactive diagram: https://gitdiagram.com/blsq/iaso
- Repository: https://github.com/blsq/iaso

## Overview

Iaso is a geospatial data-management platform for maintaining organizational-unit hierarchies and collecting, validating, comparing, and exporting linked field data. The main workflow begins with mobile or web collection, passes submissions and proposed hierarchy changes through API-backed validation, and makes accepted data available for exports and integrations. The graph includes documented import/comparison and asynchronous-task capabilities as separate branches. Several model files named in the source index are absent from the supplied tree, so model-layer paths and unverified implementation links are omitted.

Main entry points: [`iaso/models/querysets.py`](https://github.com/blsq/iaso/blob/develop/iaso/models/querysets.py) (Registry data), [`iaso/api/instances/views.py`](https://github.com/blsq/iaso/blob/develop/iaso/api/instances/views.py) (Submission API), [`iaso/engine/validation_workflow.py`](https://github.com/blsq/iaso/blob/develop/iaso/engine/validation_workflow.py) (Validation workflows), [`iaso/models/task.py`](https://github.com/blsq/iaso/blob/develop/iaso/models/task.py) (Task records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collect["Field collection"]
  node_mobile_api["Mobile APIs<br/>[views_mobile.py]"]
  node_submissions["Submission API<br/>[views.py]"]
  node_form_api["Forms API<br/>[views.py]"]
end

subgraph group_registry["Georegistry and validation"]
  node_org_api["Org-unit API<br/>[views.py]"]
  node_change_api["Change requests<br/>[views.py]"]
  node_validation["Validation workflows"]
  node_hierarchy[("Registry data<br/>[querysets.py]")]
end

subgraph group_integrations["Imports and exports"]
  node_diffing["Tree comparison<br/>[differ.py]"]
  node_gpkg_import["GeoPackage import<br/>[import_gpkg.py]"]
  node_exports["Data exports<br/>[export_utils.py]"]
  node_dhis2["DHIS2 integration"]
end

subgraph group_platform["Platform services"]
  node_tasks_api["Task API<br/>[views.py]"]
  node_task_worker["Task worker<br/>[services.py]"]
  node_task_state[("Task records<br/>[task.py]")]
  node_openhexa["OpenHEXA pipelines"]
end

node_mobile_user(("Field worker"))
node_web_user(("Web user"))
node_database[("PostgreSQL")]

node_mobile_user -->|"submits data"| node_mobile_api
node_mobile_api -.->|"handles submissions"| node_submissions
node_web_user -.->|"manages hierarchy"| node_org_api
node_web_user -.->|"reviews changes"| node_change_api
node_submissions -->|"validates data"| node_validation
node_change_api -.->|"validates changes"| node_validation
node_org_api -.->|"reads and updates"| node_hierarchy
node_validation -.->|"applies decisions"| node_hierarchy
node_form_api -.->|"stores form data"| node_database
node_hierarchy -->|"persists registry"| node_database
node_gpkg_import -->|"imports hierarchy"| node_hierarchy
node_diffing -->|"compares trees"| node_hierarchy
node_exports -->|"exports registry data"| node_hierarchy
node_submissions -->|"exports submissions"| node_exports
node_dhis2 -->|"exchanges data"| node_hierarchy
node_tasks_api -->|"reads task status"| node_task_state
node_task_worker -->|"runs and updates"| node_task_state
node_task_worker -.->|"dispatches pipeline"| node_openhexa
node_openhexa -->|"records progress"| node_task_state

click node_mobile_api "https://github.com/blsq/iaso/blob/develop/iaso/api/instances/views_mobile.py"
click node_submissions "https://github.com/blsq/iaso/blob/develop/iaso/api/instances/views.py"
click node_form_api "https://github.com/blsq/iaso/blob/develop/iaso/api/forms/views.py"
click node_org_api "https://github.com/blsq/iaso/blob/develop/iaso/api/org_units/views.py"
click node_change_api "https://github.com/blsq/iaso/blob/develop/iaso/api/org_unit_change_requests/views.py"
click node_validation "https://github.com/blsq/iaso/blob/develop/iaso/engine/validation_workflow.py"
click node_hierarchy "https://github.com/blsq/iaso/blob/develop/iaso/models/querysets.py"
click node_diffing "https://github.com/blsq/iaso/blob/develop/iaso/diffing/differ.py"
click node_gpkg_import "https://github.com/blsq/iaso/blob/develop/iaso/gpkg/import_gpkg.py"
click node_exports "https://github.com/blsq/iaso/blob/develop/hat/api/export_utils.py"
click node_dhis2 "https://github.com/blsq/iaso/blob/develop/iaso/dhis2/export_request_builder.py"
click node_tasks_api "https://github.com/blsq/iaso/blob/develop/iaso/api/tasks/views.py"
click node_task_worker "https://github.com/blsq/iaso/blob/develop/beanstalk_worker/services.py"
click node_task_state "https://github.com/blsq/iaso/blob/develop/iaso/models/task.py"
click node_openhexa "https://github.com/blsq/iaso/blob/develop/iaso/tasks/launch_openhexa_pipeline.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_mobile_api,node_submissions,node_form_api,node_web_user toneBlue
class node_org_api,node_change_api,node_validation,node_hierarchy,node_database toneAmber
class node_diffing,node_gpkg_import,node_exports,node_dhis2 toneMint
class node_tasks_api,node_task_worker,node_task_state,node_openhexa,node_mobile_user toneRose
```

## Components

### Field collection

- [Mobile APIs](https://github.com/blsq/iaso/blob/develop/iaso/api/instances/views_mobile.py): `iaso/api/instances/views_mobile.py`
- [Submission API](https://github.com/blsq/iaso/blob/develop/iaso/api/instances/views.py): `iaso/api/instances/views.py`
- [Forms API](https://github.com/blsq/iaso/blob/develop/iaso/api/forms/views.py): `iaso/api/forms/views.py`

### Georegistry and validation

- [Org-unit API](https://github.com/blsq/iaso/blob/develop/iaso/api/org_units/views.py): `iaso/api/org_units/views.py`
- [Change requests](https://github.com/blsq/iaso/blob/develop/iaso/api/org_unit_change_requests/views.py): `iaso/api/org_unit_change_requests/views.py`
- [Validation workflows](https://github.com/blsq/iaso/blob/develop/iaso/engine/validation_workflow.py): `iaso/engine/validation_workflow.py`
- [Registry data](https://github.com/blsq/iaso/blob/develop/iaso/models/querysets.py): `iaso/models/querysets.py`

### Imports and exports

- [Tree comparison](https://github.com/blsq/iaso/blob/develop/iaso/diffing/differ.py): `iaso/diffing/differ.py`
- [GeoPackage import](https://github.com/blsq/iaso/blob/develop/iaso/gpkg/import_gpkg.py): `iaso/gpkg/import_gpkg.py`
- [Data exports](https://github.com/blsq/iaso/blob/develop/hat/api/export_utils.py): `hat/api/export_utils.py`
- [DHIS2 integration](https://github.com/blsq/iaso/blob/develop/iaso/dhis2/export_request_builder.py): `iaso/dhis2/export_request_builder.py`

### Platform services

- [Task API](https://github.com/blsq/iaso/blob/develop/iaso/api/tasks/views.py): `iaso/api/tasks/views.py`
- [Task worker](https://github.com/blsq/iaso/blob/develop/beanstalk_worker/services.py): `beanstalk_worker/services.py`
- [Task records](https://github.com/blsq/iaso/blob/develop/iaso/models/task.py): `iaso/models/task.py`
- [OpenHEXA pipelines](https://github.com/blsq/iaso/blob/develop/iaso/tasks/launch_openhexa_pipeline.py): `iaso/tasks/launch_openhexa_pipeline.py`

### Other components

- **Field worker**
- **Web user**
- **PostgreSQL**

## Connections

- Field worker → Mobile APIs: submits data
- Mobile APIs → Submission API: handles submissions
- Web user → Org-unit API: manages hierarchy
- Web user → Change requests: reviews changes
- Submission API → Validation workflows: validates data (evidence: `iaso/api/instances/views.py`)
- Change requests → Validation workflows: validates changes
- Org-unit API → Registry data: reads and updates
- Validation workflows → Registry data: applies decisions
- Forms API → PostgreSQL: stores form data
- Registry data → PostgreSQL: persists registry
- GeoPackage import → Registry data: imports hierarchy
- Tree comparison → Registry data: compares trees
- Data exports → Registry data: exports registry data
- Submission API → Data exports: exports submissions (evidence: `iaso/api/instances/views.py`)
- DHIS2 integration → Registry data: exchanges data
- Task API → Task records: reads task status (evidence: `iaso/api/tasks/views.py`)
- Task worker → Task records: runs and updates (evidence: `beanstalk_worker/services.py`)
- Task worker → OpenHEXA pipelines: dispatches pipeline
- OpenHEXA pipelines → Task records: records progress (evidence: `iaso/tasks/launch_openhexa_pipeline.py`)