clean-architecture

Clean Architecture (Hexagonal / Ports & Adapters)

Core rule: business logic must not depend on infrastructure. Infrastructure depends on business logic.

     ┌─────────────────────────────────────────┐
     │           Infrastructure                │
     │  (HTTP, DB, Queue, Email, S3, ...)      │
     │                                         │
     │     ┌───────────────────────────┐       │
     │     │     Application Layer     │       │
     │     │  (Use cases, Commands)    │       │
     │     │                           │       │
     │     │   ┌─────────────────┐    │       │
     │     │   │  Domain Layer   │    │       │
     │     │   │  (Entities,     │    │       │
     │     │   │  Value Objects, │    │       │
     │     │   │  Domain Events) │    │       │
     │     │   └─────────────────┘    │       │
     │     └───────────────────────────┘       │
     └─────────────────────────────────────────┘
         Dependencies only point INWARD →

Layers

Domain (innermost)

• Entities: objects with identity and lifecycle (Order, User)
• Value Objects: immutable, defined by value (Money, Email)
• Domain Events: things that happened (OrderPlaced, PaymentFailed)
• Domain Services: stateless logic that spans entities
• Zero infrastructure imports — no SQLAlchemy, FastAPI, Stripe, etc.

Application

• Use cases / handlers: orchestrate domain objects
• Input/output ports (interfaces): what the use case needs from outside
• No infrastructure imports — depends only on domain + port interfaces

Infrastructure (outermost)

• Adapters that implement ports: SqlUserRepository, StripePaymentGateway
• Framework glue: FastAPI routes, Django views, Express controllers
• Depends on application layer — adapters implement domain/application interfaces

Ports & Adapters

A port is an interface defined in the domain/application layer. An adapter is an infrastructure class that implements a port.

# Port (in application/domain layer)
class UserRepository(Protocol):
    def find_by_id(self, id: UserId) -> User | None: ...
    def save(self, user: User) -> None: ...

# Adapter (in infrastructure layer)
class SqlUserRepository:
    def __init__(self, session: Session) -> None:
        self._session = session

    def find_by_id(self, id: UserId) -> User | None:
        return self._session.get(UserModel, id.value)

    def save(self, user: User) -> None:
        self._session.merge(UserModel.from_domain(user))