Architecture Patterns with Python

Overview

Architecture Patterns with Python (2020) by Harry Percival and Bob Gregory is a hands-on guide to applying proven software architecture patterns — long staples of Java and C# ecosystems — to modern Python applications. Both authors were engineers at MADE.com, and the book grew out of questions Percival fielded after his earlier book on TDD with Django: how do you structure an application so that your core business logic is covered by unit tests and you minimize the number of integration tests needed?

The answer is a layered architecture built around Domain-Driven Design, Ports and Adapters (Hexagonal Architecture), and event-driven patterns — all demonstrated through a single example application (an e-commerce allocation system) built step by step.

The book's core philosophy: your application's business logic should be testable without databases, web servers, or external APIs. Every architectural decision flows from that principle.

The Architecture Stack at a Glance

| Layer | Responsibility | Pattern | |-------|----------------|---------| | Domain Model | Business rules, entities, value objects | DDD Aggregates | | Service Layer | Orchestration, use cases | Unit of Work | | Repository | Data access abstraction | Repository Pattern | | Message Bus | Command/event dispatch | Event Bus | | Adapters | Web, DB, external I/O | Ports and Adapters |

Structure

The book is organized in two parts:

Part I — Building an Architecture to Support Domain Modeling covers the foundational patterns: Repository, Unit of Work, Aggregates, and the Service Layer. Each chapter alternates between writing a failing test and implementing the pattern to make it pass.

Part II — Event-Driven Architecture introduces domain events, the Message Bus, CQRS, and dependency injection. Patterns from Part I are retrofitted as the application grows to handle more complex workflows like email notifications and external API calls.

Key Themes

| Theme | Description | |-------|-------------| | Testability as a Design Force | TDD is not just a testing practice — it shapes the architecture. Patterns emerge from the need to make core logic unit-testable. | | Dependency Inversion | Rely on abstractions (protocols / ABCs), not concrete implementations. The domain model knows nothing about Django, Flask, or SQLAlchemy. | | Domain-Driven Design | Ubiquitous language, bounded contexts, aggregates, and domain events — adapted for Python without Java's ceremony. | | Event-Driven Composition | Side effects (emails, logs, API calls) become event handlers, not inline code. The message bus orchestrates them. | | Incremental Architecture | Start simple (single Flask app + SQLAlchemy). Introduce patterns as complexity demands. No big upfront design. |

Why This Book Matters

