Frameworks and databases change every three to five years. Business rules last decades. When one is hostage to the other, every technology migration becomes a rewrite project. A system where pricing calculation logic knows the specific ORM, or where the credit approval rule knows which database it is persisting to, has a swap cost that grows with every sprint. When the vendor changes licensing policy, when the technology stops receiving security patches or when the architecture needs to scale in a way the current database does not support, the company discovers that replacing one piece requires touching everything.
Subcapability 03 of 05 · Software Engineering & Architecture
Clean Architecture & Patterns
Clean Architecture Dependency Rule with Hexagonal Architecture, CQRS and Event Sourcing applied to the right contexts, allowing vendor and technology swaps without touching the business logic that matters.
What is at stake
The team wants to swap the database. Or update the framework to receive security patches. Or separate read from write to support the volume the business has reached. In each case, the discovery is the same: the business rule is so entangled with the specific technology that any infrastructure change requires touching the system core. The cost of swapping rises with every sprint that passes without separation of concerns.
What it is, in practice
How we work
Dependency Rule as the central principle
We structure code in layers with dependencies always pointing inward, toward business rules. Entities and Use Cases do not know the database, framework or UI. Each outer layer depends on the inner one, never the reverse.
Ports and Adapters for technology replacement
We define ports that express what the application needs from infrastructure in domain terms, and adapters that implement those contracts with the specific technology. Swapping database or framework means swapping the adapter, without touching business rules.
CQRS where read and write have different requirements
We separate the read model from the write model when both have distinct performance, consistency or scale requirements. The separation allows optimizing each path independently without compromising the other.
Event Sourcing for complete auditability
We implement Event Sourcing in domains where the history of state changes has regulatory or operational value. Current state is derived from the event sequence. Event replay allows reconstructing any past state with full audit trail.
Domain testing without infrastructure dependency
We structure the domain layer to be testable with pure unit tests, without in-memory database, without framework mocks and without integration containers. Fast feedback on the logic that matters most.
Measurable gains
What changes in the result when this subcapability matures.
Cost of swapping infrastructure technology
Business rules isolated in the inner layer reduce the impact scope of each database, framework or external provider change to the corresponding adapter. The swap that previously required a months-long project becomes sprint scope.
Test coverage on critical business logic
Domain without infrastructure dependency enables fast, deterministic unit tests on the logic that matters most for the outcome. Build that runs in minutes, not hours of integration containers.
Time for a new engineer to understand a business rule
Business logic concentrated in the domain layer, without entanglement of persistence or presentation concerns, reduces the time to understand what the system does and where each change should be made.
Impact of framework update on business rules
Frameworks in the outer layer as replaceable details means security patches, version updates and vendor swaps affect only the adapter. The system core remains stable.
Frequently asked questions
Are Clean Architecture, Hexagonal and Onion Architecture the same thing?
They are variations of the same central principle: dependencies pointing toward the domain, infrastructure at the edge. Clean Architecture uses the metaphor of concentric layers with Entities, Use Cases, Interface Adapters and Frameworks. Hexagonal Architecture uses the ports and adapters metaphor. Onion Architecture uses the same layers with slightly different naming. In practice, what determines the result is rigorous application of the dependency rule, not the name the team uses.
Is CQRS worth it for any system?
CQRS has a complexity cost. For systems where read and write have the same performance and consistency requirements, the separation adds indirection without real benefit. The pattern justifies the investment when read and write have different data models, different scale or acceptable eventual consistency on the read side. Those scenarios appear in high-volume systems with distinct query and transaction requirements.
Does Event Sourcing solve all auditability problems?
Event Sourcing ensures complete auditability with replay capability, but has operational cost. The current state of an entity is calculated from the event sequence, which can be slow for entities with long history without snapshots. Query complexity in pure Event Sourcing systems requires separate projections (read models). The pattern is most appropriate for domains where history has intrinsic value: financial, healthcare, contracts.
How to migrate an existing system to Clean Architecture?
The safest approach starts with the modules with the highest change frequency or highest technology swap risk. Identify the Pain First. For each module, isolate business logic in an inner layer without infrastructure dependency. Create adapters for database, external APIs and framework. Validate with unit tests on the domain layer. The Strangler Fig Pattern applies this migration incrementally, without full rewrite and without stopping the system.
How does the team convince the business to invest in architectural separation?
With the cost of the current state in economic language. How long did the last technology swap take? How many bugs appeared in business rules during the framework update? How much of the engineering budget went to remediating problems caused by layer entanglement? Those numbers exist and make the investment in separation of concerns arguable at board level with calculable return.
Other subcapabilities in this capability
Evolutionary Architecture
Fitness functions, ADRs and evolutionary architecture principles that let the system absorb strategy changes without full rewrites and keep the cost of change quantifiable and within manageable limits.
Domain-Driven Design
Domain-Driven Design strategic layer with bounded contexts, ubiquitous language and Event Storming that eliminates the translation layer between business and code, reducing rework and containing domain change cost.
Testing Strategy
Test Pyramid with Consumer-Driven Contracts via Pact and Mutation Testing that build genuine confidence to change production code and eliminate the fear ceremony that slows every release.
Code Quality & Craft
SonarQube Quality Gates, Technical Debt Ratio and Cognitive Complexity metrics that keep delivery velocity sustainable and prevent silent technical debt accumulation from becoming the invisible bottleneck of every future release.
Want clarity on where to invest first?
A complete technology capability assessment with an evolution roadmap connected to financial result.