principles & philosophy
The architectural principles that guide every technology decision across the Mukoko ecosystem.
Core Principles
Each principle carries a name, rationale, and concrete implementation guidance.
I am because we are — every architectural decision flows from communal benefit.
Rationale
Mukoko is Africa's super app built not as a copy of Western or Eastern platforms, but as a genuinely African product rooted in the Ubuntu philosophy. The platform exists to serve communities, not extract from them.
Implementation
Open data layer shares anonymised platform intelligence with the continent. Community-contributed data syncs across all devices. Platform data belongs to Africa.
The device is the primary source of truth. The cloud is a synchronisation and backup layer, not a dependency.
Rationale
Mukoko must work fully — browsing, payments, community content, weather data — in a village with no connectivity, on a phone with 2G, or in a city with intermittent wifi. The infrastructure must match the reality of African users' lives.
Implementation
RxDB with SQLite (native) or IndexedDB (browser) as the local database. Reads and writes happen locally without network round-trips. CouchDB and Supabase sync when connectivity exists.
The primary interface is a mobile device with constrained resources.
Rationale
Architecture is designed for small screens, limited battery, constrained data plans, and the hardware reality of the African smartphone market — including Android, iOS, and critically, Huawei HarmonyOS devices.
Implementation
Next.js + Capacitor as a thin native shell. 48px minimum touch targets. Progressive loading. Lazy sections with memory pressure monitoring.
Choose genuinely open source alternatives over proprietary corporate technologies.
Rationale
Strategic risk management. External corporate dependencies can be weaponised. Huawei exists as a company building its own OS precisely because external dependencies were used against it. Mukoko thinks about this before it becomes a crisis.
Implementation
Every technology assessed for sovereignty risk. Apache-licensed and public domain technologies preferred. All core infrastructure is self-hostable and forkable. MongoDB removed for SSPL license concerns.
Platform-level, anonymised, aggregate data is Mukoko's gift to the continent, not its moat.
Rationale
Researchers, journalists, governments, developers, and NGOs across Africa should be able to query what the Mukoko community collectively knows about weather, foot traffic, economic activity, and community life. Personal data remains private and protected. Platform data belongs to Africa.
Implementation
Apache Doris as the open data engine. Apache Flink strips all PII before data reaches the analytical layer. Public REST API for open data queries. MySQL-compatible SQL interface for researchers.
Framework Decision
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.Sovereignty advantage: No framework vendor holds the platform hostage. Sub-apps are web applications that can run in any browser, on HarmonyOS's WebView, or on a future Nyuchi-built runtime.
| Platform | Strategy | Status |
|---|---|---|
| android | capacitor-native | production |
| ios | capacitor-native | production |
| web | pwa | production |
| harmonyos | webview | planned |