architecture-patterns

name	architecture-patterns
description	Implement proven backend architecture patterns including Clean Architecture, Hexagonal Architecture, and Domain-Driven Design. Use when architecting complex backend systems or refactoring existing applications for better maintainability.

Architecture Patterns

Master proven backend architecture patterns including Clean Architecture, Hexagonal Architecture, and Domain-Driven Design to build maintainable, testable, and scalable systems.

When to Use This Skill

• Designing new backend systems from scratch
• Refactoring monolithic applications for better maintainability
• Establishing architecture standards for your team
• Migrating from tightly coupled to loosely coupled architectures
• Implementing domain-driven design principles
• Creating testable and mockable codebases
• Planning microservices decomposition

Core Concepts

1. Clean Architecture (Uncle Bob)

Layers (dependency flows inward):

• Entities: Core business models
• Use Cases: Application business rules
• Interface Adapters: Controllers, presenters, gateways
• Frameworks & Drivers: UI, database, external services

Key Principles:

• Dependencies point inward
• Inner layers know nothing about outer layers
• Business logic independent of frameworks
• Testable without UI, database, or external services

2. Hexagonal Architecture (Ports and Adapters)

Components:

• Domain Core: Business logic
• Ports: Interfaces defining interactions
• Adapters: Implementations of ports (database, REST, message queue)

Benefits:

• Swap implementations easily (mock for testing)
• Technology-agnostic core
• Clear separation of concerns

3. Domain-Driven Design (DDD)

Strategic Patterns:

• Bounded Contexts: Separate models for different domains
• Context Mapping: How contexts relate
• Ubiquitous Language: Shared terminology

Tactical Patterns:

• Entities: Objects with identity
• Value Objects: Immutable objects defined by attributes
• Aggregates: Consistency boundaries
• Repositories: Data access abstraction
• Domain Events: Things that happened

Clean Architecture Pattern

Directory Structure

app/
├── domain/           # Entities & business rules
│   ├── entities/
│   │   ├── user.py
│   │   └── order.py
│   ├── value_objects/
│   │   ├── email.py
│   │   └── money.py
│   └── interfaces/   # Abstract interfaces
│       ├── user_repository.py
│       └── payment_gateway.py
├── use_cases/        # Application business rules
│   ├── create_user.py
│   ├── process_order.py
│   └── send_notification.py
├── adapters/         # Interface implementations
│   ├── repositories/
│   │   ├── postgres_user_repository.py
│   │   └── redis_cache_repository.py
│   ├── controllers/
│   │   └── user_controller.py
│   └── gateways/
│       ├── stripe_payment_gateway.py
│       └── resend_email_gateway.py
└── infrastructure/   # Framework & external concerns
    ├── database.py
    ├── config.py
    └── logging.py

Implementation Example

# domain/entities/user.py
from dataclasses import dataclass
from datetime import datetime
from typing import Optional

@dataclass
class User:
    """Core user entity - no framework dependencies."""
    id: str
    email: str
    name: str
    created_at: datetime
    is_active: bool = True

    def deactivate(self):
        """Business rule: deactivating user."""
        self.is_active = False

    def can_place_order(self) -> bool:
        """Business rule: active users can order."""
        return self.is_active

# domain/interfaces/user_repository.py
from abc import ABC, abstractmethod
from typing import Optional, List
from domain.entities.user import User

class IUserRepository(ABC):
    """Port: defines contract, no implementation."""

    @abstractmethod
    async def find_by_id() -> [User]:
        


      () -> [User]:
        


      () -> User:
        


      () -> :
        


 domain.entities.user  User
 domain.interfaces.user_repository  IUserRepository
 dataclasses  dataclass
 datetime  datetime
 uuid


 :
    email: 
    name: 


 :
    user: [User]
    success: 
    error: [] = 

 :
    

     ():
        .user_repository = user_repository

      () -> CreateUserResponse:
        
        existing =  .user_repository.find_by_email(request.email)
         existing:
             CreateUserResponse(
                user=,
                success=,
                error=
            )

        
        user = User(
            =(uuid.uuid4()),
            email=request.email,
            name=request.name,
            created_at=datetime.now(),
            is_active=
        )

        
        saved_user =  .user_repository.save(user)

         CreateUserResponse(
            user=saved_user,
            success=
        )


 domain.interfaces.user_repository  IUserRepository
 domain.entities.user  User
 typing  
 asyncpg

 ():
    

     ():
        .pool = pool

      () -> [User]:
          .pool.acquire()  conn:
            row =  conn.fetchrow(
                , user_id
            )
             ._to_entity(row)  row  

      () -> [User]:
          .pool.acquire()  conn:
            row =  conn.fetchrow(
                , email
            )
             ._to_entity(row)  row  

      () -> User:
          .pool.acquire()  conn:
             conn.execute(
                ,
                user., user.email, user.name, user.created_at, user.is_active
            )
             user

      () -> :
          .pool.acquire()  conn:
            result =  conn.execute(
                , user_id
            )
             result == 

     () -> User:
        
         User(
            =row[],
            email=row[],
            name=row[],
            created_at=row[],
            is_active=row[]
        )


 fastapi  APIRouter, Depends, HTTPException, Request
 use_cases.create_user  CreateUserUseCase, CreateUserRequest
 adapters.repositories.user_repository  PostgresUserRepository
 pydantic  BaseModel

