Version 2.0 | February 2026

🟩🟨🟥⬛

A Product of The Bundu Family — Built by Nyuchi Africa

Ndiri nekuti tiri — I am because we are

Your Honey. Your Identity. Your Sovereignty.

CONFIDENTIAL

Mukoko is a Digital Twin Social Ecosystem for Africa and the global African diaspora, delivered as a WeChat-style super app on Android, iOS, and Huawei devices. It is the flagship product of The Bundu Family, built by Nyuchi Africa.

The platform consists of 15 interconnected mini-apps — including Campfire, Pulse, Mukoko News, Bytes, Circles, Nhimbe, Novels, BushTrade, Mukoko Lingo, and more — all powered by "Your Honey," a privacy-first personalization engine that works FOR users, not against them. Your Honey runs on-device AI, meaning user behavior data never leaves the device. This is the core product: personalization that empowers rather than manipulates.

The application uses a hybrid architecture: a Flutter native shell provides the core platform services (authentication, wallet, Shamwari AI, notifications, device APIs), while the 15 ecosystem mini-apps run as optimized WebView mini-apps, enabling rapid development and independent deployment. Each app can also operate as a standalone PWA.

This architecture is adapted for African market realities: mixed device quality, high data costs, intermittent connectivity, and mobile money as the primary payment rail.

• Target Markets: Zimbabwe (primary), SADC region, global African diaspora
• Platforms: Android (API 24+), iOS (15+), HarmonyOS (Huawei AppGallery)
• Framework: Flutter native shell + WebView mini-apps (WeChat model)
• Backend: Cloudflare Workers (existing), MongoDB Atlas, D1, KV, Durable Objects
• AI: Shamwari AI companion + Nuchi Honey personalization engine (honey.nyuchi.com)
• Payments: EcoCash, InnBucks, bank integrations + MUKOKO token economy
• Identity: Mukoko ID with Soulbound Identity Token (MIT) on Polygon PoS

Mukoko exists within a unified brand ecosystem rooted in Shona language and Ubuntu philosophy. Understanding this hierarchy is essential to the architecture because it determines how products relate, how branding flows, and how the user journey works.

"The bee needs the hive. The hive needs the bees. Neither exists meaningfully without the other."

Bees (Nyuchi) fly out into the Bundu (wilderness) to collect, pollinate, and build. They return to the Mukoko (hive) to store knowledge, collaborate, and rest. Inside the Mukoko lives Shamwari — the collective wisdom, the helpful AI intelligence. The cycle continues: gather → store → share → grow.

This mirrors the Ubuntu principle: "Munhu munhu muvanhu" — A person is a person through other persons.

1. ENTER THE BUNDU — Discover the ecosystem (marketing, word-of-mouth)
2. JOIN THE MUKOKO — Create Mukoko ID (single sign-on), welcome ceremony (onboarding)
3. MEET SHAMWARI — AI companion introduces features, personalized guidance begins
4. BECOME NYUCHI — Start contributing (learning, sharing, creating), pollinate across platforms
5. SERVE THE HIVE — Help others in community, store knowledge for next generation
6. EMBODY UBUNTU — "I am because we are" realized, individual success = community success

Mukoko is the flagship Digital Twin Social Ecosystem. Other Nyuchi products are separate but use Mukoko ID for authentication:

• Nyuchi Learning — Education platform (separate product, uses Mukoko ID)
• Zimbabwe Travel — Travel/tourism platform (separate product, uses Mukoko ID)
• Harare Metro — Merges INTO Clips (no longer separate; becomes part of Mukoko)

"Your Honey. Your Identity. Your Sovereignty."

Your Honey is the single most important component of Mukoko. It is a personalization engine that learns user preferences on-device and surfaces relevant content across all 15 mini-apps. Unlike exploitative algorithms that optimize for engagement (platform profit), Your Honey optimizes for enrichment (user growth).

1. You Choose Interests Explicitly — 32 categories with granular keywords (e.g., "African tech startups" within Technology)
2. Your Digital Twin Learns On-Device — As you engage across Mukoko News, Pulse, Circles, Novels, Nhimbe, your preferences evolve. All processing stays on YOUR device, never sent to servers.
3. Content Surfaces Across All Components — Mukoko News shows news you care about, Pulse surfaces creators you'll love, Circles suggests matching communities, Novels recommends stories, Nhimbe highlights relevant gatherings.
4. Preferences Evolve As You Grow — Your Digital Twin captures personality evolution. Interests deepen, shift, and new passions emerge naturally.
5. Privacy Preserved Always — On-device AI means no data sent to servers, no surveillance, no selling preferences, no manipulation.

