Clean Architecture with Python • Sam Keen & Max Kirchoff • GOTO 2025

In this interview, Sam Keen, author of “Clean Architecture with Python,” discusses the core principles of applying clean architecture to Python development in a pragmatic and non-dogmatic way. The primary motivation for the book was to provide a resource for thoughtful architecture in a Python context, moving beyond the many “learn Python” books and focusing on principles that enhance long-term maintainability.

The Core Promise: Thoughtful Dependency Management

The main promise of clean architecture is to manage dependencies thoughtfully. It’s not a rigid, all-or-nothing framework, but rather a set of principles that developers can adapt to their specific context. The book aims to be empathetic to the practical realities of software development, acknowledging that business needs and deadlines exist. The core idea is to understand the principles and apply them where they provide the most value, avoiding the trap of “dependency hell” in long-running applications.

Balancing Principles with Python’s Pragmatism

A key challenge addressed is how to apply architectural principles, which often originate from statically-typed languages like Java, to a dynamic and pragmatic language like Python without making it overly complex. The book achieves this by:

• Leveraging Pythonic Features: It utilizes built-in features like type hints, Abstract Base Classes (ABCs), and protocols to implement architectural patterns naturally within the Python ecosystem.
• Avoiding a Binary Choice: The book presents the full gamut of principles but emphasizes that their application is context-dependent. It shows how to “thin down” the layers and patterns for simpler applications like a straightforward API to avoid accidental complexity.
• Focusing on Code and Concepts: Instead of theoretical UML diagrams, the book uses concise code examples to illustrate principles. A companion to-do application on GitHub provides more extensive, functional code for each chapter, striking a balance between conceptual explanation and practical implementation.

The Onion Model and the Dependency Rule

The architecture is structured in layers, often visualized as an onion or a bullseye:

1. Domain Layer: The innermost core, containing the essential business logic and domain objects. It has zero dependencies on any other layer or framework.
2. Application Layer: Orchestrates the use cases by managing the state of domain objects. It depends on the domain layer but not on external frameworks.
3. Adoption Layer (Adapters): Contains the code that adapts external technologies (databases, web frameworks) to the application’s core. This is where interfaces defined in the application layer are implemented.
4. Framework Layer: The outermost layer, consisting of frameworks and libraries like Django, Flask, or SQL Alchemy.

The most crucial principle is the Dependency Rule: all dependencies point inward. The outer layers can see the inner layers, but the inner layers know nothing about the outer ones. This isolates the core business logic—the most valuable part of the application—from the implementation details, which are more likely to change.

Architecture Is Key to Testability

A central theme is the relationship between architecture and testability. Test friction is often a sign of poor architecture. If tests are hard to write, it’s a signal that the production code is tightly coupled and difficult to use.

Clean architecture enables the ideal Test Pyramid:

• Unit Tests: The domain layer, having no dependencies, is extremely easy to unit test. Tests are fast, simple, and require no mocks for external systems.
• Integration Tests: The application layer is tested by coding against interfaces (e.g., a repository pattern for persistence). Tests can use in-memory implementations or simple mocks instead of spinning up databases or external services.
• End-to-End Tests: Because the core logic is thoroughly tested at lower levels, the number of slow, brittle end-to-end tests can be drastically reduced. They are reserved only for critical user flows.

Clean Architecture in the Age of AI

While not explicitly covered in the book, clean architecture principles are highly relevant for AI-assisted development:

• Scoping for AI Agents: AI models struggle with large, undifferentiated context windows (a problem called “context rot”). The layered structure of clean architecture allows a developer to scope tasks for the AI (e.g., “implement this interface in the adapter layer”), making the AI more effective.
• A Plan for the AI: The principles provide a “rule book” or a foundation for a system prompt that can guide the AI to generate well-structured code.
• Human-AI Collaboration: It allows for a powerful division of labor. The human developer, as the domain expert, can focus on the high-value work of designing the domain model and defining interfaces. The AI can then be tasked with the boilerplate work of implementing concrete adapters (e.g., “write the SQL Alchemy implementation for this persistence interface”).

The Main Takeaway

The ultimate takeaway is a recalibration of what constitutes value in a software application. The frameworks and libraries (Flask, Django, Superbase) are just details. The true, lasting value lies in the codified understanding of the business domain. This core logic should be clear, concise, and isolated from the churn of external technologies.

• Tags:
• Feature
• Python
• Test Driven Development
• AI-Assisted Development
• Software Design
• Domain-Driven Design
• Clean Architecture
• Dependency Management