The three layers
A consistent, predictable structure for every feature in your app.
Clean React organises every React Native feature into three distinct layers — each with a single, well-defined responsibility.
📦
Domain Module Layer
A single domain module handles the functionality for a single feature in the app — each module is completely isolated from every other module at the domain level.
Each module exposes a strictly typed public API that defines exactly what data it needs and what functionality it provides. Nothing reaches inside its internals.
External integrations connect through a simple type contract, meaning any provider can be swapped without touching anything else in the codebase.
Every module is self-contained, independently testable, and completely unaware of what surrounds it.
🏗️
Connector Layer
The bridge between the domain module and the UI.
The Connector consumes the domain module's public API and implements the type contracts that the UI templates expect — without either layer knowing anything about the other.
Business logic and UI logic remain genuinely independent. The Connector is the only place they meet, and it keeps that boundary clean.
👾
Atomic UI Layer
A hierarchical component library built from the smallest reusable units up — atoms, molecules, organisms, templates.
Every component has a single responsibility and sits at exactly one level of the hierarchy.
Because every UI element is built from the same set of base components, nothing is ever duplicated — the same atom used in ten different places means ten places that update consistently when that atom changes.
The result is a UI that is visually consistent, structurally predictable, and navigable by any engineer from day one.
The principles
The decisions that make Clean React work.
Every principle in Clean React exists to enforce one thing — that every part of the system has a single, well-defined responsibility and an explicit contract with everything around it. That is what makes it consistent, testable, and uniquely suited to agentic development.
Swappable Integrations
Every part of the system is decoupled — each file has a single, well-defined responsibility and communicates with everything around it through explicit type contracts. Every external integration connects through one of those contracts. The implementation behind it can be anything. Switching providers means changing one file. Nothing else in the codebase knows or cares.
Controlled Writes, Optimised Reads
Write operations and read operations are handled deliberately and differently. Write operations go through the domain module's public API — controlled, testable, and provider-agnostic. Read operations go directly through React Query — preserving its full caching and invalidation capabilities without any abstraction getting in the way.
No Duplicated UI
The atomic hierarchy means every UI element exists once and is composed everywhere. The same component used across ten features updates consistently in all ten places. Visual consistency is not a design decision — it is a structural guarantee.
Predictable Failures
Every module has its own error taxonomy. Every possible failure maps to a typed, predictable shape. Engineers always know what a failure looks like and where it came from. Users get consistent, meaningful feedback rather than crashes and blank screens.
Why this matters for AI generation
The architecture that makes AI code generation perform at its best.
AI can generate code for any repo, but that can also be very problematic. Clean React's contract-driven structure means AI agents produce more consistent output, at a fraction of the cost, with far less review and rework — because the architecture gives them exactly what they need and nothing they don't.
Why this matters for engineers
A codebase every engineer can navigate from day one.
Clean React removes the two biggest sources of engineering friction — inconsistency and unpredictability. Every part of the system works the same way, every time.
Why this matters for the business
The architecture is a commercial decision, not just a technical one.
Every architectural decision in Clean React has a direct commercial consequence. This is what the right architecture actually means for your business.
Get in touch
Ready to migrate your React Native app to Clean React?
If your app is holding your business back — let's talk about what a migration would look like for you. The first call is free.