Users select from 32 categories during onboarding and can adjust at any time. Each category has granular sub-keywords. Examples:

• Technology (AI, startups, programming, African tech, gadgets)
• Music (Afrobeats, Chimurenga, Amapiano, Gospel, Hip-Hop, Sungura)
• Business (Entrepreneurship, Finance, Investing, SMEs, Agriculture)
• Sports (Football, Cricket, Rugby, Athletics, Boxing)
• Culture (Shona traditions, Ndebele heritage, Pan-African identity, Diaspora)
• Food (Zimbabwean cuisine, Cooking, Restaurants, Street food)
• Politics (Zimbabwe, SADC, AU, Global affairs)
• Health (Fitness, Mental health, Traditional medicine, Healthcare)
• Education (STEM, Languages, Vocational training, Scholarships)
• Entertainment (Movies, Series, Comedy, Theatre, Gaming)
• ...and 22 more categories

Nuchi Honey is the backend personalization service that powers Your Honey. It runs on completely isolated infrastructure, separate from the main Cloudflare Workers deployment, for maximum privacy and security.

The on-device component runs as a lightweight ML model embedded in the Flutter shell. It processes user interactions locally, builds the Digital Twin profile, and communicates with Nuchi Honey only to receive updated model weights (federated learning), never raw user data.

• Model format: TensorFlow Lite (Android/Huawei) + Core ML (iOS)
• Size target: < 5MB model, < 10MB total on-device AI footprint
• Battery budget: < 2% additional drain from background learning
• Sync pattern: Model weight updates via delta sync, not full model download
• Local storage: Digital Twin profile stored encrypted in app sandbox (SQLite)

Mukoko consists of 15 interconnected mini-apps, all sharing one Digital Twin, one Your Honey engine, one reputation system, and one token economy. Each app is implemented as a WebView mini-app loaded inside the Flutter shell.

Mukoko News is the evolution of Harare Metro. It provides context-rich news from trusted African and global sources, filtered by Your Honey to surface topics the user actually cares about. News should inform, not manipulate. Context over clickbait.

• Migrates from existing mukoko-news-backend Cloudflare Worker
• RSS aggregation from 17+ Zimbabwean sources (Herald, NewsDay, Chronicle, ZBC, Techzim, The Standard, ZimLive, Business Weekly, etc.)
• AI-powered categorization into 10+ content categories
• Your Honey personalizes the feed based on Digital Twin interests
• Threaded comments, bookmarks, reading history (MongoDB Atlas)

Pulse is the super app's aggregated feed — a monorepo-native feature that pulls content from ALL ecosystem apps into a single, personalized stream. It exists only within the super app, powered by Your Honey.

• Aggregates content from Mukoko News, Circles, Novels, Nhimbe, and creator content
• Personalized by Your Honey (on-device learning + Mukoko ID cloud profile)
• Combines TikTok-style vertical scrolling with Instagram-style discovery
• MUKOKO token rewards for quality content creation
• Not to be confused with Bytes — Bytes is the TikTok-style scrolling feature in the mukoko-news standalone app only

Interest-based communities. Your Honey suggests Circles matching explicit interests and recommends discussions the user would find valuable. Community forms around shared interests, not algorithmic manipulation.

• Circle creation and moderation tools
• Discussion threads with rich media
• Circle reputation system (moderators earn tokens)
• Cross-pollination: Mukoko News articles can be discussed in relevant Circles
• Leverages existing Durable Objects (ChatRoom, UserSession) for real-time features

Web novel platform supporting African authors. Authors keep 80%+ of revenue. Your Honey recommends stories in genres the user loves. African stories deserve global audiences.

• Chapter-by-chapter publishing
• Reader engagement (likes, comments, bookmarks)
• Author dashboard with analytics
• MUKOKO token payments for premium chapters
• Genre categorization aligned with Your Honey interest categories