Before this book, Python developers had few resources bridging the gap between "tutorial-level Flask/Django apps" and the architectural literature from the Java world (Evans' DDD, Martin's Clean Architecture, Vernon's Implementing DDD). Most Python shops either reinvented these patterns poorly or dismissed them as "too Java."

Percival and Gregory changed that by showing that DDD and hexagonal architecture are not language-specific — they are programmer constructs that work beautifully in Python when adapted idiomatically. The book is also notable for its strict TDD approach: every architectural decision is validated by a test written first.

The companion website (cosmicpython.com) hosts the complete code, exercises, and errata, making this one of the most practical architecture books for the Python community.

Who Should Read

| Reader Type | Why | |---|---| | Python developers building apps that outgrow a single module | The patterns scale with complexity. Start with Repository; add the bus later. | | Developers transitioning from Django/Flask to microservices | Part II directly addresses event-driven decomposition. | | TDD practitioners seeking architectural guidance | Each pattern emerges from the need to write cleaner tests. | | Architects evaluating Python for enterprise | Shows Python can handle DDD and hexagonal patterns without sacrificing expressiveness. |

Related Books

| Book | Connection | |------|------------| | Clean Architecture (Martin) | The theoretical foundation for Ports and Adapters. APWP implements what Clean Architecture preaches, in Python. | | Designing Data-Intensive Applications (Kleppmann) | Deeper treatment of event-driven systems, stream processing, and CQRS at scale. | | Building Microservices (Newman) | APWP's event-driven patterns are a stepping stone to the microservice decomposition Newman describes. | | The Pragmatic Programmer (Hunt) | Shares the same practical, tool-agnostic philosophy — invest in patterns that pay for themselves. | | Design Patterns (GoF) | APWP updates classic GoF patterns (e.g., Command, Observer) for the Python and DDD context. |

Final Verdict

Architecture Patterns with Python is the best practical introduction to DDD and hexagonal architecture for Python developers. Its strength is concreteness: every pattern is accompanied by working code, tests, and a clear explanation of the problem it solves.

The book's limitations are its scope — it covers one medium-sized example, and the treatment of CQRS and event sourcing is introductory. Readers needing production-scale guidance will need to supplement with Kleppmann or Vernon.

Rating: 8.5/10 — Indispensable for the intermediate Python developer; less novel for architects already familiar with the patterns from other languages.

The Architectural Blueprint

The book builds a single e-commerce allocation system across every chapter. The architecture evolves through six layers:

flowchart TB
    subgraph Adapters["Adapters / I/O"]
      Flask["Flask (Web)"]
      DB["SQLAlchemy (DB)"]
      Email["Email (SMTP)"]
      Redis["Redis (Pub/Sub)"]
    end

    subgraph ServiceLayer["Service Layer"]
      Handlers["Command / Event Handlers"]
      UoW["Unit of Work"]
    end

    subgraph Domain["Domain Model"]
      Products["Product Aggregate"]
      Orders["Order Entity"]
      Batches["Batch Entity"]
      Events["Domain Events"]
    end

    subgraph Bus["Message Bus"]
      Router["Command -> Handler Router"]
      EventsQueue["Event Queue"]
    end

    subgraph Tests["Test Suite"]
      UnitT["Unit Tests"]
      IntT["Integration Tests"]
      E2ET["End-to-End Tests"]
    end

    Flask --> Handlers
    DB --> UoW
    UoW --> Products
    UoW --> Orders
    UoW --> Batches
    Handlers --> Router
    Router --> UoW
    Products -.->|"emit"| Events
    Events --> EventsQueue
    EventsQueue --> Router
    Tests -.->|"drive"| Domain
    Tests -.-> ServiceLayer
    Tests -.-> Adapters

The rule: arrows point toward the domain. The domain model depends on nothing. Everything depends on it.

Part I: Building the Foundation

1. Domain Model First

The book starts with a plain Python domain model — no ORM, no framework. An OrderLine value object, a Batch entity, and a Product aggregate. Business rules live here as pure functions:

• Batch.can_allocate() — can this batch fulfill an order line?
• Batch.allocate() — reduce available quantity
• Product.allocate() — find and allocate the best batch

These are tested with zero infrastructure. Pure TDD: write the test, write the domain code, watch it pass.

2. The Repository Pattern

Problem: domain logic tests that hit a real database are slow and brittle. Solution: abstract data access behind a Repository protocol.

class AbstractRepository(ABC):
    @abstractmethod
    def add(self, product):
        ...

    @abstractmethod
    def get(self, sku) -> Product:
        ...

Two implementations follow:

• SqlAlchemyRepository — real database
• FakeRepository — an in-memory dict for tests

The test for allocation now creates a FakeRepository, injects it into the service layer, and verifies business logic without a database. This is the core win: your core logic is testable in milliseconds.

3. The Unit of Work Pattern

The Repository pattern works for reads but doesn't coordinate writes. If allocating an order line triggers multiple repository writes, partial failures leave the database inconsistent.

The Unit of Work captures the atomicity concern:

class AbstractUnitOfWork(ABC):
    products: AbstractRepository

    @abstractmethod
    def commit(self):
        ...

    @abstractmethod
    def rollback(self):
        ...

    def __enter__(self):
        return self

    def __exit__(self, *args):
        self.rollback()

The service layer uses a context manager:

def allocate(order_line: OrderLine, uow: AbstractUnitOfWork):
    with uow:
        product = uow.products.get(order_line.sku)
        product.allocate(order_line)
        uow.commit()

Key benefit: the test can use a FakeUnitOfWork (which bundles a FakeRepository and a no-op commit) and verify that commit() was called. No database needed — even transactional behavior is testable at unit speed.

4. Aggregates and Consistency Boundaries

An Aggregate is a cluster of domain objects treated as a single unit for data changes. The book's Product aggregate contains Batch entities and enforces invariants:

• Cannot allocate more than available stock
• Can deallocate and reallocate
• Emits domain events when state changes

The aggregate is the consistency boundary: within a single aggregate, strong consistency; between aggregates, eventual consistency. This distinction becomes critical in Part II.

5. The Service Layer

The service layer (or use-case layer) orchestrates domain operations without embedding orchestration in the domain or leaking it into the web layer. A typical service function:

1. Retrieves an aggregate via the repository
2. Calls a domain method
3. Commits the unit of work

The Flask endpoint becomes a thin adapter:

@flask.route("/allocate", methods=["POST"])
def allocate_endpoint():
    line = OrderLine(request.json["sku"], ...)
    try:
        allocate(line, uow)
        return OK, 201
    except OutOfStock as e:
        return {"error": str(e)}, 400

No business logic in the controller. The controller just translates HTTP to domain calls and back.

Part II: Going Event-Driven

6. Domain Events

A domain event is something that happened in the domain that domain experts care about:

class Allocated(Event):
    order_id: str
    sku: str
    qty: int
    batch_ref: str

class Deallocated(Event):
    order_id: str
    sku: str
    qty: int

Events are emitted by the aggregate when state changes. They are not yet handled — they are simply recorded:

class Product:
    def allocate(self, line: OrderLine) -> str:
        batch = self._find_batch(line)
        batch.allocate(line)
        self.events.append(
            Allocated(
                order_id=line.order_id,
                sku=line.sku,
                qty=line.qty,
                batch_ref=batch.ref,
            )
        )
        return batch.ref

7. The Message Bus

The Message Bus connects commands (intent) to handlers (behavior) and events (facts) to event handlers (side effects). The bus pattern decouples the caller from the callee:

class MessageBus:
    def __init__(self, uow: AbstractUnitOfWork):
        self.uow = uow

    def handle(self, command: Command):
        handler = COMMAND_HANDLERS[type(command)]
        handler(command, self.uow)
        for event in self.uow.collect_new_events():
            self._handle_event(event)

    def _handle_event(self, event: Event):
        for handler in EVENT_HANDLERS[type(event)]:
            handler(event, self.uow)
            for e in self.uow.collect_new_events():
                self._handle_event(e)

This is the heart of the architecture. Commands are routed to a single handler. Events can have multiple handlers (e.g., send email and update read model). Handlers can emit new events, which the bus recursively processes.

8. CQRS (Command-Query Responsibility Segregation)

The book introduces CQRS as an escape hatch: when the read model diverges from the write model, build a separate read-only view.

For example, allocating products requires aggregates and invariants. But showing a user their order history is a simple query that does not need aggregates at all. CQRS says: use the domain model for writes, use flat queries (raw SQL, materialized views) for reads.

The authors are pragmatic here — CQRS is an option, not a mandate. They introduce it only when the example genuinely needs it.

9. Dependency Injection

The final piece: wire everything together at the entrypoint:

uow = SqlAlchemyUnitOfWork(session_factory)
bus = MessageBus(uow)

app = Flask(__name__)
app.config["bus"] = bus

No global state. No import db from a config module. The bus, the unit of work, and the session are created once and injected. Every component can be swapped for testing.

Key Lessons

• Architecture follows testability. The patterns exist to make core logic testable without infrastructure. If a pattern doesn't improve testability, reconsider it.
• The domain model is the center of the universe. Infrastructure (web, DB, queues) is peripheral. Dependencies point inward.
• Start simple, add patterns as you grow. The book introduces Repository in chapter 2, UoW in chapter 3, events in chapter 8. Each pattern solves a concrete problem that appeared in the previous chapter.
• Python handles these patterns idiomatically. Protocols instead of interfaces, context managers for UoW, simple callables for handlers — no heavy framework needed.
• Events make side effects explicit. Instead of hiding email sending inside allocate(), emit an event and let a handler send it. The domain stays pure; the side effect is visible and testable.

Strengths

• Exceptionally concrete. Most architecture books stay at the diagram level. This one gives you working Python code, with tests, for every pattern. You can run pytest and see the architecture in action. The cosmicpython.com repo is a genuine resource.
• TDD as an architectural tool. The book does not treat testing as an afterthought. Tests come first in every chapter, and the patterns emerge from the need to make those tests fast and reliable. This is a rare and valuable pedagogical approach.
• Pythonic without being sloppy. The authors adapt DDD and hexagonal architecture to Python's idioms — protocols over interfaces, context managers for UoW, simple dicts for the message bus routing. The result is readable and pragmatic rather than ceremonious.
• Excellent pacing. Patterns are introduced one at a time, each motivated by a concrete problem. The book never throws too many concepts at once. By chapter 12 you have a fully event-driven system — but you got there incrementally.
• Honest about trade-offs. The authors flag when a pattern is overkill (CQRS for simple cases, domain events for trivial side effects). They include a chapter on "it's not always DDD" that advises readers when to deviate from the architecture.

Weaknesses

• Single example, limited scope. The allocation domain is simple enough to fit in a book but does not expose the patterns to realistic complexity. Readers working on systems with dozens of aggregates, nested transactions, or distributed sagas will need supplementary material.
• Light on production concerns. The book does not cover monitoring, distributed tracing, idempotency, retry policies, dead-letter queues, or deployment. The message bus is in-process. Turning it into a distributed bus (RabbitMQ, Kafka) is left as an exercise.
• Assumes TDD acceptance. If you are not already a TDD practitioner, the strict test-first flow may feel forced. The book does not argue for TDD — it assumes you already buy in.
• Limited TypeScript / typing coverage. Protocols are used for dependency abstraction, but the broader typing story (Pydantic for value objects, generic repository types) is underdeveloped by modern Python 3.12+ standards.
• CQRS treatment is introductory. The CQRS chapter is the shortest in the book and does not address read-model synchronization latency, eventual consistency failure modes, or multi-service CQRS topologies.

Critique

The "TDD First" Approach

The book's defining choice — every pattern emerges from a failing test — is both its greatest strength and a source of friction. Readers who prefer understanding the architecture before writing code may find the test-first rhythm distracting. The tests occasionally triage design decisions that would be clearer with a diagram-first explanation. That said, for readers who already write tests, this approach validates that the patterns actually deliver testability — they are not just aspirational diagrams.

Abstraction Inversion Risk

The Repository and Unit of Work patterns abstract SQLAlchemy, but SQLAlchemy already has its own unit of work (the session). The book's UoW is essentially an adapter around SQLAlchemy's session. Critics argue this adds a layer of indirection without proportional value — especially since swapping SQLAlchemy for another ORM is rare in practice. The authors acknowledge this trade-off and argue the value is in testability, not ORM-swappability.

Event Bus as In-Process

The book's message bus runs in-process. Events are handled synchronously in the same transaction. This works for the example but does not prepare readers for event-driven failures in production: a handler crashes, the event is lost, and the system is inconsistent. The book notes this limitation but does not address compensating transactions or outbox patterns.

Comparison to Similar Books

| Book | Key Difference | |------|----------------| | Clean Architecture (Martin) | Martin is theoretical and language-agnostic. APWP is Python-specific and hands-on. Read Martin for why; read APWP for how. | | Designing Data-Intensive Applications (Kleppmann) | DDIA focuses on distributed data systems at scale. APWP focuses on in-process architecture. They complement rather than overlap. | | Building Microservices (Newman) | Newman assumes services already exist. APWP shows how to structure a single service so it can be decomposed later. | | Domain-Driven Design (Evans) | Evans is the canonical DDD reference — dense, comprehensive, language-agnostic. APWP is a Python-focused subset. | | Implementing Domain-Driven Design (Vernon) | Vernon is more complete than APWP but uses Java. APWP is the best Python alternative to Vernon. |

Final Assessment

| Dimension | Rating | Notes | |-----------|--------|-------| | Practical Utility | 9/10 | Every pattern has runnable code; the test-first approach proves each works | | Originality | 7/10 | Patterns are known; the Python adaptation and TDD pedagogy are novel | | Readability | 8/10 | Clean, conversational prose; code examples are well-commented | | Depth | 7/10 | Covers one example thoroughly; does not venture into multi-service territory | | Python Fit | 9/10 | Idiomatic, framework-agnostic Python — not Java translated to Python | | Overall | 8/10 | The best book on architecture patterns in and for Python |

Architecture Patterns with Python fills a genuine gap: it teaches proven patterns with Python code, not Java diagrams. It is not a comprehensive architecture handbook — it is a practical, test-driven introduction to the patterns that matter most for greenfield Python projects. Its shelf life will be long because the patterns it covers precede any framework or version.