# kobotoolbox/collect architecture

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

- Interactive diagram: https://gitdiagram.com/kobotoolbox/collect
- Repository: https://github.com/kobotoolbox/collect

## Overview

1. **Overall shape**
   KoboCollect is a large Android monorepo built as many Gradle modules. The main application is `collect_app`, and most functionality is split into reusable feature/library modules so the app can be assembled from shared building blocks.

2. **Primary runtime**
   The product runs as an Android app using a mix of Kotlin and Java, with Activities, Fragments, ViewModels, and Android services as the top-level UI/runtime boundary. Dependency injection is used heavily through Dagger setup classes in multiple modules.

3. **Core product flow**
   The center of the architecture is form collection: users download blank forms, fill them out, save drafts, finalize submissions, and upload instances. That flow crosses several modules: form management, form entry, instance management, saving/finalization, and network sync.

4. **Form system**
   The `forms`, `forms-test`, and `test-forms` modules define the shared form model and test fixtures. In the app, form parsing, loading, hierarchy rendering, widgets, media handling, and validation live under `collect_app/src/main/java/org/odk/collect/android/formentry`, `widgets`, `formhierarchy`, and `formmanagement`.

5. **Local persistence boundary**
   Local data is split into repositories over SQLite and app settings over shared preferences. The `db` module provides low-level SQLite helpers/migrations, while app repositories such as forms, instances, savepoints, entities, and projects wrap the database or settings store behind domain-friendly APIs.

6. **Projects and settings**
   A “project” is a first-class boundary in the app. The `projects` and `settings` modules handle project creation, migration, configuration import, server credentials, and preference schemas. The app’s project-aware behavior is driven by these modules rather than hardcoded global state.

7. **Server communication**
   Network interaction is centered on OpenRosa/ODK-style endpoints. The `open-rosa` module provides HTTP and XML fetching/parsing, while `collect_app` uses it for form discovery, download, and instance upload. This boundary separates protocol handling from app-specific form/instance logic.

8. **Background work and sync**
   Sync-like tasks are handled asynchronously rather than inline with the UI. The `async` module provides scheduler abstractions and WorkManager/coroutine integration, and `collect_app/backgroundwork` wires these into form updates, instance submission, and recurring maintenance jobs.

9. **Media, sensors, and device capabilities**
   Several features are device-centric and isolated into modules: `location` for GPS tracking, `audio-recorder` and `audio-clips` for recording/playback, `selfie-camera` for capture, `draw` for annotation, `qr-code` for scanning/encoding, and `geo`/`maps` for map-based question input. These modules keep hardware-specific logic separate from core form flows.

10. **Maps and geo rendering**
    Map support is abstracted behind `maps`, with concrete providers in `google-maps`, `mapbox`, and `osmdroid`. The app chooses a map implementation through configurator/factory layers, so geo questions can render against different backends without changing the higher-level form logic.

11. **Cross-cutting utilities**
    Shared foundations live in modules like `shared`, `androidshared`, `material`, `lists`, `image-loader`, `permissions`, `analytics`, `metadata`, `external-app`, `notifications`, and `strings`. These contain reusable UI widgets, file/path utilities, permissions checks, localization, analytics wrappers, and generic result/lock helpers used across the app.

12. **External integration surfaces**
    The app exposes Android activities, content providers, and intent-based entry points for other apps and system flows. Modules such as `external-app`, `web-page`, `errors`, and `crash-handler` represent boundaries for external launch, browser/web content, error display, and crash handling.

13. **Entities and specialized workflows**
    Entities are a separate product capability with their own storage, parsing, and browser UI in the `entities` module, plus app-side integration under `collect_app/entities`. This is a distinct flow from ordinary form submissions and has its own parse/finalize/filter pipeline.

