# jamesleondufour/kobo-choice-sync architecture

> Architecture diagram of the GitHub repository jamesleondufour/kobo-choice-sync, 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-choice-sync
- Repository: https://github.com/jamesleondufour/kobo-choice-sync

## Overview

This repository synchronizes KoboToolbox “Other” answers into a growing external choices CSV. A Kobo webhook sends the selected value through GitHub Actions to the Python entry point; reconciliation checks existing choices, adds only new values, and updates Kobo media. An explicit catch-up run can scan historical submissions, and manual runs can finish pending media recovery. The README also documents redeployment so collectors can refresh the form. The Python implementation is sampled only in excerpts, so internal links are limited to relationships shown there or documented in the README.

Main entry points: [`kobo_sync/sync.py`](https://github.com/jamesleondufour/kobo-choice-sync/blob/main/kobo_sync/sync.py) (Reconciliation), [`.github/workflows/sync.yml`](https://github.com/jamesleondufour/kobo-choice-sync/blob/main/.github/workflows/sync.yml) (GitHub Actions), [`config.json`](https://github.com/jamesleondufour/kobo-choice-sync/blob/main/config.json) (Sync configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Trigger and entry"]
  node_webhook["Kobo webhook"]
  node_actions["GitHub Actions<br/>[sync.yml]"]
  node_entrypoint["CLI entry point<br/>[sync.py]"]
  node_config["Sync configuration<br/>[config.json]"]
end

subgraph group_sync["Choice synchronization"]
  node_reconcile["Reconciliation<br/>[sync.py]"]
  node_choice_merge["Choice merge<br/>[sync.py]"]
  node_catch_up["Historical catch-up<br/>[sync.py]"]
  node_media_recovery["Media recovery<br/>[sync.py]"]
end

subgraph group_kobo["Kobo services"]
  node_kobo_api["Kobo API client<br/>[sync.py]"]
  node_submissions[("Submission history")]
  node_choice_media[("Choices CSV media")]
  node_form_deploy["Deployed form"]
end

node_collector(("Form collector"))

node_collector -->|"submits Other"| node_webhook
node_webhook -->|"dispatches value"| node_actions
node_actions -->|"runs sync"| node_entrypoint
node_entrypoint -->|"loads settings"| node_config
node_entrypoint -->|"invokes"| node_reconcile
node_reconcile -->|"requests data"| node_kobo_api
node_reconcile -->|"merges choices"| node_choice_merge
node_reconcile -->|"checks recovery"| node_media_recovery
node_reconcile -->|"reads and updates"| node_choice_media
node_kobo_api -->|"reads and uploads"| node_choice_media
node_entrypoint -->|"enables explicitly"| node_catch_up
node_catch_up -->|"scans history"| node_submissions
node_kobo_api -.->|"retrieves submissions"| node_submissions
node_reconcile -->|"redeploys form"| node_form_deploy
node_form_deploy -->|"makes choices available"| node_collector

click node_actions "https://github.com/jamesleondufour/kobo-choice-sync/blob/main/.github/workflows/sync.yml"
click node_entrypoint "https://github.com/jamesleondufour/kobo-choice-sync/blob/main/kobo_sync/sync.py"
click node_config "https://github.com/jamesleondufour/kobo-choice-sync/blob/main/config.json"
click node_reconcile "https://github.com/jamesleondufour/kobo-choice-sync/blob/main/kobo_sync/sync.py"
click node_choice_merge "https://github.com/jamesleondufour/kobo-choice-sync/blob/main/kobo_sync/sync.py"
click node_catch_up "https://github.com/jamesleondufour/kobo-choice-sync/blob/main/kobo_sync/sync.py"
click node_media_recovery "https://github.com/jamesleondufour/kobo-choice-sync/blob/main/kobo_sync/sync.py"
click node_kobo_api "https://github.com/jamesleondufour/kobo-choice-sync/blob/main/kobo_sync/sync.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_webhook,node_actions,node_entrypoint,node_config toneBlue
class node_reconcile,node_choice_merge,node_catch_up,node_media_recovery toneAmber
class node_kobo_api,node_submissions,node_choice_media,node_form_deploy toneMint
class node_collector toneIndigo
```

## Components

### Trigger and entry

- **Kobo webhook**
- [GitHub Actions](https://github.com/jamesleondufour/kobo-choice-sync/blob/main/.github/workflows/sync.yml): `.github/workflows/sync.yml`
- [CLI entry point](https://github.com/jamesleondufour/kobo-choice-sync/blob/main/kobo_sync/sync.py): `kobo_sync/sync.py`
- [Sync configuration](https://github.com/jamesleondufour/kobo-choice-sync/blob/main/config.json): `config.json`

### Choice synchronization

- [Reconciliation](https://github.com/jamesleondufour/kobo-choice-sync/blob/main/kobo_sync/sync.py): `kobo_sync/sync.py`
- [Choice merge](https://github.com/jamesleondufour/kobo-choice-sync/blob/main/kobo_sync/sync.py): `kobo_sync/sync.py`
- [Historical catch-up](https://github.com/jamesleondufour/kobo-choice-sync/blob/main/kobo_sync/sync.py): `kobo_sync/sync.py`
- [Media recovery](https://github.com/jamesleondufour/kobo-choice-sync/blob/main/kobo_sync/sync.py): `kobo_sync/sync.py`

### Kobo services

- [Kobo API client](https://github.com/jamesleondufour/kobo-choice-sync/blob/main/kobo_sync/sync.py): `kobo_sync/sync.py`
- **Submission history**
- **Choices CSV media**
- **Deployed form**

### Other components

- **Form collector**

## Connections

- Form collector → Kobo webhook: submits Other (evidence: `README.md`)
- Kobo webhook → GitHub Actions: dispatches value (evidence: `README.md`)
- GitHub Actions → CLI entry point: runs sync (evidence: `README.md`)
- CLI entry point → Sync configuration: loads settings (evidence: `README.md`)
- CLI entry point → Reconciliation: invokes (evidence: `kobo_sync/sync.py`)
- Reconciliation → Kobo API client: requests data (evidence: `kobo_sync/sync.py`)
- Reconciliation → Choice merge: merges choices (evidence: `kobo_sync/sync.py`)
- Reconciliation → Media recovery: checks recovery (evidence: `kobo_sync/sync.py`)
- Reconciliation → Choices CSV media: reads and updates (evidence: `README.md`)
- Kobo API client → Choices CSV media: reads and uploads (evidence: `kobo_sync/sync.py`)
- CLI entry point → Historical catch-up: enables explicitly (evidence: `kobo_sync/sync.py`)
- Historical catch-up → Submission history: scans history (evidence: `README.md`)
- Kobo API client → Submission history: retrieves submissions
- Reconciliation → Deployed form: redeploys form (evidence: `README.md`)
- Deployed form → Form collector: makes choices available (evidence: `README.md`)
