# kobotoolbox/kobo-transfer architecture

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

## Overview

kobo-transfer is a CLI for moving KoboToolbox assets and submissions between source and destination projects. Its principal workflow optionally recreates an asset and its versions, then downloads submission attachments, transforms and uploads submission XML, with an optional UUID-difference sync. Validation statuses and analysis metadata are separate optional phases. The graph distinguishes the CLI orchestrator from transfer modules and shared configuration/utilities. Sampled code supports the shown calls; the README documents additional usage options, but unsampled modules are not inferred beyond those capabilities.

Main entry points: [`run.py`](https://github.com/kobotoolbox/kobo-transfer/blob/main/run.py) (CLI workflow), [`transfer/xml.py`](https://github.com/kobotoolbox/kobo-transfer/blob/main/transfer/xml.py) (Submission XML), [`transfer/asset.py`](https://github.com/kobotoolbox/kobo-transfer/blob/main/transfer/asset.py) (Asset transfer), [`transfer/validation_status.py`](https://github.com/kobotoolbox/kobo-transfer/blob/main/transfer/validation_status.py) (Status sync)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["CLI orchestration"]
  node_runner["CLI workflow<br/>[run.py]"]
end

subgraph group_transfer["Transfer stages"]
  node_asset["Asset transfer<br/>[asset.py]"]
  node_media["Attachment transfer<br/>[media.py]"]
  node_xml["Submission XML<br/>[xml.py]"]
  node_validation["Status sync"]
  node_analysis["Analysis sync<br/>[analysis.py]"]
end

subgraph group_support["Configuration and utilities"]
  node_config["Project config<br/>[config.py]"]
  node_singleton["Singleton<br/>[singleton.py]"]
  node_joins["List joins<br/>[joins.py]"]
  node_iterators["Chunking<br/>[iterators.py]"]
  node_text["Filename cleanup<br/>[text.py]"]
end

subgraph group_state["Transfer state"]
  node_attachments["Local attachments"]
end

node_operator(("Operator"))
node_source{{"Source project"}}
node_destination{{"Destination project"}}

node_operator -->|"runs"| node_runner
node_runner -->|"loads config"| node_config
node_config -->|"uses metaclass"| node_singleton
node_config -->|"validates access"| node_source
node_config -->|"validates access"| node_destination
node_runner -->|"lists UUIDs"| node_source
node_runner -->|"lists UUIDs"| node_destination
node_runner -->|"starts transfer"| node_asset
node_asset -->|"reads asset versions"| node_source
node_asset -->|"creates and deploys"| node_destination
node_asset -->|"downloads form media"| node_source
node_asset -->|"uploads form media"| node_destination
node_runner -->|"downloads attachments"| node_media
node_media -->|"fetches attachments"| node_source
node_media -->|"writes files"| node_attachments
node_runner -->|"transfers submissions"| node_xml
node_xml -->|"fetches submission XML"| node_source
node_xml -->|"posts submission XML"| node_destination
node_xml -->|"reads media files"| node_attachments
node_xml -->|"uses media cleanup"| node_media
node_xml -->|"cleans filenames"| node_text
node_runner -->|"syncs statuses"| node_validation
node_validation -->|"reads statuses"| node_source
node_validation -->|"updates statuses"| node_destination
node_validation -->|"joins submissions"| node_joins
node_validation -->|"chunks updates"| node_iterators
node_runner -->|"syncs analysis"| node_analysis
node_analysis -->|"reads analysis data"| node_source
node_analysis -->|"posts analysis data"| node_destination

click node_runner "https://github.com/kobotoolbox/kobo-transfer/blob/main/run.py"
click node_config "https://github.com/kobotoolbox/kobo-transfer/blob/main/helpers/config.py"
click node_singleton "https://github.com/kobotoolbox/kobo-transfer/blob/main/helpers/singleton.py"
click node_asset "https://github.com/kobotoolbox/kobo-transfer/blob/main/transfer/asset.py"
click node_media "https://github.com/kobotoolbox/kobo-transfer/blob/main/transfer/media.py"
click node_xml "https://github.com/kobotoolbox/kobo-transfer/blob/main/transfer/xml.py"
click node_validation "https://github.com/kobotoolbox/kobo-transfer/blob/main/transfer/validation_status.py"
click node_analysis "https://github.com/kobotoolbox/kobo-transfer/blob/main/transfer/analysis.py"
click node_joins "https://github.com/kobotoolbox/kobo-transfer/blob/main/utils/joins.py"
click node_iterators "https://github.com/kobotoolbox/kobo-transfer/blob/main/utils/iterators.py"
click node_text "https://github.com/kobotoolbox/kobo-transfer/blob/main/utils/text.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_runner toneBlue
class node_asset,node_media,node_xml,node_validation,node_analysis toneAmber
class node_config,node_singleton,node_joins,node_iterators,node_text toneMint
class node_attachments toneRose
class node_operator,node_source,node_destination toneIndigo
```

## Components

### CLI orchestration

- [CLI workflow](https://github.com/kobotoolbox/kobo-transfer/blob/main/run.py): `run.py`

### Transfer stages

- [Asset transfer](https://github.com/kobotoolbox/kobo-transfer/blob/main/transfer/asset.py): `transfer/asset.py`
- [Attachment transfer](https://github.com/kobotoolbox/kobo-transfer/blob/main/transfer/media.py): `transfer/media.py`
- [Submission XML](https://github.com/kobotoolbox/kobo-transfer/blob/main/transfer/xml.py): `transfer/xml.py`
- [Status sync](https://github.com/kobotoolbox/kobo-transfer/blob/main/transfer/validation_status.py): `transfer/validation_status.py`
- [Analysis sync](https://github.com/kobotoolbox/kobo-transfer/blob/main/transfer/analysis.py): `transfer/analysis.py`

### Configuration and utilities

- [Project config](https://github.com/kobotoolbox/kobo-transfer/blob/main/helpers/config.py): `helpers/config.py`
- [Singleton](https://github.com/kobotoolbox/kobo-transfer/blob/main/helpers/singleton.py): `helpers/singleton.py`
- [List joins](https://github.com/kobotoolbox/kobo-transfer/blob/main/utils/joins.py): `utils/joins.py`
- [Chunking](https://github.com/kobotoolbox/kobo-transfer/blob/main/utils/iterators.py): `utils/iterators.py`
- [Filename cleanup](https://github.com/kobotoolbox/kobo-transfer/blob/main/utils/text.py): `utils/text.py`

### Transfer state

- **Local attachments**

### Other components

- **Operator**
- **Source project**
- **Destination project**

## Connections

- Operator → CLI workflow: runs (evidence: `README.md`)
- CLI workflow → Project config: loads config (evidence: `run.py`)
- Project config → Singleton: uses metaclass (evidence: `helpers/config.py`)
- Project config → Source project: validates access (evidence: `helpers/config.py`)
- Project config → Destination project: validates access (evidence: `helpers/config.py`)
- CLI workflow → Source project: lists UUIDs (evidence: `run.py`)
- CLI workflow → Destination project: lists UUIDs (evidence: `run.py`)
- CLI workflow → Asset transfer: starts transfer (evidence: `run.py`)
- Asset transfer → Source project: reads asset versions (evidence: `transfer/asset.py`)
- Asset transfer → Destination project: creates and deploys (evidence: `transfer/asset.py`)
- Asset transfer → Source project: downloads form media (evidence: `transfer/asset.py`)
- Asset transfer → Destination project: uploads form media (evidence: `transfer/asset.py`)
- CLI workflow → Attachment transfer: downloads attachments (evidence: `run.py`)
- Attachment transfer → Source project: fetches attachments (evidence: `transfer/media.py`)
- Attachment transfer → Local attachments: writes files (evidence: `transfer/media.py`)
- CLI workflow → Submission XML: transfers submissions (evidence: `run.py`)
- Submission XML → Source project: fetches submission XML (evidence: `transfer/xml.py`)
- Submission XML → Destination project: posts submission XML (evidence: `transfer/xml.py`)
- Submission XML → Local attachments: reads media files (evidence: `transfer/xml.py`)
- Submission XML → Attachment transfer: uses media cleanup (evidence: `transfer/xml.py`)
- Submission XML → Filename cleanup: cleans filenames (evidence: `transfer/xml.py`)
- CLI workflow → Status sync: syncs statuses (evidence: `run.py`)
- Status sync → Source project: reads statuses (evidence: `transfer/validation_status.py`)
- Status sync → Destination project: updates statuses (evidence: `transfer/validation_status.py`)
- Status sync → List joins: joins submissions (evidence: `transfer/validation_status.py`)
- Status sync → Chunking: chunks updates (evidence: `transfer/validation_status.py`)
- CLI workflow → Analysis sync: syncs analysis (evidence: `run.py`)
- Analysis sync → Source project: reads analysis data (evidence: `transfer/analysis.py`)
- Analysis sync → Destination project: posts analysis data (evidence: `transfer/analysis.py`)
