Three Changes to How We Describe the Nyuchi Architecture

Architecture documents are easy to write and hard to keep honest. They drift the moment the system grows. They start describing a model the team has quietly abandoned and stop describing the model the team is actually building.

We've spent the last two months pulling our architecture documentation back into sync with the system. The work changed three things, and the changes are big enough that anyone building on the Nyuchi platform — or considering it — should understand them.

This post is the field guide.

What changed

Three things, in order of how visible they are:

1. The application architecture has a new model — the Mzizi DNA Helix — replacing the older "ten layers, four axes, three dimensions plus outliers" framing that we used to talk about how Mzizi (the design system / framework) is composed.
2. We separated the application architecture from the data architecture, deliberately. These two used to be described as one stack. They are now described as two architectures that intersect at one defined point. The distinction matters more than it sounds.
3. The Architecture and Order documents moved up to the Bundu Foundation. They used to be owned by the Mukoko pillar. They were always Foundation-level concerns; we just hadn't named the ownership correctly.

Three reframes, one coherent story: a maturing ecosystem learning to describe itself accurately.

1. The Mzizi DNA Helix

Mzizi is the design system and framework that everything in the ecosystem uses. Mukoko mini-apps, the Nyuchi Console, the Nyuchi enterprise products, the consumer-facing surfaces — they all consume Mzizi components, tokens, and patterns. Mzizi is owned by the Bundu Foundation as intellectual property, authored by Nyuchi as code, and used everywhere.

We used to describe Mzizi as a stack of ten numbered nodes (N1 through N10) organised along three dimensional axes plus a category called "outliers." The model worked when there were ten nodes. It broke whenever we added a piece — because adding a piece meant relitigating which axis it lived on and whether it was horizontal, vertical, depth, or outlier.

The DNA helix replaces the dimensional metaphor with named strand components. The whole helix is Mzizi. The strands are functional, not dimensional:

• Core guarantee — primitives, accessibility, data, resilience, observability, fundi (the self-healing agent), safety. The fixed promise: every adopter gets these, unchanged, no matter what else they swap.
• Shipped — brand, pages, shell. Nyuchi-authored components that ship with Mzizi but are still part of the framework.
• Swappable — styling/tokens, icon library, framework (React today, with SvelteKit as a migration target). The pieces an adopter can replace wholesale to make Mzizi their own.
• Spine — the harness. The pre-wiring backbone that holds the strands together. Not a styling layer; a structural one.
• Genetic code — Ubuntu principles, Bundu conventions, the cultural-architectural sequence everything is read from.
• Documentation / transcription — every piece of doctrine, every convention, every architectural decision, queryable as a document.

The shift sounds semantic but the practical consequence is significant. Adopters who want to use Mzizi in a different framework, with a different icon set, or with their own visual identity now have a named, structured way to do it — swap exactly three layers (styling, icons, framework) and inherit everything else. The seven core guarantee components stay locked. The framework is forkable along defined seams instead of forkable everywhere.

We chose "helix" rather than "stack" or "tree" because the model expands by adding strand components without redefining a dimension. A new core guarantee fits on the same strand. A new swappable doesn't break the model. The metaphor is biological because the system needs to grow that way.

2. Two architectures, not one

This is the change with the most far-reaching consequences. Before the reframe we described the ecosystem as one stack — UI on top, data substrate underneath, both governed by the same doctrine. Easy to draw. Wrong in practice.

Application architecture and data architecture are governed by different rules, evolve on different timescales, and answer to different sovereignty concerns:

Concern	Application architecture	Data architecture
What it governs	UI primitives, component composition, design tokens, framework choice	Where data lives, who owns it, how it moves, what gets published
Canonical model	Mzizi DNA Helix	Substrate model + four-category ownership lifecycle
Evolves at the speed of	Frontend taste, framework cycles	Storage decisions, regulatory environment, sovereignty posture
What "sovereign" means	"Does this design system depend on a vendor we cannot replace?"	"Does this database depend on a licence or jurisdiction we cannot control?"
Who cares most	Adopters and product engineers	Foundation, platform operators, regulators, enterprise buyers

The two architectures intersect at exactly one defined point: the data node in the Mzizi core. The data node is the application-side interface to the data architecture. From the application's perspective, it's just another core guarantee. From the data architecture's perspective, it's the consumer. The seam is narrow and explicit.

We made this distinction sharp because conflating them was costing us real decisions. A frontend framework choice was bleeding into a database licence discussion. A substrate sovereignty argument was getting tangled in a component-library debate. Naming the two architectures separately means each conversation gets to be the conversation it is.

For people building on the Nyuchi platform, the practical consequence is decoupling: you can adopt our application architecture (Mzizi components, design tokens, the swappable framework slot) without inheriting our substrate decisions, and you can consume the substrate (Postgres, the document tier, the open-data pipeline) without using Mzizi at all. The two layers don't drag each other along.

