v4.0.1

mukoko architecture

Local-first, mobile-first, open source architecture for Africa’s super app. Built on Ubuntu philosophy — I am because we are.

Principles

Ubuntu philosophy and guiding principles

Data Layer

Local-first storage and cloud sync

Pipeline

Open data pipeline for Africa

Sovereignty

Technology sovereignty assessments

Guiding Principles

Ubuntu Philosophy

I am because we are — every architectural decision flows from communal benefit.

Local-First

The device is the primary source of truth. The cloud is a synchronisation and backup layer, not a dependency.

Mobile-First

The primary interface is a mobile device with constrained resources.

Open Source & Sovereign

Choose genuinely open source alternatives over proprietary corporate technologies.

Open Data

Platform-level, anonymised, aggregate data is Mukoko's gift to the continent, not its moat.

Framework Decision

Next.js + Capacitor

The two dominant cross-platform frameworks (Flutter/React Native) are controlled by large American corporations. Capacitor runs web standards — HTML, CSS, JavaScript — inside a native WebView. Web standards are governed by the W3C and WHATWG (international standards bodies), and JavaScript by ECMA International (Swiss). This is also precisely the architecture that WeChat and Alipay converged on — a runtime environment hosting mini-applications built on web standards.

android

capacitor-native

production

ios

capacitor-native

production

web

pwa

production

harmonyos

webview

planned

Architecture Overview

┌─────────────────────────────────────────────────────────┐
│                    USER'S DEVICE                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │         Next.js App (Capacitor Shell)            │   │
│  │  ┌──────────────────────────────────────────┐   │   │
│  │  │              RxDB Layer                   │   │   │
│  │  │  (Reactive queries, schema, replication)  │   │   │
│  │  └──────────┬──────────────────┬────────────┘   │   │
│  │    ┌────────▼──────┐  ┌───────▼────────┐       │   │
│  │    │  SQLite        │  │  IndexedDB     │       │   │
│  │    │  (Native App)  │  │  (Browser PWA) │       │   │
│  │    └───────────────┘  └────────────────┘       │   │
│  └─────────────────────────────────────────────────┘   │
└───────────────────────┬─────────────────────────────────┘
                      │ Sync (when online)
┌───────────────────────▼─────────────────────────────────┐
│                  OPERATIONAL CLOUD                       │
│  ┌──────────────────┐      ┌──────────────────────┐    │
│  │   Apache CouchDB  │      │  Supabase / Postgres  │    │
│  │  (Community data) │      │  (Auth, wallet, txns) │    │
│  └────────┬─────────┘      └──────────┬────────────┘    │
└───────────┼─────────────────────────────┼───────────────┘
          │ Change events               │
          └──────────────┬──────────────┘
┌──────────────────────────▼──────────────────────────────┐
│                  ANALYTICS PIPELINE                      │
│  ┌─────────────────────────────────────────────────┐   │
│  │              Redpanda (Kafka-compatible)          │   │
│  └──────────────────────┬──────────────────────────┘   │
│  ┌──────────────────────▼──────────────────────────┐   │
│  │   Apache Flink — Strip PII · Enrich · Aggregate  │   │
│  └──────────────────────┬──────────────────────────┘   │
│  ┌──────────────────────▼──────────────────────────┐   │
│  │   Apache Doris — Open Data API + Dashboards       │   │
│  └──────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

Architecture API

All architecture data is available via the Mukoko Architecture API.

Endpoint	Description
GET /api/v1	API discovery document
GET /api/v1/ecosystem	Architecture principles and framework decision
GET /api/v1/data-layer	Local-first and cloud data layer specification
GET /api/v1/pipeline	Open data pipeline stages
GET /api/v1/sovereignty	Technology sovereignty assessments