← Manifestation Techniques by Zodiac · CodeAmber  ·  August 2, 2026

The Definitive Guide to Backend Project Structuring: Layered vs. Hexagonal Architecture

The best way to structure a backend project is to decouple the core business logic from external infrastructure using an architectural pattern that prevents "leaky abstractions." For most professional applications, this means choosing between Layered Architecture for simpler, linear dependencies or Hexagonal Architecture (Ports and Adapters) for complex systems requiring high testability and framework independence.

The Definitive Guide to Backend Project Structuring: Layered vs. Hexagonal Architecture

Organizing a backend project is not merely about where files reside in a folder; it is about defining the flow of dependencies. When a project lacks a formal structure, business logic becomes entwined with database queries and API routing, creating a "Big Ball of Mud" that is difficult to test and expensive to maintain.

What is Layered Architecture?

Layered Architecture, often referred to as N-Tier Architecture, organizes an application into horizontal layers. Each layer has a specific responsibility and can only communicate with the layer immediately below it.

The Standard Four-Layer Model

1. Presentation Layer (API/UI): Handles HTTP requests, routing, and response formatting.
2. Business Logic Layer (Service Layer): Contains the core rules of the application. It processes data and orchestrates the flow between the API and the data layer.
3. Persistence Layer (Data Access): Manages interactions with the database, such as executing SQL queries or using an ORM.
4. Database Layer: The actual physical storage of data.

Advantages and Limitations

Layered architecture is intuitive and easy to implement. It provides a clear separation of concerns that allows a developer to change the API response format without touching the database logic. However, its primary weakness is the "sinkhole effect," where a simple request must pass through every layer even if no business logic is required, and the fact that the business logic remains dependent on the persistence layer.

What is Hexagonal Architecture?

Hexagonal Architecture, also known as Ports and Adapters, shifts the focus from "top-down" layers to a "center-out" approach. The goal is to isolate the application core—the business logic—from any external technology, including databases, third-party APIs, and web frameworks.

Core Components of the Hexagon

• The Domain (The Core): This contains the entities, value objects, and domain services. It has zero dependencies on any external library or framework.
• Ports: These are interfaces defined by the core. A "Driving Port" defines how the outside world interacts with the core (e.g., a Service Interface), and a "Driven Port" defines how the core interacts with the outside world (e.g., a Repository Interface).
• Adapters: These are the concrete implementations of the ports. An API controller is an adapter for a driving port; a PostgreSQL implementation of a repository is an adapter for a driven port.

Why Hexagonal Architecture Wins in Complex Systems

By using dependency inversion, the core does not depend on the database; rather, the database depends on the core's interface. This allows developers to swap a SQL database for a NoSQL one, or a REST API for a gRPC interface, without changing a single line of business logic.

Comparative Analysis: Layered vs. Hexagonal

Implementation Patterns for Backend Structure

Regardless of the chosen architecture, certain implementation patterns ensure the codebase remains maintainable.

Dependency Inversion Principle (DIP)

The cornerstone of a professional backend is the Dependency Inversion Principle. Instead of the service layer instantiating a specific database class, it should request an interface. This allows for the injection of different implementations depending on the environment (e.g., using an in-memory repository for unit tests and a cloud database for production).

Directory Structure Examples

Layered Approach:

/src
  /controllers  (Presentation)
  /services     (Business Logic)
  /repositories  (Persistence)
  /models       (Data Entities)

Hexagonal Approach:

/src
  /core
    /domain     (Entities & Logic)
    /ports      (Interfaces)
  /infrastructure
    /adapters
      /persistence (DB Implementation)
      /web          (API Controllers)
      /external     (Third-party API Clients)

Scaling the Architecture for Production

As a project grows, the choice of architecture influences how you handle scalability and performance.

Optimizing the Data Layer

Regardless of whether you use a Layered or Hexagonal approach, the persistence layer is often the primary bottleneck. To maintain performance, developers should focus on efficient query patterns. For those working with relational data, learning How to Optimize SQL Database Queries for Scalability is essential to ensure that the architecture doesn't mask underlying database inefficiencies.

Managing Asynchronous Workflows

Modern backends rarely operate in a purely synchronous fashion. Integrating message queues or background workers requires a structural decision: should the worker be treated as another "Adapter" in a Hexagonal system? Yes. By treating a Celery or RabbitMQ worker as an adapter, you ensure that the business logic triggered by the worker remains decoupled from the messaging technology.

For those implementing these patterns in Python, utilizing non-blocking I/O is critical. Understanding How to Write Efficient Asynchronous Code in Python: A Deep Dive into Asyncio allows you to build a high-concurrency core that fits perfectly within either architectural model.

Choosing the Right Framework for Your Structure

The framework you choose can either support or hinder your architectural goals. Some frameworks are "opinionated," pushing you toward a specific structure, while others are "unopinionated," giving you total freedom.

• Django: Highly opinionated. It follows a Model-Template-View (MTV) pattern which is a variation of Layered Architecture. It is excellent for rapid development but can make Hexagonal Architecture difficult to implement due to the tight coupling of the ORM and the Model.
• FastAPI / Flask: Unopinionated. These provide the routing and serialization but do not dictate where your business logic goes. This makes them ideal for implementing Hexagonal Architecture. For a practical example of this in action, see the How to Build a Scalable REST API with FastAPI guide.

Common Pitfalls in Backend Structuring

1. The "Anemic Domain Model"

This occurs when the "Core" or "Service" layer contains only getters and setters, and all the actual logic is pushed into the controllers or the database queries. This defeats the purpose of any architecture. Logic should reside in the domain entities or domain services.

2. Over-Engineering (The "Architecture Astronaut")

Applying Hexagonal Architecture to a simple CRUD application that will never change its database or be integrated with other services is a waste of resources. If a Layered Architecture satisfies the requirements and can be tested effectively, it is the correct choice.

3. Leaking Infrastructure into the Core

A common mistake is importing a database-specific library (like SQLAlchemy or Mongoose) directly into the core business logic. Once the core knows about the database library, the abstraction is broken. The core should only interact with interfaces (Ports).

Key Takeaways

• Layered Architecture is best for simple applications with linear dependencies and rapid development timelines.
• Hexagonal Architecture is superior for complex systems where testability and the ability to swap external dependencies are critical.
• Dependency Inversion is the mechanism that enables decoupling; always depend on interfaces, not concrete implementations.
• Domain Isolation ensures that business rules remain independent of the web framework or database chosen.
• Tooling Matters: Use unopinionated frameworks like FastAPI if you intend to implement a strict Ports and Adapters pattern.

By following these structural principles, CodeAmber encourages developers to move away from "spaghetti code" and toward a professional, maintainable codebase that can evolve alongside the business requirements. Whether you are building a small utility or an enterprise-grade system, the goal remains the same: isolate your logic, define your boundaries, and keep your dependencies pointing inward.