# kobotoolbox/kobo-docker architecture

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

## Overview

kobo-docker packages the containers and configuration for running a self-hosted KoboToolbox survey platform. The principal workflow is a user reaching the frontend, where KPI, KoBoCAT and Enketo provide the platform’s application capabilities, backed by PostgreSQL, MongoDB and Redis. The README documents separate frontend and backend deployments, distinct KPI and KoBoCAT PostgreSQL databases, scheduled backups, and optional S3 storage. The graph preserves those documented capabilities; frontend request routing and maintenance behavior are not established by the excerpts, so those links are marked unverified.

Main entry points: [`docker-compose.frontend.yml`](https://github.com/kobotoolbox/kobo-docker/blob/master/docker-compose.frontend.yml) (NGINX), [`postgres/scripts/backup-to-s3.py`](https://github.com/kobotoolbox/kobo-docker/blob/master/postgres/scripts/backup-to-s3.py) (PostgreSQL backup), [`mongo/backup-to-s3.py`](https://github.com/kobotoolbox/kobo-docker/blob/master/mongo/backup-to-s3.py) (MongoDB backup), [`redis/backup-to-s3.py`](https://github.com/kobotoolbox/kobo-docker/blob/master/redis/backup-to-s3.py) (Redis backup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend services"]
  node_nginx["NGINX"]
  node_kpi["KPI"]
  node_kobocat["KoBoCAT"]
  node_enketo["Enketo Express"]
end

subgraph group_backend["Backend services"]
  node_mongo[("MongoDB")]
  node_postgres_kpi[("KPI PostgreSQL")]
  node_postgres_kc[("KoBoCAT PostgreSQL")]
  node_redis[("Redis")]
end

subgraph group_backup["Backup services"]
  node_mongo_backup["MongoDB backup<br/>[backup-to-s3.py]"]
  node_postgres_backup["PostgreSQL backup<br/>[backup-to-s3.py]"]
  node_redis_backup["Redis backup<br/>[backup-to-s3.py]"]
  node_kobocat_media_backup["KoBoCAT media backup"]
end

subgraph group_maintenance["Maintenance"]
  node_maintenance_config["Maintenance configuration"]
  node_maintenance_nginx["Maintenance page<br/>[index.html.tmpl]"]
end

node_user(("Platform user"))
node_s3[("AWS S3")]

node_user -.->|"accesses"| node_nginx
node_nginx -.->|"routes requests"| node_kpi
node_nginx -.->|"routes requests"| node_kobocat
node_nginx -.->|"routes requests"| node_enketo
node_mongo_backup -->|"backs up"| node_mongo
node_postgres_backup -->|"backs up"| node_postgres_kpi
node_postgres_backup -->|"backs up"| node_postgres_kc
node_redis_backup -->|"backs up"| node_redis
node_kobocat_media_backup -->|"backs up media"| node_kobocat
node_mongo_backup -.->|"uploads optionally"| node_s3
node_postgres_backup -.->|"uploads optionally"| node_s3
node_redis_backup -.->|"uploads optionally"| node_s3
node_maintenance_config -.->|"serves"| node_maintenance_nginx

click node_nginx "https://github.com/kobotoolbox/kobo-docker/blob/master/docker-compose.frontend.yml"
click node_kpi "https://github.com/kobotoolbox/kobo-docker/blob/master/docker-compose.frontend.yml"
click node_kobocat "https://github.com/kobotoolbox/kobo-docker/blob/master/docker-compose.frontend.yml"
click node_enketo "https://github.com/kobotoolbox/kobo-docker/blob/master/docker-compose.frontend.yml"
click node_mongo "https://github.com/kobotoolbox/kobo-docker/blob/master/docker-compose.backend.yml"
click node_postgres_kpi "https://github.com/kobotoolbox/kobo-docker/blob/master/docker-compose.backend.yml"
click node_postgres_kc "https://github.com/kobotoolbox/kobo-docker/blob/master/docker-compose.backend.yml"
click node_redis "https://github.com/kobotoolbox/kobo-docker/blob/master/docker-compose.backend.yml"
click node_mongo_backup "https://github.com/kobotoolbox/kobo-docker/blob/master/mongo/backup-to-s3.py"
click node_postgres_backup "https://github.com/kobotoolbox/kobo-docker/blob/master/postgres/scripts/backup-to-s3.py"
click node_redis_backup "https://github.com/kobotoolbox/kobo-docker/blob/master/redis/backup-to-s3.py"
click node_kobocat_media_backup "https://github.com/kobotoolbox/kobo-docker/blob/master/docker-compose.frontend.yml"
click node_maintenance_config "https://github.com/kobotoolbox/kobo-docker/blob/master/docker-compose.maintenance.yml"
click node_maintenance_nginx "https://github.com/kobotoolbox/kobo-docker/blob/master/nginx/maintenance/index.html.tmpl"

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_nginx,node_kpi,node_kobocat,node_enketo,node_user toneBlue
class node_mongo,node_postgres_kpi,node_postgres_kc,node_redis,node_s3 toneAmber
class node_mongo_backup,node_postgres_backup,node_redis_backup,node_kobocat_media_backup toneMint
class node_maintenance_config,node_maintenance_nginx toneRose
```

## Components

### Frontend services

- [NGINX](https://github.com/kobotoolbox/kobo-docker/blob/master/docker-compose.frontend.yml): `docker-compose.frontend.yml`
- [KPI](https://github.com/kobotoolbox/kobo-docker/blob/master/docker-compose.frontend.yml): `docker-compose.frontend.yml`
- [KoBoCAT](https://github.com/kobotoolbox/kobo-docker/blob/master/docker-compose.frontend.yml): `docker-compose.frontend.yml`
- [Enketo Express](https://github.com/kobotoolbox/kobo-docker/blob/master/docker-compose.frontend.yml): `docker-compose.frontend.yml`

### Backend services

- [MongoDB](https://github.com/kobotoolbox/kobo-docker/blob/master/docker-compose.backend.yml): `docker-compose.backend.yml`
- [KPI PostgreSQL](https://github.com/kobotoolbox/kobo-docker/blob/master/docker-compose.backend.yml): `docker-compose.backend.yml`
- [KoBoCAT PostgreSQL](https://github.com/kobotoolbox/kobo-docker/blob/master/docker-compose.backend.yml): `docker-compose.backend.yml`
- [Redis](https://github.com/kobotoolbox/kobo-docker/blob/master/docker-compose.backend.yml): `docker-compose.backend.yml`

### Backup services

- [MongoDB backup](https://github.com/kobotoolbox/kobo-docker/blob/master/mongo/backup-to-s3.py): `mongo/backup-to-s3.py`
- [PostgreSQL backup](https://github.com/kobotoolbox/kobo-docker/blob/master/postgres/scripts/backup-to-s3.py): `postgres/scripts/backup-to-s3.py`
- [Redis backup](https://github.com/kobotoolbox/kobo-docker/blob/master/redis/backup-to-s3.py): `redis/backup-to-s3.py`
- [KoBoCAT media backup](https://github.com/kobotoolbox/kobo-docker/blob/master/docker-compose.frontend.yml): `docker-compose.frontend.yml`

### Maintenance

- [Maintenance configuration](https://github.com/kobotoolbox/kobo-docker/blob/master/docker-compose.maintenance.yml): `docker-compose.maintenance.yml`
- [Maintenance page](https://github.com/kobotoolbox/kobo-docker/blob/master/nginx/maintenance/index.html.tmpl): `nginx/maintenance/index.html.tmpl`

### Other components

- **Platform user**
- **AWS S3**

## Connections

- Platform user → NGINX: accesses
- NGINX → KPI: routes requests
- NGINX → KoBoCAT: routes requests
- NGINX → Enketo Express: routes requests
- MongoDB backup → MongoDB: backs up (evidence: `README.md`)
- PostgreSQL backup → KPI PostgreSQL: backs up (evidence: `README.md`)
- PostgreSQL backup → KoBoCAT PostgreSQL: backs up (evidence: `README.md`)
- Redis backup → Redis: backs up (evidence: `README.md`)
- KoBoCAT media backup → KoBoCAT: backs up media (evidence: `README.md`)
- MongoDB backup → AWS S3: uploads optionally (evidence: `README.md`)
- PostgreSQL backup → AWS S3: uploads optionally (evidence: `README.md`)
- Redis backup → AWS S3: uploads optionally (evidence: `README.md`)
- Maintenance configuration → Maintenance page: serves
