# jamesleondufour/kobo-autoqa architecture

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

- Interactive diagram: https://gitdiagram.com/jamesleondufour/kobo-autoqa
- Repository: https://github.com/jamesleondufour/kobo-autoqa

## Overview

Kobo AutoQA automates transcription, translation, and qualitative analysis for KoboToolbox submissions. Administrators configure accounts, connections, forms, webhooks, languages, and analysis questions through the web UI or CLI. Submissions enter through the webhook or polling catch-up, are queued in SQLite, and a worker advances each through asynchronous NLP stages before results are written back to Kobo supplemental details. The README documents major UI and workflow capabilities; several supporting modules are indexed but unsampled, so uncertain implementation links are omitted.

Main entry points: [`app/admin.py`](https://github.com/jamesleondufour/kobo-autoqa/blob/main/app/admin.py) (Admin API), [`app/pipeline.py`](https://github.com/jamesleondufour/kobo-autoqa/blob/main/app/pipeline.py) (Submission state machine), [`app/store.py`](https://github.com/jamesleondufour/kobo-autoqa/blob/main/app/store.py) (SQLite store), [`app/kobo.py`](https://github.com/jamesleondufour/kobo-autoqa/blob/main/app/kobo.py) (Kobo API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Setup and access"]
  node_admin_ui["Admin UI<br/>[index.html]"]
  node_admin_api["Admin API<br/>[admin.py]"]
  node_auth["Session auth<br/>[auth.py]"]
  node_accounts["Account management<br/>[users.py]"]
  node_cli["Setup CLI<br/>[cli.py]"]
  node_asset_config["Recording config<br/>[assetconf.py]"]
  node_rate_limit["Rate limiting<br/>[ratelimit.py]"]
end

subgraph group_intake["Submission intake"]
  node_webhook["Webhook receiver<br/>[webhook.py]"]
  node_poller["Catch-up poller<br/>[worker.py]"]
  node_worker["Worker loop<br/>[worker.py]"]
end

subgraph group_processing["NLP processing"]
  node_pipeline["Submission state machine<br/>[pipeline.py]"]
  node_payloads["NLP payloads<br/>[payloads.py]"]
  node_supplement["Supplement handling<br/>[supplement.py]"]
end

subgraph group_persistence["State and settings"]
  node_settings["Environment settings<br/>[config.py]"]
  node_runtime_settings["Runtime settings<br/>[runtime.py]"]
  node_store[("SQLite store<br/>[store.py]")]
  node_common["Shared wiring<br/>[common.py]"]
end

subgraph group_integrations["Kobo integration"]
  node_kobo_client["Kobo API client<br/>[kobo.py]"]
end

node_browser_user(("Administrator"))
node_kobo(("KoboToolbox"))
node_submission["Kobo submission"]
node_results["Supplemental results"]

node_browser_user -->|"uses"| node_admin_ui
node_admin_ui -->|"configures and monitors"| node_admin_api
node_admin_api -->|"authenticates"| node_auth
node_auth -->|"validates accounts"| node_accounts
node_admin_api -->|"reads and updates"| node_store
node_admin_api -->|"configures and queries"| node_kobo_client
node_admin_api -->|"configures recordings"| node_asset_config
node_admin_api -->|"limits requests"| node_rate_limit
node_cli -->|"runs jobs"| node_pipeline
node_cli -->|"queues and inspects"| node_store
node_admin_api -->|"saves connection settings"| node_runtime_settings
node_runtime_settings -->|"persists overrides"| node_store
node_browser_user -->|"uses headlessly"| node_cli
node_kobo -->|"creates"| node_submission
node_submission -->|"posts event"| node_webhook
node_webhook -->|"enqueues"| node_store
node_poller -->|"polls submissions"| node_kobo_client
node_poller -->|"enqueues missed jobs"| node_store
node_worker -->|"processes queued jobs"| node_pipeline
node_worker -->|"claims and reschedules"| node_store
node_worker -->|"runs catch-up polling"| node_poller
node_pipeline -->|"resolves recording settings"| node_asset_config
node_pipeline -->|"builds and reads payloads"| node_payloads
node_pipeline -->|"checks NLP features"| node_supplement
node_pipeline -->|"requests and checks jobs"| node_kobo_client
node_pipeline -->|"advances job stages"| node_store
node_kobo_client -->|"calls API"| node_kobo
node_kobo -->|"stores NLP results"| node_results
node_admin_api -->|"registers hooks and configures NLP"| node_kobo
node_common -->|"applies connection overrides"| node_runtime_settings
node_common -->|"constructs client"| node_kobo_client

click node_admin_ui "https://github.com/jamesleondufour/kobo-autoqa/blob/main/app/static/index.html"
click node_admin_api "https://github.com/jamesleondufour/kobo-autoqa/blob/main/app/admin.py"
click node_auth "https://github.com/jamesleondufour/kobo-autoqa/blob/main/app/auth.py"
click node_accounts "https://github.com/jamesleondufour/kobo-autoqa/blob/main/app/users.py"
click node_cli "https://github.com/jamesleondufour/kobo-autoqa/blob/main/app/cli.py"
click node_asset_config "https://github.com/jamesleondufour/kobo-autoqa/blob/main/app/assetconf.py"
click node_webhook "https://github.com/jamesleondufour/kobo-autoqa/blob/main/app/webhook.py"
click node_poller "https://github.com/jamesleondufour/kobo-autoqa/blob/main/app/worker.py"
click node_worker "https://github.com/jamesleondufour/kobo-autoqa/blob/main/app/worker.py"
click node_pipeline "https://github.com/jamesleondufour/kobo-autoqa/blob/main/app/pipeline.py"
click node_payloads "https://github.com/jamesleondufour/kobo-autoqa/blob/main/app/payloads.py"
click node_supplement "https://github.com/jamesleondufour/kobo-autoqa/blob/main/app/supplement.py"
click node_rate_limit "https://github.com/jamesleondufour/kobo-autoqa/blob/main/app/ratelimit.py"
click node_settings "https://github.com/jamesleondufour/kobo-autoqa/blob/main/app/config.py"
click node_runtime_settings "https://github.com/jamesleondufour/kobo-autoqa/blob/main/app/runtime.py"
click node_store "https://github.com/jamesleondufour/kobo-autoqa/blob/main/app/store.py"
click node_common "https://github.com/jamesleondufour/kobo-autoqa/blob/main/app/common.py"
click node_kobo_client "https://github.com/jamesleondufour/kobo-autoqa/blob/main/app/kobo.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_admin_ui,node_admin_api,node_auth,node_accounts,node_cli,node_asset_config,node_rate_limit toneBlue
class node_webhook,node_poller,node_worker toneAmber
class node_pipeline,node_payloads,node_supplement toneMint
class node_settings,node_runtime_settings,node_store,node_common toneRose
class node_kobo_client,node_browser_user,node_kobo,node_submission,node_results toneIndigo
```

## Components

### Setup and access

- [Admin UI](https://github.com/jamesleondufour/kobo-autoqa/blob/main/app/static/index.html): `app/static/index.html`
- [Admin API](https://github.com/jamesleondufour/kobo-autoqa/blob/main/app/admin.py): `app/admin.py`
- [Session auth](https://github.com/jamesleondufour/kobo-autoqa/blob/main/app/auth.py): `app/auth.py`
- [Account management](https://github.com/jamesleondufour/kobo-autoqa/blob/main/app/users.py): `app/users.py`
- [Setup CLI](https://github.com/jamesleondufour/kobo-autoqa/blob/main/app/cli.py): `app/cli.py`
- [Recording config](https://github.com/jamesleondufour/kobo-autoqa/blob/main/app/assetconf.py): `app/assetconf.py`
- [Rate limiting](https://github.com/jamesleondufour/kobo-autoqa/blob/main/app/ratelimit.py): `app/ratelimit.py`

### Submission intake

- [Webhook receiver](https://github.com/jamesleondufour/kobo-autoqa/blob/main/app/webhook.py): `app/webhook.py`
- [Catch-up poller](https://github.com/jamesleondufour/kobo-autoqa/blob/main/app/worker.py): `app/worker.py`
- [Worker loop](https://github.com/jamesleondufour/kobo-autoqa/blob/main/app/worker.py): `app/worker.py`

### NLP processing

- [Submission state machine](https://github.com/jamesleondufour/kobo-autoqa/blob/main/app/pipeline.py): `app/pipeline.py`
- [NLP payloads](https://github.com/jamesleondufour/kobo-autoqa/blob/main/app/payloads.py): `app/payloads.py`
- [Supplement handling](https://github.com/jamesleondufour/kobo-autoqa/blob/main/app/supplement.py): `app/supplement.py`

### State and settings

- [Environment settings](https://github.com/jamesleondufour/kobo-autoqa/blob/main/app/config.py): `app/config.py`
- [Runtime settings](https://github.com/jamesleondufour/kobo-autoqa/blob/main/app/runtime.py): `app/runtime.py`
- [SQLite store](https://github.com/jamesleondufour/kobo-autoqa/blob/main/app/store.py): `app/store.py`
- [Shared wiring](https://github.com/jamesleondufour/kobo-autoqa/blob/main/app/common.py): `app/common.py`

### Kobo integration

- [Kobo API client](https://github.com/jamesleondufour/kobo-autoqa/blob/main/app/kobo.py): `app/kobo.py`

### Other components

- **Administrator**
- **KoboToolbox**
- **Kobo submission**
- **Supplemental results**

## Connections

- Administrator → Admin UI: uses (evidence: `README.md`)
- Admin UI → Admin API: configures and monitors (evidence: `README.md`)
- Admin API → Session auth: authenticates (evidence: `app/admin.py`)
- Session auth → Account management: validates accounts (evidence: `app/auth.py`)
- Admin API → SQLite store: reads and updates (evidence: `app/admin.py`)
- Admin API → Kobo API client: configures and queries (evidence: `app/admin.py`)
- Admin API → Recording config: configures recordings (evidence: `app/admin.py`)
- Admin API → Rate limiting: limits requests (evidence: `app/admin.py`)
- Setup CLI → Submission state machine: runs jobs (evidence: `app/cli.py`)
- Setup CLI → SQLite store: queues and inspects (evidence: `app/cli.py`)
- Admin API → Runtime settings: saves connection settings (evidence: `app/admin.py`)
- Runtime settings → SQLite store: persists overrides (evidence: `app/runtime.py`)
- Administrator → Setup CLI: uses headlessly (evidence: `README.md`)
- KoboToolbox → Kobo submission: creates (evidence: `README.md`)
- Kobo submission → Webhook receiver: posts event (evidence: `README.md`)
- Webhook receiver → SQLite store: enqueues (evidence: `app/webhook.py`)
- Catch-up poller → Kobo API client: polls submissions (evidence: `app/worker.py`)
- Catch-up poller → SQLite store: enqueues missed jobs (evidence: `app/worker.py`)
- Worker loop → Submission state machine: processes queued jobs (evidence: `app/worker.py`)
- Worker loop → SQLite store: claims and reschedules (evidence: `app/worker.py`)
- Worker loop → Catch-up poller: runs catch-up polling (evidence: `README.md`)
- Submission state machine → Recording config: resolves recording settings (evidence: `app/pipeline.py`)
- Submission state machine → NLP payloads: builds and reads payloads (evidence: `app/pipeline.py`)
- Submission state machine → Supplement handling: checks NLP features (evidence: `app/pipeline.py`)
- Submission state machine → Kobo API client: requests and checks jobs (evidence: `app/pipeline.py`)
- Submission state machine → SQLite store: advances job stages (evidence: `app/pipeline.py`)
- Kobo API client → KoboToolbox: calls API (evidence: `app/kobo.py`)
- KoboToolbox → Supplemental results: stores NLP results (evidence: `README.md`)
- Admin API → KoboToolbox: registers hooks and configures NLP (evidence: `README.md`)
- Shared wiring → Runtime settings: applies connection overrides (evidence: `app/common.py`)
- Shared wiring → Kobo API client: constructs client (evidence: `app/common.py`)