Cultural celebrations, meetups, and community events. Evolves from the existing Nhimbe Events platform. Digital connection should enhance physical community, not replace it. Integrates with Mukoko Wallet for ticket purchasing.

• Migrates from existing mukoko-nhimbe-api Cloudflare Worker
• Event discovery powered by Your Honey (location + interests)
• Ticket purchasing via Mukoko Wallet (EcoCash, InnBucks, MUKOKO tokens)
• Event organizer tools (create, manage, promote)
• Post-event community: attendees can form Circles

Campfire is the messaging + payments core — the WeChat-style anchor that keeps users in the ecosystem. Messaging, voice notes, group chats, and integrated payments (EcoCash, InnBucks, MUKOKO tokens) in one place.

Beyond the core apps, Mukoko includes:

• BushTrade — Peer-to-peer marketplace for buying/selling within the community
• Mukoko Lingo — Language learning focused on African languages
• Weather — Local weather forecasts for Zimbabwean cities
• Transport — Kombi/taxi routes, transit info, and ride booking
• Bytes — TikTok-style short-form video scrolling (shares backend with Mukoko News)

"I serve, I do not control."

Shamwari (Shona for "friend") is the AI companion that lives inside the Mukoko hive. It is not a separate app but an omnipresent intelligence woven into every part of the ecosystem, guiding users, providing recommendations, and bridging human connection with technology.

• Onboarding guide — Introduces new users to the ecosystem, helps configure interests
• Cross-app intelligence — Surfaces connections between Clips articles, Pulse creators, Connect discussions, Novels, and Events
• Conversational assistant — Answers questions, helps navigate, provides context
• Content summarization — Summarizes long articles, provides TLDR for busy users
• Language support — Multilingual assistance including Shona and Ndebele

• Companionship — Be present without being intrusive
• Guidance — Suggest, don't command
• Trust — Earn trust through consistent helpfulness
• Humility — Know your limitations
• Partnership — Work alongside humans, not above them

Shamwari runs as a service accessible through the MukokoBridge API. Mini-apps can invoke Shamwari for contextual assistance. The Flutter shell provides a persistent Shamwari chat interface accessible from any screen via a floating action button.

