Architecture

Choose Between Layered, Hexagonal, and Clean Architecture

Compare common architecture styles and select boundaries that fit application complexity and team needs.

Architecture styles are tools for organizing dependencies and change. Layered, hexagonal, and clean architecture can all support maintainable systems, but they emphasize different boundaries.

Layered architecture

A conventional layered design separates presentation, application logic, domain rules, and infrastructure. It is easy to explain and often works well for CRUD-oriented applications. The main risk is allowing business rules to leak into controllers or persistence code.

Hexagonal architecture

Ports and adapters isolate application behavior from external systems. A port describes a capability the application needs, while an adapter connects that capability to a database, queue, or provider. This is useful when external integrations vary or need independent testing.

Clean architecture

Clean architecture emphasizes dependency direction: inner business policy should not depend on outer frameworks or delivery mechanisms. It can provide strong separation, but too many layers and interfaces can burden a small application.

Choose based on pressure

Start with the simplest structure that keeps responsibilities clear. A modular monolith with explicit boundaries is often a good default. Introduce more formal ports where infrastructure substitution, testing, or independent evolution justifies them.

Checklist

  • Map the application's change boundaries.
  • Keep domain rules independent of HTTP details.
  • Isolate unstable external integrations.
  • Avoid layers that merely forward calls.
  • Revisit architecture when complexity creates measurable friction.
Share this page Help other developers discover this resource.