Clean Architecture Explained

Concentric layers with strict dependency rules that keep business logic independent of frameworks, databases, and delivery mechanisms.

Clean Architecture

Clean Architecture is a software design philosophy by Robert C. Martin that organizes code into concentric layers with strict dependency rules, ensuring that business logic remains independent of frameworks, databases, and UI.

Explanation

Most applications start with framework-first thinking: pick a framework (Rails, Django, Next.js), follow its conventions, and scatter business logic throughout controllers, models, and views. When the framework changes or you need to swap the database, the business logic is tangled with infrastructure and must be rewritten. Clean Architecture inverts this. Business logic lives at the center (entities and use cases), surrounded by interface adapters (controllers, presenters, gateways), with frameworks and infrastructure at the outermost layer. The dependency rule is absolute: inner layers know nothing about outer layers. A use case does not know whether data comes from PostgreSQL or MongoDB, or whether it is called from a REST API or a CLI. This separation enables testability (use cases can be tested without databases or HTTP), replaceability (swap frameworks or databases without touching business logic), and clarity (each layer has a single responsibility). The cost is more files and indirection — a simple CRUD operation requires entities, use cases, repositories, and controllers that might feel like overkill for trivial features.

Bookuvai Implementation

Bookuvai applies Clean Architecture principles to projects with complex business logic. Our codebase structure separates domain entities, use cases, repository interfaces, and infrastructure implementations. This enables comprehensive unit testing of business rules without mocking infrastructure and makes it straightforward to swap data sources or add new delivery mechanisms.

Key Facts

  • The Dependency Rule: source code dependencies point inward only
  • Business logic is independent of frameworks, databases, and UI
  • Enables testing use cases without any infrastructure (databases, HTTP)
  • Popularized by Robert C. Martin ("Uncle Bob") in 2012
  • Similar to Hexagonal Architecture and Onion Architecture

Related Terms

Frequently Asked Questions

Is Clean Architecture the same as Hexagonal Architecture?
They share the same core principle — isolate business logic from infrastructure — but differ in terminology and structure. Clean Architecture uses concentric layers; Hexagonal Architecture uses ports and adapters. In practice, they achieve the same goal.
Is Clean Architecture overkill for small projects?
For simple CRUD applications, the additional layers add unnecessary complexity. Clean Architecture shines in applications with complex business rules that need to be tested independently and may outlive their initial framework choice.
What is the dependency rule?
The dependency rule states that source code dependencies must point inward — toward higher-level policies. Inner layers (business logic) must not reference outer layers (frameworks, databases). This is enforced through interfaces and dependency injection.