14. **Testing architecture**
    The repo is test-heavy and organized by module. It includes Robolectric/unit tests per module, Android instrumented tests in `collect_app/src/androidTest`, reusable test helpers in `test-shared`, and dedicated fixture modules like `test-forms` and `forms-test` to keep product behavior testable across the monorepo.

Main entry points: [`collect_app`](https://github.com/kobotoolbox/collect/tree/master/collect_app) (Collect app), [`collect_app/src/main/java/org/odk/collect/android/formentry`](https://github.com/kobotoolbox/collect/tree/master/collect_app/src/main/java/org/odk/collect/android/formentry) (Form entry), [`forms`](https://github.com/kobotoolbox/collect/tree/master/forms) (Forms API), [`geo`](https://github.com/kobotoolbox/collect/tree/master/geo) (Geo input)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Android app"]
  node_collect_app["Collect app<br/>android app"]
  node_formmanagement["Form mgmt<br/>app feature"]
  node_formentry["Form entry<br/>app feature"]
  node_instancemanagement["Instances<br/>app feature"]
  node_projects["Projects<br/>app feature"]
  node_preferences["Settings UI<br/>app feature"]
  node_backgroundwork["Background work<br/>app feature"]
  node_mainmenu["Main menu<br/>app feature"]
  node_entities_app["Entities<br/>app feature"]
end

subgraph group_core["Core libraries"]
  node_db[("SQLite core")]
  node_forms["Forms API<br/>domain library"]
  node_projects_lib["Projects API<br/>domain library"]
  node_settings_lib["Settings API<br/>domain library"]
  node_openrosa["OpenRosa<br/>protocol library"]
  node_async_lib["Async core<br/>runtime library"]
  node_shared_lib["Shared utils<br/>common library"]
  node_androidshared["Android shared<br/>android utility lib"]
end

subgraph group_features["Feature modules"]
  node_maps["Maps core<br/>map library"]
  node_geo["Geo input<br/>feature module"]
  node_location["Location<br/>device library"]
  node_audio["Audio<br/>feature module"]
  node_qr["QR code<br/>feature module"]
  node_media_ui["Media capture<br/>feature module"]
end

subgraph group_test["Test support"]
  node_test_shared["Test shared<br/>test support"]
  node_forms_test["Form fixtures<br/>test data"]
end

node_collect_app -->|"owns"| node_formmanagement
node_collect_app -->|"owns"| node_formentry
node_collect_app -->|"owns"| node_instancemanagement
node_collect_app -->|"owns"| node_projects
node_collect_app -->|"owns"| node_preferences
node_collect_app -->|"schedules"| node_backgroundwork
node_collect_app -->|"starts"| node_mainmenu
node_collect_app -->|"integrates"| node_entities_app
node_formmanagement -->|"fetches forms"| node_openrosa
node_formmanagement -->|"uses"| node_forms
node_formentry -->|"loads forms"| node_forms
node_formentry -->|"uses"| node_location
node_formentry -->|"uses"| node_audio
node_formentry -->|"uses"| node_qr
node_formentry -->|"renders"| node_geo
node_instancemanagement -->|"persists instances"| node_forms
node_instancemanagement -->|"uploads instances"| node_openrosa
node_projects -->|"wraps"| node_projects_lib
node_preferences -->|"reads schema"| node_settings_lib
node_preferences -->|"applies"| node_projects_lib
node_backgroundwork -->|"uses"| node_async_lib
node_backgroundwork -->|"syncs"| node_openrosa
node_mainmenu -->|"depends on"| node_projects_lib
node_entities_app -->|"extends"| node_forms
node_entities_app -.->|"hooks into"| node_collect_app
node_db -->|"backing store"| node_forms
node_db -->|"backing store"| node_projects_lib
node_db -->|"supports migrations"| node_settings_lib
node_androidshared -->|"builds on"| node_shared_lib
node_maps -->|"renders map input"| node_geo
node_geo -->|"tracks position"| node_location
node_geo -->|"uses maps"| node_maps
node_qr -.->|"used by"| node_collect_app
node_audio -.->|"used by"| node_collect_app
node_media_ui -.->|"used by"| node_collect_app
node_test_shared -.->|"supports tests"| node_collect_app
node_forms_test -.->|"fixtures for"| node_forms

click node_collect_app "https://github.com/kobotoolbox/collect/tree/master/collect_app"
click node_formmanagement "https://github.com/kobotoolbox/collect/tree/master/collect_app/src/main/java/org/odk/collect/android/formmanagement"
click node_formentry "https://github.com/kobotoolbox/collect/tree/master/collect_app/src/main/java/org/odk/collect/android/formentry"
click node_instancemanagement "https://github.com/kobotoolbox/collect/tree/master/collect_app/src/main/java/org/odk/collect/android/instancemanagement"
click node_projects "https://github.com/kobotoolbox/collect/tree/master/collect_app/src/main/java/org/odk/collect/android/projects"
click node_preferences "https://github.com/kobotoolbox/collect/tree/master/collect_app/src/main/java/org/odk/collect/android/preferences"
click node_backgroundwork "https://github.com/kobotoolbox/collect/tree/master/collect_app/src/main/java/org/odk/collect/android/backgroundwork"
click node_mainmenu "https://github.com/kobotoolbox/collect/tree/master/collect_app/src/main/java/org/odk/collect/android/mainmenu"
click node_entities_app "https://github.com/kobotoolbox/collect/tree/master/collect_app/src/main/java/org/odk/collect/android/entities"
click node_db "https://github.com/kobotoolbox/collect/tree/master/db"
click node_forms "https://github.com/kobotoolbox/collect/tree/master/forms"
click node_projects_lib "https://github.com/kobotoolbox/collect/tree/master/projects"
click node_settings_lib "https://github.com/kobotoolbox/collect/tree/master/settings"
click node_openrosa "https://github.com/kobotoolbox/collect/tree/master/open-rosa"
click node_async_lib "https://github.com/kobotoolbox/collect/tree/master/async"
click node_shared_lib "https://github.com/kobotoolbox/collect/tree/master/shared"
click node_androidshared "https://github.com/kobotoolbox/collect/tree/master/androidshared"
click node_maps "https://github.com/kobotoolbox/collect/tree/master/maps"
click node_geo "https://github.com/kobotoolbox/collect/tree/master/geo"
click node_location "https://github.com/kobotoolbox/collect/tree/master/location"
click node_audio "https://github.com/kobotoolbox/collect/tree/master/audio-recorder"
click node_qr "https://github.com/kobotoolbox/collect/tree/master/qr-code"
click node_media_ui "https://github.com/kobotoolbox/collect/tree/master/selfie-camera"
click node_test_shared "https://github.com/kobotoolbox/collect/tree/master/test-shared"
click node_forms_test "https://github.com/kobotoolbox/collect/tree/master/forms-test"

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_collect_app,node_formmanagement,node_formentry,node_instancemanagement,node_projects,node_preferences,node_backgroundwork,node_mainmenu,node_entities_app toneBlue
class node_db,node_forms,node_projects_lib,node_settings_lib,node_openrosa,node_async_lib,node_shared_lib,node_androidshared toneAmber
class node_maps,node_geo,node_location,node_audio,node_qr,node_media_ui toneMint
class node_test_shared,node_forms_test toneRose
```

## Components

### Android app

Main Collect application and its in-app subsystems.

- [Collect app](https://github.com/kobotoolbox/collect/tree/master/collect_app): android app · Main Android application shell, UI, flows, initialization, and feature wiring. · `collect_app`
- [Form mgmt](https://github.com/kobotoolbox/collect/tree/master/collect_app/src/main/java/org/odk/collect/android/formmanagement): app feature · Coordinates blank-form discovery, download, metadata, and finalization. · `collect_app/src/main/java/org/odk/collect/android/formmanagement`
- [Form entry](https://github.com/kobotoolbox/collect/tree/master/collect_app/src/main/java/org/odk/collect/android/formentry): app feature · Runs the form-filling session, widgets, validation, saving, and end-of-form logic. · `collect_app/src/main/java/org/odk/collect/android/formentry`
- [Instances](https://github.com/kobotoolbox/collect/tree/master/collect_app/src/main/java/org/odk/collect/android/instancemanagement): app feature · Handles drafts, finalization, submission, deletion, and autosend. · `collect_app/src/main/java/org/odk/collect/android/instancemanagement`
- [Projects](https://github.com/kobotoolbox/collect/tree/master/collect_app/src/main/java/org/odk/collect/android/projects): app feature · Project creation, reset, deletion, and project-specific settings flow. · `collect_app/src/main/java/org/odk/collect/android/projects`
- [Settings UI](https://github.com/kobotoolbox/collect/tree/master/collect_app/src/main/java/org/odk/collect/android/preferences): app feature · Project and app preference screens, dialogs, and preference wiring. · `collect_app/src/main/java/org/odk/collect/android/preferences`
- [Background work](https://github.com/kobotoolbox/collect/tree/master/collect_app/src/main/java/org/odk/collect/android/backgroundwork): app feature · App-side schedulers and task specs for sync, updates, and maintenance jobs. · `collect_app/src/main/java/org/odk/collect/android/backgroundwork`
- [Main menu](https://github.com/kobotoolbox/collect/tree/master/collect_app/src/main/java/org/odk/collect/android/mainmenu): app feature · Home screen, permissions gate, and primary navigation into the app. · `collect_app/src/main/java/org/odk/collect/android/mainmenu`
- [Entities](https://github.com/kobotoolbox/collect/tree/master/collect_app/src/main/java/org/odk/collect/android/entities): app feature · App integration for entity parsing, finalization, and browser UI. · `collect_app/src/main/java/org/odk/collect/android/entities`

### Core libraries

Reusable libraries that define shared domain, storage, protocol, and infrastructure.

- [SQLite core](https://github.com/kobotoolbox/collect/tree/master/db): library · Low-level SQLite helpers, migrations, and database connection primitives. · `db`
- [Forms API](https://github.com/kobotoolbox/collect/tree/master/forms): domain library · Shared form, instance, and savepoint domain model and repository interfaces. · `forms`
- [Projects API](https://github.com/kobotoolbox/collect/tree/master/projects): domain library · Project model, repository, and configuration abstractions. · `projects`
- [Settings API](https://github.com/kobotoolbox/collect/tree/master/settings): domain library · Settings schemas, migrations, validation, and import/export helpers. · `settings`
- [OpenRosa](https://github.com/kobotoolbox/collect/tree/master/open-rosa): protocol library · HTTP/XML client and parser for OpenRosa-style server communication. · `open-rosa`
- [Async core](https://github.com/kobotoolbox/collect/tree/master/async): runtime library · Coroutine and WorkManager scheduler abstractions plus network state helpers. · `async`
- [Shared utils](https://github.com/kobotoolbox/collect/tree/master/shared): common library · Pure shared utilities for files, strings, result types, locks, and collections. · `shared`
- [Android shared](https://github.com/kobotoolbox/collect/tree/master/androidshared): android utility lib · Reusable Android utilities for UI, system integration, bitmaps, and lifecycle helpers. · `androidshared`

### Feature modules

Optional or specialized runtime modules assembled into the app.

- [Maps core](https://github.com/kobotoolbox/collect/tree/master/maps): map library · Map abstractions, fragments, view models, markers, and offline layer support. · `maps`
- [Geo input](https://github.com/kobotoolbox/collect/tree/master/geo): feature module · Geopoint and geopoly capture UI and location-aware question workflows. · `geo`
- [Location](https://github.com/kobotoolbox/collect/tree/master/location): device library · Location client abstraction, fused/GPS providers, and tracking services. · `location`
- [Audio](https://github.com/kobotoolbox/collect/tree/master/audio-recorder): feature module · Audio recording and playback feature modules for form questions. · `audio-recorder`
- [QR code](https://github.com/kobotoolbox/collect/tree/master/qr-code): feature module · Barcode scanning and QR generation/decoding for configuration and form input. · `qr-code`
- [Media capture](https://github.com/kobotoolbox/collect/tree/master/selfie-camera): feature module · Selfie capture, drawing, image loading, printing, and other media-related capabilities. · `selfie-camera`

### Test support

Shared fixtures and cross-module test helpers.

- [Test shared](https://github.com/kobotoolbox/collect/tree/master/test-shared): test support · Reusable test fixtures, matchers, fake schedulers, and activity helpers. · `test-shared`
- [Form fixtures](https://github.com/kobotoolbox/collect/tree/master/forms-test): test data · Reusable form and instance fixtures for module-level tests. · `forms-test`

## Connections

- Collect app → Form mgmt: owns · App wires the form management flow.
- Collect app → Form entry: owns · App hosts the form entry runtime.
- Collect app → Instances: owns · App hosts draft and submission flows.
- Collect app → Projects: owns · App hosts project management.
- Collect app → Settings UI: owns · App renders settings and preference screens.
- Collect app → Background work: schedules · App triggers async sync and maintenance jobs.
- Collect app → Main menu: starts · Main menu is the entry point.
- Collect app → Entities: integrates · App exposes entity workflows.
- Form mgmt → OpenRosa: fetches forms · Downloads form lists and form files.
- Form mgmt → Forms API: uses · Operates on form domain objects.
- Form entry → Forms API: loads forms · Consumes form model and savepoints.
- Form entry → Location: uses · Supports geopoint and background location questions.
- Form entry → Audio: uses · Supports audio questions and recording.
- Form entry → QR code: uses · Supports barcode and QR question types.
- Form entry → Geo input: renders · Opens geo input screens and map questions.
- Instances → Forms API: persists instances · Tracks drafts, instances, and savepoints.
- Instances → OpenRosa: uploads instances · Submits finalized instances to server endpoints.
- Projects → Projects API: wraps · App-specific project UI sits on project domain APIs.
- Settings UI → Settings API: reads schema · Preferences are driven by settings definitions and migrations.
- Settings UI → Projects API: applies · Project-specific settings are stored and migrated per project.
- Background work → Async core: uses · Background jobs run through scheduler abstractions.
- Background work → OpenRosa: syncs · Background tasks call server communication paths.
- Main menu → Projects API: depends on · Menu shows and switches current project.
- Entities → Forms API: extends · Entity workflows build on form and finalization concepts.
- Entities → Collect app: hooks into · App-side entity integration joins the main runtime.
- SQLite core → Forms API: backing store · Forms repositories sit on SQLite helpers and migrations.
- SQLite core → Projects API: backing store · Project state can be persisted through shared database helpers.
- SQLite core → Settings API: supports migrations · Settings import/migration logic works with stored data.
- Android shared → Shared utils: builds on · Android utilities complement common shared primitives.
- Maps core → Geo input: renders map input · Map abstractions power geo question UIs.
- Geo input → Location: tracks position · Geo workflows depend on location providers and tracking.
- Geo input → Maps core: uses maps · Geo input delegates to map abstractions and providers.
- QR code → Collect app: used by · App configuration and form entry launch scanner flows.
- Audio → Collect app: used by · App embeds recorder and player flows in form entry.
- Media capture → Collect app: used by · Media-related capabilities surface through the app.
- Test shared → Collect app: supports tests · Shared test helpers are consumed by app tests.
- Form fixtures → Forms API: fixtures for · Reusable sample forms and repositories support core form tests.