kobotoolbox/collect

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.