# kiwix/operations architecture

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

- Interactive diagram: https://gitdiagram.com/kiwix/operations
- Repository: https://github.com/kiwix/operations

## Overview

This repository deploys and maintains Kiwix’s Kubernetes infrastructure: users reach hosted library and download services, while cluster workloads also support content distribution and operational services. The graph preserves those major product areas and selected maintenance functions. The README establishes the repository’s infrastructure scope; sampled source confirms the tracker-whitelisting and resource-overview behaviors. Most workload wiring is represented only by manifest filenames in the supplied evidence, so uncertain service-to-service links are omitted.

Main entry points: [`zim/library`](https://github.com/kiwix/operations/tree/main/zim/library) (ZIM library), [`zim/load-balancer`](https://github.com/kiwix/operations/tree/main/zim/load-balancer) (Mirror load balancer), [`bittorrent/whitelister.py`](https://github.com/kiwix/operations/blob/main/bittorrent/whitelister.py) (Torrent whitelister), [`zim/download-kiwix`](https://github.com/kiwix/operations/tree/main/zim/download-kiwix) (Download services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_content["Content delivery"]
  node_library["ZIM library"]
  node_downloads["Download services"]
  node_openzim_downloads["OpenZIM downloads"]
  node_mirror_lb["Mirror load balancer"]
  node_master_mirror["Master mirror"]
  node_tracker["BitTorrent tracker<br/>[tracker.yaml]"]
  node_whitelister["Torrent whitelister<br/>[whitelister.py]"]
  node_catalog["Kiwix catalog"]
end

subgraph group_platform["Platform services"]
  node_login["Login service<br/>[login.yaml]"]
  node_drives["Drive service<br/>[drives.yaml]"]
end

subgraph group_apps["Hosted applications"]
  node_cms["CMS services<br/>[api.yaml]"]
  node_cardshop["Cardshop<br/>[api.yaml]"]
  node_nautilus["Nautilus<br/>[api.yaml]"]
  node_zimfarm["ZIMfarm<br/>[api.yaml]"]
  node_zimit["Zimit<br/>[api.yaml]"]
  node_mirrors_qa["Mirror QA<br/>[api.yaml]"]
  node_wiki["Wikis"]
end

subgraph group_operations["Operations"]
  node_stats["Web analytics<br/>[matomo-app.yaml]"]
  node_overview["Resource overview<br/>[build-overview.py]"]
  node_cluster_backup["Cluster backup"]
end

subgraph group_cluster["Cluster foundation"]
  node_kubernetes{{"Kubernetes cluster"}}
end

node_visitors(("Visitors"))
node_external_mirrors(("External mirrors"))

node_visitors -->|"browse"| node_library
node_visitors -->|"download"| node_downloads
node_visitors -->|"download"| node_openzim_downloads
node_visitors -->|"access"| node_cms
node_visitors -->|"access"| node_zimfarm
node_visitors -->|"access"| node_zimit
node_library -->|"serves catalog"| node_catalog
node_whitelister -->|"fetches OPDS"| node_catalog
node_whitelister -->|"updates whitelist"| node_tracker
node_external_mirrors -->|"mirror content"| node_mirror_lb
node_master_mirror -->|"syncs content"| node_mirror_lb
node_kubernetes -->|"runs workload"| node_library
node_kubernetes -->|"runs workload"| node_downloads
node_kubernetes -->|"runs workload"| node_openzim_downloads
node_kubernetes -->|"runs workload"| node_mirror_lb
node_kubernetes -->|"runs workload"| node_tracker
node_kubernetes -->|"runs workload"| node_login
node_kubernetes -->|"runs workload"| node_drives
node_kubernetes -->|"runs workload"| node_cms
node_kubernetes -->|"runs workload"| node_cardshop
node_kubernetes -->|"runs workload"| node_nautilus
node_kubernetes -->|"runs workload"| node_zimfarm
node_kubernetes -->|"runs workload"| node_zimit
node_kubernetes -->|"runs workload"| node_mirrors_qa
node_kubernetes -->|"runs workload"| node_wiki
node_kubernetes -->|"runs workload"| node_stats
node_overview -->|"queries resources"| node_kubernetes
node_cluster_backup -->|"backs up"| node_kubernetes

click node_library "https://github.com/kiwix/operations/tree/main/zim/library"
click node_downloads "https://github.com/kiwix/operations/tree/main/zim/download-kiwix"
click node_openzim_downloads "https://github.com/kiwix/operations/tree/main/zim/download-openzim"
click node_mirror_lb "https://github.com/kiwix/operations/tree/main/zim/load-balancer"
click node_master_mirror "https://github.com/kiwix/operations/tree/main/zim/master-mirror"
click node_tracker "https://github.com/kiwix/operations/blob/main/bittorrent/tracker.yaml"
click node_whitelister "https://github.com/kiwix/operations/blob/main/bittorrent/whitelister.py"
click node_catalog "https://github.com/kiwix/operations/blob/main/zim/library/prod-kiwix-catalog-backend.yaml"
click node_login "https://github.com/kiwix/operations/blob/main/login/login/login.yaml"
click node_drives "https://github.com/kiwix/operations/blob/main/drives/drives.yaml"
click node_cms "https://github.com/kiwix/operations/blob/main/cms/api/api.yaml"
click node_cardshop "https://github.com/kiwix/operations/blob/main/cardshop/api/api.yaml"
click node_nautilus "https://github.com/kiwix/operations/blob/main/nautilus/api/api.yaml"
click node_zimfarm "https://github.com/kiwix/operations/blob/main/zimfarm/api/api.yaml"
click node_zimit "https://github.com/kiwix/operations/blob/main/zimit/api/api.yaml"
click node_mirrors_qa "https://github.com/kiwix/operations/blob/main/mirrors-qa/api/api.yaml"
click node_wiki "https://github.com/kiwix/operations/tree/main/wiki"
click node_stats "https://github.com/kiwix/operations/blob/main/stats/matomo-app.yaml"
click node_overview "https://github.com/kiwix/operations/blob/main/cluster-mgmt/overview/build-overview.py"
click node_cluster_backup "https://github.com/kiwix/operations/blob/main/cluster-backup/cluster-backup.cronjob.yaml"

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_library,node_downloads,node_openzim_downloads,node_mirror_lb,node_master_mirror,node_tracker,node_whitelister,node_catalog toneBlue
class node_login,node_drives toneAmber
class node_cms,node_cardshop,node_nautilus,node_zimfarm,node_zimit,node_mirrors_qa,node_wiki toneMint
class node_stats,node_overview,node_cluster_backup toneRose
class node_kubernetes,node_visitors,node_external_mirrors toneIndigo
```

## Components

### Content delivery

- [ZIM library](https://github.com/kiwix/operations/tree/main/zim/library): `zim/library`
- [Download services](https://github.com/kiwix/operations/tree/main/zim/download-kiwix): `zim/download-kiwix`
- [OpenZIM downloads](https://github.com/kiwix/operations/tree/main/zim/download-openzim): `zim/download-openzim`
- [Mirror load balancer](https://github.com/kiwix/operations/tree/main/zim/load-balancer): `zim/load-balancer`
- [Master mirror](https://github.com/kiwix/operations/tree/main/zim/master-mirror): `zim/master-mirror`
- [BitTorrent tracker](https://github.com/kiwix/operations/blob/main/bittorrent/tracker.yaml): `bittorrent/tracker.yaml`
- [Torrent whitelister](https://github.com/kiwix/operations/blob/main/bittorrent/whitelister.py): `bittorrent/whitelister.py`
- [Kiwix catalog](https://github.com/kiwix/operations/blob/main/zim/library/prod-kiwix-catalog-backend.yaml): `zim/library/prod-kiwix-catalog-backend.yaml`

### Platform services

- [Login service](https://github.com/kiwix/operations/blob/main/login/login/login.yaml): `login/login/login.yaml`
- [Drive service](https://github.com/kiwix/operations/blob/main/drives/drives.yaml): `drives/drives.yaml`

### Hosted applications

- [CMS services](https://github.com/kiwix/operations/blob/main/cms/api/api.yaml): `cms/api/api.yaml`
- [Cardshop](https://github.com/kiwix/operations/blob/main/cardshop/api/api.yaml): `cardshop/api/api.yaml`
- [Nautilus](https://github.com/kiwix/operations/blob/main/nautilus/api/api.yaml): `nautilus/api/api.yaml`
- [ZIMfarm](https://github.com/kiwix/operations/blob/main/zimfarm/api/api.yaml): `zimfarm/api/api.yaml`
- [Zimit](https://github.com/kiwix/operations/blob/main/zimit/api/api.yaml): `zimit/api/api.yaml`
- [Mirror QA](https://github.com/kiwix/operations/blob/main/mirrors-qa/api/api.yaml): `mirrors-qa/api/api.yaml`
- [Wikis](https://github.com/kiwix/operations/tree/main/wiki): `wiki`

### Operations

- [Web analytics](https://github.com/kiwix/operations/blob/main/stats/matomo-app.yaml): `stats/matomo-app.yaml`
- [Resource overview](https://github.com/kiwix/operations/blob/main/cluster-mgmt/overview/build-overview.py): `cluster-mgmt/overview/build-overview.py`
- [Cluster backup](https://github.com/kiwix/operations/blob/main/cluster-backup/cluster-backup.cronjob.yaml): `cluster-backup/cluster-backup.cronjob.yaml`

### Cluster foundation

- **Kubernetes cluster**

### Other components

- **Visitors**
- **External mirrors**

## Connections

- Visitors → ZIM library: browse
- Visitors → Download services: download
- Visitors → OpenZIM downloads: download
- Visitors → CMS services: access
- Visitors → ZIMfarm: access
- Visitors → Zimit: access
- ZIM library → Kiwix catalog: serves catalog
- Torrent whitelister → Kiwix catalog: fetches OPDS
- Torrent whitelister → BitTorrent tracker: updates whitelist
- External mirrors → Mirror load balancer: mirror content
- Master mirror → Mirror load balancer: syncs content
- Kubernetes cluster → ZIM library: runs workload
- Kubernetes cluster → Download services: runs workload
- Kubernetes cluster → OpenZIM downloads: runs workload
- Kubernetes cluster → Mirror load balancer: runs workload
- Kubernetes cluster → BitTorrent tracker: runs workload
- Kubernetes cluster → Login service: runs workload
- Kubernetes cluster → Drive service: runs workload
- Kubernetes cluster → CMS services: runs workload
- Kubernetes cluster → Cardshop: runs workload
- Kubernetes cluster → Nautilus: runs workload
- Kubernetes cluster → ZIMfarm: runs workload
- Kubernetes cluster → Zimit: runs workload
- Kubernetes cluster → Mirror QA: runs workload
- Kubernetes cluster → Wikis: runs workload
- Kubernetes cluster → Web analytics: runs workload
- Resource overview → Kubernetes cluster: queries resources
- Cluster backup → Kubernetes cluster: backs up