3. The Foundation owns the architecture

The third change is organisational, and it took the longest to admit.

Until recently the canonical Architecture and Order documents were owned by the Mukoko pillar. Mukoko Architecture v4. The Mukoko Order v4. Mukoko Manifesto v4. Same author, same brand, same masthead. The implicit message was: the architecture is Mukoko's architecture, and the other pillars use it.

The truth is the opposite. The Bundu Foundation owns the architecture and the order. The Foundation is the umbrella — a Zimbabwe Company Limited by Guarantee that governs the four platform tokens, stewards the open standards, and sets the rules under which the ecosystem operates. The architecture is a Foundation-level commitment. The Order — the mathematical doctrine of 3 / 4 / 5 / 7 / 12 / 17 / 40 — is a Foundation-level commitment. They describe the ecosystem, not a single pillar's product.

The Mukoko Manifesto stays where it is. The Manifesto is Mukoko's mission statement — its seven covenants, its twelve sections in chiastic symmetry, its vision of the consumer super-app. That belongs to the pillar and should not be moved.

Two new canonical documents and one preserved:

• The Bundu Order v4 — Foundation-owned. The mathematical doctrine, the pattern language, the three-pillar structure, the federation logic.
• Nyuchi Platform Architecture v4 — Nyuchi-owned. The seven platform layers, the substrate, the FastAPI + Stytch backend, the Honeycomb storage network, the sovereignty assessments, the enterprise product layer.
• Mukoko App Architecture v4 — Mukoko-owned. The seventeen mini-apps, the four substrate components (Twin, Home, Token, Ubuntu Layer), the native shells, the Bridge SDK, the mini-app platform architecture.

What used to be one 548-line document called Mukoko Architecture is now three documents at three levels of the ecosystem — Foundation, platform, app. Each one describes what its owner is actually responsible for, and each one explicitly points to the others for what it doesn't cover.

The third pillar, Shamwari AI, is the intelligence pillar — sovereign by nature, with on-device personal inference, pod-resident conversation context, and no third-party AI vendor dependency. Shamwari runs across the ecosystem and surfaces at shamwari.ai as a pillar in its own right.

What this means if you build on Nyuchi

If you are building on or evaluating the Nyuchi platform, the three reframes give you concrete things you can rely on:

You can pick what to adopt. The decoupling of application and data architectures means you can take the design system without the substrate, take the substrate without the design system, or take both. The seams are explicit. Mzizi's swappable layers (styling, icons, framework) mean you can run our component library against your own visual identity without forking the core guarantees.

You can read the doctrine. Every architectural decision — what substrate we picked and why, what licences we accepted, what we rejected and on what grounds — lives in the Mzizi DNA database as queryable documents. The MCP server at design.nyuchi.com/mcp exposes them to AI coding assistants. Doctrine is not in someone's head; it is in a versioned store with an audit trail.

You can trust the governance. The Foundation owning the architecture and the order means the substrate decisions are not at the mercy of a single operator's commercial pressure. Tokens are governed by a Zimbabwe CLG. Sovereignty assessments are written and queryable. If MongoDB's licence ever becomes unacceptable, that decision is made at the Foundation level and recorded the same way every other decision is recorded.

You can see two architectures clearly. When you're evaluating whether the Nyuchi platform fits your sovereignty requirements, you can look at the data architecture document separately from the application architecture document. They are different questions. They get different answers. You no longer have to disentangle a frontend conversation from a substrate conversation to figure out what we're actually committing to.

What didn't change

None of these reframes broke anything in production. Mukoko's seventeen mini-apps still run on the same seven platform layers. The Five African Minerals palette grew to seven minerals — same discipline, expanded canvas (see the post on the seven minerals). Mzizi's component registry still ships installable components via the shadcn CLI. The Nyuchi Console at platform.nyuchi.com is still being built in the same monorepo with the same SvelteKit-plus-FastAPI-plus-Workers structure.

What changed is how we describe what we built. The descriptions are now closer to the system. That makes the descriptions usable as references — both for our own engineers and for anyone building on us.

Where to read more

The three canonical documents are owned and maintained at:

• The Bundu Order v4 — the mathematical doctrine, owned by the Bundu Foundation
• Nyuchi Platform Architecture v4 — the seven platform layers and the substrate, owned by Nyuchi Africa
• Mukoko App Architecture v4 — the seventeen mini-apps and the consumer experience, owned by Mukoko

Mzizi DNA documentation is queryable at https://design.nyuchi.com. The MCP server is at https://design.nyuchi.com/mcp. Source repositories live under the nyuchi and bundu-labs GitHub organisations.

If you're considering building on the Nyuchi platform — whether you want the design system, the substrate, the identity layer, or all of it — the right starting point is now the Foundation-level overview, then either the platform architecture or the application architecture depending on what you need. They are deliberately separate. You can read them in either order.