# kobotoolbox/kpi architecture

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

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

## Overview

KPI is the KoboToolbox platform for authoring and managing data-collection projects, handling submissions, and administering accounts and service usage. The visible frontend includes account, organization, security, billing, and usage interfaces; the README also documents a versioned API and submission filtering. The sampled backend code shows submission-query construction against Mongo-backed parsed instances and storage abstractions spanning filesystem, S3, and Azure. Several product areas are documented or apparent from the tree but their internal wiring was not sampled, so uncertain links are omitted.

Main entry points: [`jsapp/js/account/routes.tsx`](https://github.com/kobotoolbox/kpi/blob/main/jsapp/js/account/routes.tsx) (Account routes), [`kobo/apps/openrosa/apps/logger/utils/database_query.py`](https://github.com/kobotoolbox/kpi/blob/main/kobo/apps/openrosa/apps/logger/utils/database_query.py) (Submission query builder), [`kpi/deployment_backends/kc_access/storage.py`](https://github.com/kobotoolbox/kpi/blob/main/kpi/deployment_backends/kc_access/storage.py) (Attachment storage), [`kpi/utils/storage.py`](https://github.com/kobotoolbox/kpi/blob/main/kpi/utils/storage.py) (Storage operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web interface"]
  node_account_routes["Account routes<br/>[routes.tsx]"]
  node_account_settings["Account settings"]
  node_org_members["Organization members<br/>[MembersRoute.tsx]"]
  node_security["Security settings"]
  node_usage["Service usage<br/>[usageContainer.tsx]"]
  node_usage_summary["Usage summary"]
end

subgraph group_api["API and submissions"]
  node_api_client["API client<br/>[api.ts]"]
  node_api_models["API models"]
  node_submission_actions["Submission actions<br/>[submissions.ts]"]
  node_query_builder["Submission query builder<br/>[database_query.py]"]
  node_parsed_instances[("Parsed instances<br/>[parsed_instance.py]")]
end

subgraph group_storage["Files and storage"]
  node_attachment_storage["Attachment storage<br/>[storage.py]"]
  node_storage_ops["Storage operations<br/>[storage.py]"]
  node_private_azure["Private Azure files"]
  node_private_access["Private file access<br/>[private_storage.py]"]
end

subgraph group_admin["Administration"]
  node_admin_site["Django admin"]
  node_account_models[("Account models")]
  node_storage_report["Attachment storage counters"]
end

node_user(("KoboToolbox user"))
node_postgres[("PostgreSQL records")]
node_filesystem[("Filesystem")]
node_s3[("S3 storage")]
node_azure[("Azure storage")]

node_user -->|"opens"| node_account_routes
node_account_routes -->|"routes to"| node_account_settings
node_account_routes -->|"routes to"| node_org_members
node_account_routes -->|"routes to"| node_security
node_account_routes -->|"routes to"| node_usage
node_usage -->|"loads summary"| node_usage_summary
node_usage_summary -->|"fetches usage"| node_api_client
node_api_client -->|"uses types"| node_api_models
node_submission_actions -->|"sends requests"| node_api_client
node_query_builder -->|"queries IDs"| node_parsed_instances
node_query_builder -->|"returns filters"| node_postgres
node_query_builder -->|"returns filters"| node_parsed_instances
node_storage_ops -->|"deletes files"| node_filesystem
node_storage_ops -->|"batch deletes"| node_s3
node_storage_ops -->|"batch deletes"| node_azure
node_attachment_storage -->|"selects backend"| node_s3
node_attachment_storage -->|"selects backend"| node_azure
node_attachment_storage -->|"selects backend"| node_filesystem
node_private_azure -->|"stores files"| node_azure
node_private_access -->|"checks asset permissions"| node_account_models
node_admin_site -->|"manages"| node_account_models
node_storage_report -->|"updates counters"| node_postgres

click node_account_routes "https://github.com/kobotoolbox/kpi/blob/main/jsapp/js/account/routes.tsx"
click node_account_settings "https://github.com/kobotoolbox/kpi/blob/main/jsapp/js/account/accountSettingsRoute.tsx"
click node_org_members "https://github.com/kobotoolbox/kpi/blob/main/jsapp/js/account/organization/MembersRoute.tsx"
click node_security "https://github.com/kobotoolbox/kpi/blob/main/jsapp/js/account/security/securityRoute.component.tsx"
click node_usage "https://github.com/kobotoolbox/kpi/blob/main/jsapp/js/account/usage/usageContainer.tsx"
click node_usage_summary "https://github.com/kobotoolbox/kpi/blob/main/jsapp/js/account/usage/useOrganizationsServiceUsageSummary.ts"
click node_api_client "https://github.com/kobotoolbox/kpi/blob/main/jsapp/js/api.ts"
click node_api_models "https://github.com/kobotoolbox/kpi/tree/main/jsapp/js/api/models"
click node_submission_actions "https://github.com/kobotoolbox/kpi/blob/main/jsapp/js/actions/submissions.ts"
click node_query_builder "https://github.com/kobotoolbox/kpi/blob/main/kobo/apps/openrosa/apps/logger/utils/database_query.py"
click node_parsed_instances "https://github.com/kobotoolbox/kpi/blob/main/kobo/apps/openrosa/apps/viewer/models/parsed_instance.py"
click node_attachment_storage "https://github.com/kobotoolbox/kpi/blob/main/kpi/deployment_backends/kc_access/storage.py"
click node_storage_ops "https://github.com/kobotoolbox/kpi/blob/main/kpi/utils/storage.py"
click node_private_azure "https://github.com/kobotoolbox/kpi/blob/main/kobo/apps/storage_backends/private_azure_storage.py"
click node_private_access "https://github.com/kobotoolbox/kpi/blob/main/kpi/utils/private_storage.py"
click node_admin_site "https://github.com/kobotoolbox/kpi/tree/main/hub/admin"
click node_account_models "https://github.com/kobotoolbox/kpi/tree/main/hub/models"
click node_storage_report "https://github.com/kobotoolbox/kpi/blob/main/kobo/apps/openrosa/apps/logger/management/commands/update_attachment_storage_bytes.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_account_routes,node_account_settings,node_org_members,node_security,node_usage,node_usage_summary,node_user toneBlue
class node_api_client,node_api_models,node_submission_actions,node_query_builder,node_parsed_instances,node_postgres,node_filesystem,node_s3,node_azure toneAmber
class node_attachment_storage,node_storage_ops,node_private_azure,node_private_access toneMint
class node_admin_site,node_account_models,node_storage_report toneRose
```

## Components

### Web interface

- [Account routes](https://github.com/kobotoolbox/kpi/blob/main/jsapp/js/account/routes.tsx): `jsapp/js/account/routes.tsx`
- [Account settings](https://github.com/kobotoolbox/kpi/blob/main/jsapp/js/account/accountSettingsRoute.tsx): `jsapp/js/account/accountSettingsRoute.tsx`
- [Organization members](https://github.com/kobotoolbox/kpi/blob/main/jsapp/js/account/organization/MembersRoute.tsx): `jsapp/js/account/organization/MembersRoute.tsx`
- [Security settings](https://github.com/kobotoolbox/kpi/blob/main/jsapp/js/account/security/securityRoute.component.tsx): `jsapp/js/account/security/securityRoute.component.tsx`
- [Service usage](https://github.com/kobotoolbox/kpi/blob/main/jsapp/js/account/usage/usageContainer.tsx): `jsapp/js/account/usage/usageContainer.tsx`
- [Usage summary](https://github.com/kobotoolbox/kpi/blob/main/jsapp/js/account/usage/useOrganizationsServiceUsageSummary.ts): `jsapp/js/account/usage/useOrganizationsServiceUsageSummary.ts`

### API and submissions

- [API client](https://github.com/kobotoolbox/kpi/blob/main/jsapp/js/api.ts): `jsapp/js/api.ts`
- [API models](https://github.com/kobotoolbox/kpi/tree/main/jsapp/js/api/models): `jsapp/js/api/models`
- [Submission actions](https://github.com/kobotoolbox/kpi/blob/main/jsapp/js/actions/submissions.ts): `jsapp/js/actions/submissions.ts`
- [Submission query builder](https://github.com/kobotoolbox/kpi/blob/main/kobo/apps/openrosa/apps/logger/utils/database_query.py): `kobo/apps/openrosa/apps/logger/utils/database_query.py`
- [Parsed instances](https://github.com/kobotoolbox/kpi/blob/main/kobo/apps/openrosa/apps/viewer/models/parsed_instance.py): `kobo/apps/openrosa/apps/viewer/models/parsed_instance.py`

### Files and storage

- [Attachment storage](https://github.com/kobotoolbox/kpi/blob/main/kpi/deployment_backends/kc_access/storage.py): `kpi/deployment_backends/kc_access/storage.py`
- [Storage operations](https://github.com/kobotoolbox/kpi/blob/main/kpi/utils/storage.py): `kpi/utils/storage.py`
- [Private Azure files](https://github.com/kobotoolbox/kpi/blob/main/kobo/apps/storage_backends/private_azure_storage.py): `kobo/apps/storage_backends/private_azure_storage.py`
- [Private file access](https://github.com/kobotoolbox/kpi/blob/main/kpi/utils/private_storage.py): `kpi/utils/private_storage.py`

### Administration

- [Django admin](https://github.com/kobotoolbox/kpi/tree/main/hub/admin): `hub/admin`
- [Account models](https://github.com/kobotoolbox/kpi/tree/main/hub/models): `hub/models`
- [Attachment storage counters](https://github.com/kobotoolbox/kpi/blob/main/kobo/apps/openrosa/apps/logger/management/commands/update_attachment_storage_bytes.py): `kobo/apps/openrosa/apps/logger/management/commands/update_attachment_storage_bytes.py`

### Other components

- **KoboToolbox user**
- **PostgreSQL records**
- **Filesystem**
- **S3 storage**
- **Azure storage**

## Connections

- KoboToolbox user → Account routes: opens
- Account routes → Account settings: routes to
- Account routes → Organization members: routes to
- Account routes → Security settings: routes to
- Account routes → Service usage: routes to
- Service usage → Usage summary: loads summary
- Usage summary → API client: fetches usage
- API client → API models: uses types
- Submission actions → API client: sends requests
- Submission query builder → Parsed instances: queries IDs
- Submission query builder → PostgreSQL records: returns filters
- Submission query builder → Parsed instances: returns filters
- Storage operations → Filesystem: deletes files
- Storage operations → S3 storage: batch deletes
- Storage operations → Azure storage: batch deletes
- Attachment storage → S3 storage: selects backend
- Attachment storage → Azure storage: selects backend
- Attachment storage → Filesystem: selects backend
- Private Azure files → Azure storage: stores files
- Private file access → Account models: checks asset permissions
- Django admin → Account models: manages
- Attachment storage counters → PostgreSQL records: updates counters