• Brand color: Malachite (#004D40 light / #64FFDA dark)
• Backend: Dedicated Cloudflare Worker + AI model inference
• Context: Receives anonymized context from Your Honey to provide relevant assistance
• Personality: Warm, knowledgeable, culturally aware, never condescending

Mukoko ID is the honeycomb that holds the honey. It is the enabling infrastructure that makes Your Honey possible — invisible to users enjoying the sweetness, but essential to the ecosystem. Great infrastructure disappears.

• ONE login across all six apps (seamless, no friction)
• ONE Digital Twin that learns evolving personality
• ONE reputation system that builds as users participate anywhere
• ONE wallet collecting MUKOKO tokens from all activities
• ONE Your Honey engine that improves across everything

Each user's Digital Twin is anchored by a MUKOKO Identity Token (MIT) — a soulbound, non-transferable ERC-721 token on the Polygon PoS blockchain. This is not a collectible NFT — it is a mathematical representation of a person's temporal identity within the ecosystem.

• Soulbound: Cannot be sold, traded, or transferred. The transferFrom function is overridden to revert unconditionally.
• Birth-date anchored: Minted with the user's verified date of birth. This date becomes the mathematical anchor for value calculation.
• Three-pool membership: Every MIT simultaneously belongs to a Year Pool (birth year), Month Pool (birth month), and Day Pool (birth day-of-month).
• Monotonically increasing value: Token value grows at exactly one second per second. There is no crash scenario in the protocol.
• One per human: Enforced at the contract level — one MIT per verified identity.
• Deletable: Users can burn their token and delete all associated data (full data sovereignty).

The MIT's value is the weighted composite of three temporal pools:

V(token, t) = 0.60 × Mean(Year Pool) + 0.30 × Mean(Month Pool) + 0.10 × Mean(Day Pool)

Pool means are computed in O(1) via running aggregates — no iteration over members, regardless of pool size. This is essential for continental scale (1B+ users).

People born on 29 February belong to a pool that accumulates members only once every four years. A normalisation factor L = 4 scales their day pool contribution to be equivalent to a full-representation pool. Calendar equity is non-negotiable.

Chain: Polygon PoS (low gas, EVM-compatible, existing African exchange liquidity). Framework: OpenZeppelin Contracts v5. KYC: Africa Talks API (primary, SMS OTP verification), Stytch (secondary, web/desktop users).

The Memory File is the central personalization artifact for each user. It is co-created by two systems:

Nyuchi Honey (on-device)          Mukoko ID (cloud)
┌─────────────────────┐          ┌─────────────────────┐
│ Learns preferences   │ ──sync──▶│ Stores Memory File   │
│ privately on phone   │ summaries│ in user's account    │
│ Raw data stays local │          │ Editable by user     │
└─────────────────────┘          └──────────┬──────────┘
                                            │ reads
                              ┌─────────────┼──────────────┐
                              ▼             ▼              ▼
                          Shamwari AI    Pulse feed    All app
                          (companion)   (aggregated)   personalization

• Honey processes interactions on-device, syncs only summarized data (never raw events) to Mukoko ID
• Mukoko ID stores the Memory File securely in the cloud
• The user can edit or delete their Memory File at any time — full data sovereignty
• Shamwari AI, Pulse, and all app personalization read the Memory File

Mukoko ID already has production and staging Cloudflare Workers deployed (mukoko-id-api, mukoko-id-api-staging). The Flutter shell integrates with this existing infrastructure via Stytch authentication, adding biometric unlock, secure token storage, and the Digital Twin minting flow.

┌────────────────────────────────────────────────────────┐
│       MUKOKO SUPER APP (Flutter Shell)                 │
│                                                        │
│  ┌──────────────────────────────────────────────────┐  │
│  │  Native Platform Services (Flutter/Dart)         │  │
│  │                                                  │  │
│  │  Mukoko ID | Wallet | Shamwari AI | NavBar       │  │
│  │  Your Honey (On-Device AI / Digital Twin)        │  │
│  │  Push Notifications | Biometrics | Camera        │  │
│  │  Offline Engine (SQLite + Sync Queue)            │  │
│  └──────────────────────────────────────────────────┘  │
│              │ MukokoBridge JS API │                    │
│  ┌──────────────────────────────────────────────────┐  │
│  │  Mini-App Runtime (WebView)                      │  │
│  │                                                  │  │
│  │  Clips | Pulse | Connect | Novels | Events       │  │
│  │  + Utility apps (Weather, Marketplace, etc.)     │  │
│  │  (Preact + Nyuchi Design System)                 │  │
│  └──────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────┘
                        │
            HTTPS (Cloudflare Edge)
                        │
┌────────────────────────────────────────────────────────┐
│  BACKEND SERVICES                                      │
│  API Gateway Worker                                    │
│     │                                                  │
│  ┌──┴───┬──────┬─────┬──────┬──────┬───────┐         │
│  │ ID   │ News │ Nhi │ Weat │ Wall │ Honey │         │
│  │ API  │ API  │ API │ API  │ API  │ (iso) │         │
│  └──┬───┴──────┴─────┴──────┴──────┴───────┘         │
│     │                                                  │
│  ┌──┴─────┬──────┬────┬──────┬───────────┐           │
│  │MongoDB │  D1  │ KV │  R2  │ Durable Obj│          │
│  │ Atlas  │      │    │      │            │          │
│  └────────┴──────┴────┴──────┴───────────┘           │
└────────────────────────────────────────────────────────┘
                        │
               honey.nyuchi.com
         (Isolated Nuchi Honey Service)
      Docker | FastAPI | Cloudflare Tunnel

The Flutter shell handles everything requiring native device access or persistence across mini-app contexts. Built with clean architecture: presentation (widgets), domain (use cases), data (repositories).

• Authentication lifecycle (Mukoko ID): login, register, biometric unlock, token refresh, Digital Twin minting
• Your Honey on-device AI: TFLite/CoreML model, local preference learning, federated weight sync
• Shamwari AI: persistent chat interface, contextual assistance across all apps
• Wallet operations: EcoCash, InnBucks, MUKOKO tokens, balance, transactions, QR scan-to-pay
• WebView management: lifecycle, caching, preloading, memory management, MukokoBridge injection
• Mini-app manifest: registry, version checking, asset preloading from R2
• Offline engine: SQLite local database, sync queue, conflict resolution
• Push notifications: FCM (Android), APNs (iOS), HMS Push (Huawei), unified notification center
• Device APIs: camera, location, contacts, biometrics, NFC, share sheet

Injected into every mini-app WebView. Provides typed access to native platform services.

window.MukokoBridge = {
  auth: {
    getUser()           // Current user + Digital Twin profile
    getToken()          // JWT for API calls
    onAuthChange(cb)    // Subscribe to auth state
  },
  honey: {
    getInterests()      // User's 32-category interest map
    trackInteraction({ type, contentId, duration })
    getSuggestions(context)  // Ask Your Honey for recommendations
  },
  shamwari: {
    ask(question)       // Invoke Shamwari AI
    summarize(content)  // Content summarization
    translate(text, lang)
  },
  wallet: {
    getBalance()        // Wallet balance (fiat + MUKOKO tokens)
    requestPayment({ amount, currency, description })
    transferTokens({ to, amount })
    onPaymentResult(cb)
  },
  device: {
    getLocation()       // GPS coordinates
    openCamera()        // Returns image data
    scanQR()            // QR code scanner
    share(data)         // Native share sheet
    haptic(type)        // Haptic feedback
  },
  nav: {
    openMiniApp(id, params)  // Launch another mini-app
    goBack()                 // Navigate back
    setTitle(text)           // Update nav bar title
  },
  storage: {
    get(key) / set(key, value) / remove(key)
  },
  reputation: {
    getScore()          // Cross-platform reputation
    getTokenBalance()   // MUKOKO token balance
  }
}

Each of the six ecosystem apps is a lightweight web application loaded inside the Flutter shell's WebView.

• UI Framework: Preact (3KB gzipped — not React's 40KB)
• Design System: @mukoko/ui — shared Nyuchi Brand v6 components
• Bridge SDK: @mukoko/bridge — typed TypeScript wrapper around MukokoBridge
• Build: Vite, output < 150KB gzipped per mini-app
• Hosting: Cloudflare R2 (static assets) + Workers (API)
• Caching: Service Worker + Flutter WebView cache (offline-capable)
• Standalone: Each mini-app also works as PWA at its subdomain

The backend leverages existing Cloudflare Workers infrastructure already deployed and running. The mobile app targets the same API endpoints, with a new API gateway worker for unified routing.

Total: 15 workers deployed

Stytch is the auth provider for the entire ecosystem. NOT Supabase.

• Sessions: Stytch session tokens (not Supabase JWT)
• Methods: Email magic links, OAuth (Google, GitHub, Apple), SMS OTP, biometric
• SSO: Mukoko ID provides SSO to all Nyuchi products (Learning, Travel, Bundu Family)
• Worker middleware: Every worker verifies Stytch session token on protected routes
• Super Admin: [email protected]

The system operates with two tokens that have distinct roles but work together as a single economic system.

MUKOKO Identity Token (MIT) — soulbound, non-transferable, anchored to verified birth date. Used for governance staking and as the value anchor for the exchange token. The right analogy is ancestral land under Ubuntu customary law — it represents your permanent stake in the community.

MUKOKO Exchange Token (MXT) — standard transferable ERC-20 used for all transactions across the platform. Its floor price is derived from the MIT pool system. This is the currency people spend. Think of it as the money circulating on the land — backed by something real, spendable freely, and always guaranteed a minimum value by the protocol.

The core economic loop: More users join → more MITs are minted → pool means grow as the community ages → MXT floor rises → the platform becomes more valuable to everyone already on it. Growth benefits all existing members. This is Ubuntu expressed as token economics.

There is no hard supply cap on MXT. This is the single most important design decision in the token economics.

A fixed supply is the right model for digital gold — a scarce store of value. It is the wrong model for a transaction currency designed to serve a growing continental economy. Africa's GDP is ~$3 trillion today, projected to reach $29 trillion by 2050. At continental scale, a fixed supply combined with a burn mechanism would strangle the platform's own success.

Three parameters govern the MXT supply, all stored in the EmissionController contract and adjustable only through Tier 1 constitutional governance votes:

Initial minted supply: 3 billion MXT. Governance protection for the founding team comes from Reserved Powers (legal), not token dominance — freeing the allocation to reflect where value actually comes from.

50% goes to the community from day one. Investors get economic participation — not governance rights.

Governance uses conviction staking, not coin-voting. The effective weight formula:

Effective Weight = √(MXT staked) × Ubuntu Multiplier × Regional Multiplier

• Square root (quadratic voting): Doubling your stake only increases weight by ~41%. A community of 1,000 people staking 100 MXT each outweighs one person staking 100,000 MXT.
• Ubuntu Multiplier (1.0×–2.0×): Rewards sustained community engagement, derived from on-platform Ubuntu Score.
• Regional Multiplier: Platform-wide votes = 1.0×. Regional votes = 2.0× for affected region. Country-level = 3.0× for affected country.

Four Governance Tiers:

Founder's Reserved Powers: Embedded in the Mukoko Foundation's Mauritius constitutional documents as legal rights — not token rights. Protects: Ubuntu purpose, African sovereignty mandate, platform control, core token protocol. The community governs operations. The founder protects the soul.

Earning:

• Clips — Quality comments, sharing, community journalism
• Pulse — Creating content, trending contributions, curation
• Connect — Circle moderation, helpful discussions, community building
• Novels — Publishing stories, reader engagement, editorial contributions
• Events — Organizing events, community gathering, cultural celebration

Spending:

• Event tickets, novel chapters, marketplace transactions
• Peer-to-peer payments and remittances across African borders
• Premium features across all apps
• Enterprise API access (B2B demand)

Creators keep 80%+ of revenue (vs. 30-50% on mainstream platforms):

• Novel authors: 85% of chapter revenue
• Pulse creators: 80% of tipping revenue
• Event organizers: 90% of ticket revenue
• Circle moderators: reputation + token bonuses

Creator rewards are distributed in MXT from the Ecosystem Reserve — creating income denominated in a currency with a rising floor value.

For each MXT fee collected: 30% burned (permanent supply reduction), 40% Community Treasury (governance distribution), 30% Ecosystem Reserve (creator rewards, developer grants).

The wallet displays all values in the user's preferred local currency. Off-ramp partnerships with mobile money providers enable conversion without crypto exchange accounts:

• M-Pesa — East Africa
• MTN MoMo — West and Central Africa
• Airtel Money — East and Central Africa
• EcoCash — Zimbabwe (primary launch market)
• InnBucks — Zimbabwe (growing market)

• QR code scan-to-pay at merchants
• Peer-to-peer transfers between Mukoko users
• Event ticket purchasing via Events integration
• Novel chapter purchases and author tips
• Bill splitting for events and group purchases
• Transaction history with full export
• Biometric auth required for transactions above threshold

Data costs are a primary concern in Zimbabwe. The architecture minimizes data consumption at every level.

• Mini-app bundles downloaded once, cached locally (50-150KB gzipped per app)
• Shared design system loaded once across all mini-apps (not duplicated)
• Images via Cloudflare Images: automatic WebP/AVIF, responsive sizing
• API responses: gzip compression, pagination, delta sync (only changes since last timestamp)
• User-configurable data saver mode: reduces image quality, disables auto-play, limits prefetch
• Your Honey model weights: delta sync, not full model download

SQLite (sqflite) serves as local database with sync queue pattern. When offline, all writes queue locally with timestamps. When connectivity returns, the sync engine replays against the API with conflict resolution (last-write-wins for content, manual resolution for payments). News, weather, and events are cached with TTLs. The app remains fully browsable offline with stale data indicated in UI.

mukoko/
├── app/                           # Flutter super app shell
│   ├── android/ | ios/ | huawei/  # Platform configs
│   ├── lib/
│   │   ├── core/                  # Init, routing, DI
│   │   ├── features/
│   │   │   ├── auth/              # Mukoko ID (login, register, biometric, Digital Twin)
│   │   │   ├── wallet/            # Payments, balance, tokens, QR
│   │   │   ├── honey/             # On-device AI, Digital Twin learning
│   │   │   ├── shamwari/          # AI companion, chat, assistance
│   │   │   ├── miniapp_runtime/   # WebView manager, bridge, lifecycle
│   │   │   ├── notifications/     # Push + local notification center
│   │   │   ├── discovery/         # Mini-app launcher / home screen
│   │   │   └── settings/          # Preferences, data saver
│   │   ├── shared/                # Design system widgets, Nyuchi theme
│   │   └── bridge/                # MukokoBridge JS implementation
│   └── pubspec.yaml
│
├── mini-apps/                     # Super app frontends (WebView in Flutter shell)
│   ├── clips/                     # Clips — news feed (backend in mukoko-news repo)
│   ├── pulse/                     # Pulse — personalized aggregated feed (monorepo-native)
│   ├── connect/                   # Connect — Circles (backend in mukoko-connect repo)
│   ├── novels/                    # Novels — author platform (backend in mukoko-novels repo)
│   ├── events/                    # Events — gatherings (backend in nhimbe repo)
│   ├── weather/                   # Weather — utility (backend in mukoko-weather repo)
│   └── _template/                 # Starter template for new mini-apps
│
├── services/                      # Cloudflare Workers — super app infrastructure only
│   ├── gateway/                   # API gateway + Stytch session verification
│   ├── id-api/                    # Mukoko ID (Stytch auth + Memory File storage)
│   ├── wallet-api/                # Payments + MUKOKO tokens
│   ├── shamwari-api/              # AI companion (reads Memory File)
│   ├── miniapp-registry/          # Mini-app manifest + R2 assets
│   ├── digital-twin/              # NFT minting + reputation
│   └── _template/                 # Starter template for new services
│
├── honey/                         # Nuchi Honey (isolated)
│   ├── Dockerfile
│   ├── app/                       # FastAPI service
│   ├── models/                    # ML models
│   └── docker-compose.yml
│
├── packages/                      # Shared libraries
│   ├── design-system/             # @mukoko/ui (Preact components)
│   ├── bridge-sdk/                # @mukoko/bridge (typed JS bridge)
│   ├── api-client/                # @mukoko/api (shared API client)
│   └── types/                     # @mukoko/types (shared TypeScript)
│
├── web/                           # Marketing landing page (mukoko.com → Vercel)
│   ├── src/                       # Preact + Vite, Formspree waitlist
│   ├── vercel.json                # Vercel deployment config
│   └── index.html                 # Entry with OG tags
├── docs/                          # Architecture, API docs, guides
├── .github/                       # CI/CD workflows
└── turbo.json                     # Monorepo orchestration

All UI uses the Five African Minerals palette. Mukoko Platform: Tanzanite primary, Cobalt secondary, Gold accent.

• Display: Noto Serif (elegant, cultural weight)
• Body: Plus Jakarta Sans (clean, modern, excellent readability)
• Code: JetBrains Mono (developer-facing content)

• Button radius: 12px
• Card radius: 16px
• Touch targets: 44x44px minimum
• Five African Minerals strip: 4px vertical left edge (Tanzanite → Cobalt → Gold → Malachite → Terracotta, hidden < 480px)
• Wordmarks: always lowercase (mukoko, nyuchi, shamwari, bundu)
• Contrast ratios: WCAG AAA (7:1+) — non-negotiable
• Mode adaptation: all colors adapt between light and dark automatically

• Travel Brand: NO purple/tanzanite (nature-forward aesthetic)
• Education Brand: Uses slate dark theme variant (#0F172A base, #1E293B surface)
• Mukoko Platform: Tanzanite primary, Cobalt secondary, Gold accent
• Shamwari AI: Malachite primary, Cobalt secondary, Gold accent

• Replace Google services with HMS equivalents
• HMS Push Kit (replaces FCM)
• Petal Maps (replaces Google Maps)
• HMS Core ML Kit (supplement for on-device AI)
• agconnect_push Flutter package for Huawei push notifications

• Flutter project: clean architecture, Riverpod state management, platform configs
• Mukoko ID integration: Stytch auth, biometric unlock, secure storage
• WebView runtime: MukokoBridge injection, lifecycle management, caching
• Navigation shell: bottom tabs, mini-app launcher, discovery surface
• Nyuchi Design System for Flutter: shared theme, Tanzanite primary
• API gateway worker deployment
• Your Honey on-device AI: TFLite/CoreML model scaffold, interest selection UI
• Mini-app manifest registry (R2-based asset serving)

• Clips mini-app: migrate Harare Metro/Mukoko News to Preact, integrate Your Honey
• Events mini-app: migrate Nhimbe, add ticket purchasing flow
• Pulse mini-app: short-form content, creator profiles, trending
• Connect mini-app: Circles, interest communities, discussions
• Shamwari AI: onboarding flow, basic conversational assistance
• Weather utility mini-app
• Offline engine: SQLite cache + sync queue
• Push notifications: FCM + APNs + HMS Push
• Internal testing on Android

• Mukoko Wallet: native Flutter implementation
• EcoCash integration (USSD push + API)
• InnBucks integration
• MUKOKO token ledger + earning/spending across apps
• Soulbound Identity Token (MIT) minting on Polygon PoS
• QR code scan-to-pay
• Novels mini-app: author platform, reading experience, chapter payments
• Beta launch on Google Play (Zimbabwe)

• iOS App Store submission
• Huawei AppGallery submission (HMS adaptation)
• Nuchi Honey federated learning: model improvement without exposing user data
• Performance optimization for low-end devices
• Data saver mode implementation
• Mini-app developer SDK documentation
• Public launch across all stores
• 50,000 Digital Twin target

The platform operates through two legally independent entities with distinct roles:

Mukoko Foundation — Mauritius, registered under the Foundations Act 2012

• Non-profit custodian of the protocol, token economics, and Ubuntu charter
• Holds the VASP licence under the Virtual Asset and Initial Token Offering Services Act 2021 (VAITOS)
• Controls the PoolRegistry, EmissionController, and IdentityToken smart contracts
• Governed by a Council elected by MIT holders via conviction staking
• Cannot be acquired, merged, or dissolved without a Tier 1 constitutional vote (66% quorum)
• Jurisdiction chosen for: common-law legal system, FATF-compliant crypto regulation, tax treaty network, and proximity to African markets

Nyuchi Africa (Pvt) Ltd — Zimbabwe, registered under the Companies and Other Business Entities Act

• For-profit operating company that builds and operates the Mukoko platform
• Employs the engineering, design, and operations teams
• Holds commercial agreements with payment providers (EcoCash, InnBucks, M-Pesa)
• Revenue from platform fees, enterprise API access, and premium features
• Licensed by the Foundation to operate the platform under a revocable service agreement

The founder's governance protection is embedded in the Foundation's constitutional documents as legal rights — not token rights. This ensures the platform's soul cannot be voted away by token accumulation.

Reserved Powers (exercisable only by the founder or their appointed successor):

Reserved Powers cannot be used to: allocate tokens, direct treasury spending, override operational governance (Tier 3-4), or benefit the founder financially. They exist solely to protect purpose.

• Mukoko platform IP owned by Nyuchi Africa, licensed to the Foundation
• Open-source components released under MIT License
• Brand assets (mukoko, nyuchi, shamwari, bundu wordmarks) trademarked by Nyuchi Africa
• Smart contract source code published and verified on Polygonscan

• Transport: All API communication HTTPS with certificate pinning
• Token storage: JWT tokens in platform secure storage (Keychain/Keystore), never in WebView localStorage
• Mini-app sandboxing: Scoped storage per app, no cross-app data access without MukokoBridge
• Your Honey: On-device only, federated learning for model updates, no raw data leaves device
• Wallet: Biometric auth required for transactions above threshold
• Digital Twin NFT: User-controlled, deletable (burn), exportable
• Nuchi Honey service: Isolated infrastructure, Cloudflare Tunnel, secret-based auth
• Mini-app permissions: Apps declare required capabilities in manifest, user approves
• PCI DSS: No card data stored on device, tokenization only
• MongoDB Atlas: Role-based access control on all collections
• Secrets management: All API keys and tokens in environment variables, never in source code
• Admin access: [email protected] is super_admin with full RBAC system

Before any feature, product, or decision launches, it must pass the Ubuntu Test:

1. Does this strengthen community? (Not just engagement)
2. Does this respect human dignity? (Not just compliance)
3. Does this serve the collective good? (Not just revenue)
4. Would we explain this proudly to our elders? (Not just legally)
5. Does this align with "I am because we are"? (Not just "I win")

If the answer to any is "no," reconsider.

🟩🟨🟥⬛

The algorithm works FOR you. The identity belongs TO you. The community strengthens WITH you.

Ndiri nekuti tiri — Built by Nyuchi Africa