router = APIRouter()

 ():
    email: 
    name: 

 () -> CreateUserUseCase:
    
    repository = PostgresUserRepository(request.app.state.db_pool)
     CreateUserUseCase(user_repository=repository)


  ():
    
    request = CreateUserRequest(email=dto.email, name=dto.name)
    response =  use_case.execute(request)

      response.success:
         HTTPException(status_code=, detail=response.error)

     {: response.user}

Hexagonal Architecture Pattern

# Core domain (hexagon center)
import asyncio

class OrderService:
    """Domain service - no infrastructure dependencies."""

    def __init__(
        self,
        order_repository: OrderRepositoryPort,
        payment_gateway: PaymentGatewayPort,
        notification_service: NotificationPort
    ):
        self.orders = order_repository
        self.payments = payment_gateway
        self.notifications = notification_service

    async def place_order(self, order: Order) -> OrderResult:
        # Business logic
        if not order.is_valid():
            return OrderResult(success=False, error="Invalid order")

        # Use ports (interfaces)
        payment = await self.payments.charge(
            amount=order.total,
            customer=order.customer_id
        )

        if not payment.success:
            return OrderResult(success=False, error="Payment failed")

        order.mark_as_paid()
        saved_order = await self.orders.save(order)

        await self.notifications.send(
            to=order.customer_email,
            subject="Order confirmed",
            body=f"Order {order.id} confirmed"
        )

        return OrderResult(success=True, order=saved_order)


 ():

      () -> Order:
        

 ():

      () -> PaymentResult:
        

 ():

      ():
        


 ():
    

     ():
        .stripe = stripe
        .stripe.api_key = api_key

      () -> PaymentResult:
        :
            
            charge =  asyncio.to_thread(
                .stripe.Charge.create,
                amount=amount.cents,
                currency=amount.currency,
                customer=customer,
            )
             PaymentResult(success=, transaction_id=charge.)
         stripe.error.CardError  e:
             PaymentResult(success=, error=(e))

 ():
    

      () -> PaymentResult:
         PaymentResult(success=, transaction_id=)

Domain-Driven Design Pattern

# Value Objects (immutable)
from dataclasses import dataclass
from typing import Optional

@dataclass(frozen=True)
class Email:
    """Value object: validated email."""
    value: str

    def __post_init__(self):
        if "@" not in self.value:
            raise ValueError("Invalid email")

@dataclass(frozen=True)
class Money:
    """Value object: amount with currency."""
    amount: int  # cents
    currency: str

    def add(self, other: "Money") -> "Money":
        if self.currency != other.currency:
            raise ValueError("Currency mismatch")
        return Money(self.amount + other.amount, self.currency)

# Entities (with identity)
class Order:
    """Entity: has identity, mutable state."""

    def __init__():
        . = 
        .customer = customer
        .items: [OrderItem] = []
        .status = OrderStatus.PENDING
        ._events: [DomainEvent] = []

     ():
        
        item = OrderItem(product, quantity)
        .items.append(item)
        ._events.append(ItemAddedEvent(., item))

     () -> Money:
        
          .items:
             ValueError()

        total = .items[].subtotal()
         item  .items[:]:
            total = total.add(item.subtotal())
         total

     ():
        
          .items:
             ValueError()
         .status != OrderStatus.PENDING:
             ValueError()

        .status = OrderStatus.SUBMITTED
        ._events.append(OrderSubmittedEvent(.))


 :
    

     ():
        . = 
        .email = email
        ._addresses: [Address] = []
        ._orders: [] = []  

     ():
        
         (._addresses) >= :
             ValueError()
        ._addresses.append(address)


     () -> [Address]:
         ((a  a  ._addresses  a.is_primary), )



 :
    order_id: 
    occurred_at: datetime = field(default_factory=datetime.now)


 :
    

      () -> [Order]:
        
        

      ():
        
         ._persist(order)
         ._publish_events(order._events)
        order._events.clear()

Resources

• references/clean-architecture-guide.md: Detailed layer breakdown
• references/hexagonal-architecture-guide.md: Ports and adapters patterns
• references/ddd-tactical-patterns.md: Entities, value objects, aggregates
• assets/clean-architecture-template/: Complete project structure
• assets/ddd-examples/: Domain modeling examples

Best Practices

1. Dependency Rule: Dependencies always point inward
2. Interface Segregation: Small, focused interfaces
3. Business Logic in Domain: Keep frameworks out of core
4. Test Independence: Core testable without infrastructure
5. Bounded Contexts: Clear domain boundaries
6. Ubiquitous Language: Consistent terminology
7. Thin Controllers: Delegate to use cases
8. Rich Domain Models: Behavior with data

Common Pitfalls

• Anemic Domain: Entities with only data, no behavior
• Framework Coupling: Business logic depends on frameworks
• Fat Controllers: Business logic in controllers
• Repository Leakage: Exposing ORM objects
• Missing Abstractions: Concrete dependencies in core
• Over-Engineering: Clean architecture for simple CRUD