Clean Architecture

advanced2 min read

TypeScript
Node.js

An approach that puts business rules at the centre and makes all dependencies point inward, so frameworks, databases, and UI become replaceable details.

Prerequisites

Layered architecture and dependency inversion (see Related Topics)

What you'll understand

What the dependency rule is
Why business rules sit at the centre
How this makes frameworks and databases replaceable details

Explanation

Clean architecture (closely related to hexagonal or ports-and-adapters architecture) is a way of structuring a system around one central idea: the dependency rule. Source-code dependencies must point only inward, toward the business rules. The innermost circle holds your core domain logic; outer circles hold application logic, then interface adapters, then the outermost details, the web framework, the database, the UI.

Putting business rules at the centre inverts the usual relationship. Normally code depends on its framework and database; here those are the outermost layer and depend on the core, never the other way around. The core defines interfaces (ports) that the outer layers implement (adapters), so the domain says what it needs and the details plug in from outside. This is dependency inversion (see Related Topics) applied at the scale of a whole system.

The payoff is that everything on the outside becomes a replaceable detail. Because the core does not depend on the database or the web framework, you can swap Postgres for another store, or Express for another framework, without touching business logic, and you can test that logic with no database or HTTP at all. The cost is more indirection and structure, which is overkill for small apps. Clean architecture earns its keep in large, long-lived systems where protecting the core from churn at the edges is worth the extra ceremony.

Examples

The dependency rule: all arrows point inward, toward the business rules:

Frameworks & Drivers (web, db)     outermost
   -> Interface Adapters (controllers, gateways)
      -> Application Logic (use cases)
         -> Entities / Domain Rules      innermost

Dependencies point inward only; the core knows nothing of the outside.

Common mistakes

Letting the core domain import the framework or database, breaking the dependency rule.
Applying full clean architecture to a small app that does not need it.
Creating so many layers and interfaces that simple changes become tedious.
Confusing the goal (protect the core) with the ritual (adding boilerplate).

Best practices

Keep business rules at the centre, free of framework and database details.
Point all dependencies inward; let the core define interfaces the outside implements.
Reserve this structure for large, long-lived systems (see Related Topics).
Prefer simpler layering when the extra indirection is not justified.