Presenters
Source
Welcome to the GoTo Podcast Book Club! 🚀 Today, we’re diving deep into the world of Clean Architecture in Python with none other than its brilliant author, Sam Keen, in a captivating chat with GoTo’s Max Kirchoff. Get ready to transform your approach to Python development!
Sam’s Journey to Clean Architecture 💡
Sam Keen is a seasoned software developer with nearly 30 years of experience, spanning the entire web era. He started his career in Java, then explored PHP, rode the Ruby on Rails train, and for the last 8 to 10 years, Python has been his daily go-to for backend web development. Sam has worked across a diverse range of companies, from small startups to giants like Nike, Lululemon, and AWS (where he spent six and a half years).
His motivation to write Clean Architecture in Python came when Packt Publishing reached out in February 2024 with the idea. For Sam, it was a perfect fit: he’d always been thoughtful about architecture, resonated with “clean” and “onion-type” architectures, and always wanted to write a book. This project allowed him to dive deep into a topic he truly loves.
Max’s Perspective: A Reader’s Delight ✨
Our host, Max Kirchoff, CTO at GKO and a self-proclaimed “principal technologist,” has a unique appreciation for Sam’s work. Max and Sam worked together 15 years ago at one of the first social e-commerce platforms. Max credits Sam with teaching him architectural principles that shaped his entire career. He recalls Sam building a microservice architecture with RESTful APIs and a custom DSL in PHP, which later influenced Max’s work with Flask and Python.
Max’s current work involves heavy Python use for data operations (Jupyter notebooks, Python pipelines) and building an AI companion backend for parents, leveraging Python’s strengths with LLMs and AI/ML models. He found Sam’s book incredibly practical, noticing how it fleshed out principles he learned years ago and even called out some “hilarious aspects” of his own current backend architecture that needed improvement. Max praises the book as immediately applicable and impactful.
The Core Promise: Taming Dependencies 💡
Max asked Sam about the core promise of Clean Architecture in Python. Sam quickly distilled it: it’s all about dependencies. We need them, but if we don’t approach them thoughtfully, “dependency health” can fester, creating sharp edges in long-running architectures. Clean architecture isn’t a rigid framework; it’s a set of principles that guides you to be thoughtful about managing these dependencies. The book emphasizes that it’s not an all-or-nothing approach, allowing you to adapt principles to your specific context. Max appreciated this “shame-free” and empathetic approach for practical engineers.
Pythonic Pragmatism Meets Clean Architecture 🐍
Sam faced a core challenge: how to apply clean architecture principles without turning Python into Java, a common misconception given the origins of clean architecture in Java/C++ contexts. His solution was to make it resonate with the Python audience. The book leverages native Python features like typings, ABCs (Abstract Base Classes), and protocols, sticking to Python’s “batteries included” philosophy. The key message is flexibility: the book lays out all principles but also guides you on how to thin down the application of these principles based on your context.
Striking the Balance: Architecture & Developer Experience ✨
Sam deliberately did not write a “learn Python” book. He focused on filling a gap in the Python ecosystem: architecture-focused content. While Uncle Bob’s original book was theory-heavy, Sam’s book provides just enough code to illustrate principles without getting bogged down. There are no UML diagrams in the book! For those who want more code, a companion to-do application on GitHub evolves with each chapter, offering extensive functional code examples. This approach ensures the book remains approachable, practical, and focused on architectural principles that enhance the developer experience.
The “Strict Inside, Flexible Outside” Principle 🧅
This crucial principle underpins the onion-layered structure of clean architecture. Imagine a bullseye diagram:
- Inner Layers (Core Domain Objects): These are the most important. They represent your core business rules and domain logic. They have no dependencies on outer layers. Sam emphasizes deep thought and conversation with business partners to design these.
- Application Layer: This layer applies the core business rules and manages the state of the inner domain objects. It has few dependencies.
- Adaptation Layer: This layer decouples the inner layers from the outermost framework layer. It’s context-specific, allowing you to thin it down based on your application type (CLI, web app, API).
- Framework Layer: The outermost, most chaotic layer, which sees all internal layers.
Max shared a vivid example of poor implementation: someone building GraphQL on top of a key-value store that wasn’t a graph database. This introduced unnecessary complexity at the interface layer, demonstrating the biggest mistake of mangling things in the interface and application layers. Sam noted that while it’s tempting to “hack it together” in a fast-paced environment, the real challenge is remembering to fix it later.
Testing: The True Mirror of Architecture Health 🛠️
Max strongly believes that great clean architecture is very testable. He states, “Show me your tests,” because if you struggle to write tests at different layers of the pyramid, something is likely wrong with the architecture. Sam agrees, asserting that test friction is a gauge of architecture health. If it’s difficult to write a test, don’t blame the test framework; blame the architecture. He’s seen the common “test ice cream cone” problem: an inverted pyramid with too many slow, flaky end-to-end tests and too few unit tests. Sam recounts the frustration of 200 lines of setup code and mocks just to test a simple user model.
How Clean Architecture enables the Test Pyramid:
Clean architecture brings the “dependency rule” to the forefront: code in any given layer only has dependencies pointing inward.
- Domain Layer: Having no dependencies, testing a user model becomes a simple four-line test: build the model, change state, assert the change. No extensive setup or mocks needed!
- Application Layer: By coding against interfaces (like the repository pattern), the application layer doesn’t know about concrete implementations (e.g., SQL Alchemy). Tests can easily mock these interfaces or use in-memory implementations, making them much quicker without needing to boot up a database.
This approach makes the most important parts of your codebase highly testable, enabling a true test pyramid with a large base of fast unit tests. While integration and end-to-end tests are still necessary for core features, their population is vastly reduced, perhaps from 200 to 10, making them more manageable despite their inherent brittleness and expense.
When to Abstract: The Pragmatic Approach to Complexity ⚖️
Max brought up the common challenge of integrating powerful tools like Superbase, which offer easy clients for everything from auth to vector databases. He found himself implementing the Superbase client everywhere, recognizing the coupling risk and the need for abstraction for testability and longevity.
Sam’s advice is pragmatic: bringing in clean architecture adds layers, which is a form of complexity. You must apply it thoughtfully. The key question is always: “What problem are you solving?” It’s about risk. Is the coupling risk of directly using a framework like Superbase significant enough to justify investing development capacity in an abstraction layer? If your current setup (e.g., Django) works well and your company is “crushing it,” there’s no problem to solve, and no immediate reason to pull in clean architecture. It’s all about aligning the discovered risk with other company priorities.
Clean Architecture in the Age of AI 🤖
The timing of Sam’s book was fascinating; its content was mostly locked in January 2024, just before the explosion of reasoning models and agentic coding assistants. While the book doesn’t mention AI, Sam believes clean architecture works exceptionally well with AI-friendly codebases.
- Addressing “Context Rot”: AI agents, even with million-token context windows, struggle to effectively and consistently leverage huge contexts. Clean architecture’s layered approach allows you to scope problems by layer, focusing the AI on specific tasks like domain objects, which reduces context and makes the AI more effective.
- A Guiding Foundation: Clean architecture provides a rulebook and plan for building applications. This foundation helps build effective system prompts for guiding AI in architectural decisions.
- Symbiosis: Sam sees AI as a capable planning partner in addition to a coding assistant. Humans, as domain experts, can guide AI to build thoughtful architectural plans. AI can then handle the boilerplate – implementing interfaces for persistence, for example – freeing humans to focus on the core domain objects and interfaces that truly define the business. This approach helps both humans and AIs build robust, scalable applications.
The Ultimate Takeaway: Domain Over Details 🎯
Max asked for the single most important takeaway from the book. Sam’s powerful summary:
The true value of a software application lies in the understanding and codification of its domain. This means prioritizing those crucial conversations with business partners to ensure the domain is clear, concise, and isolated. Frameworks like Flask, Django, SQL Alchemy, or Superbase? “They’re all just details.” They will change. The real, enduring value is in what a customer means to you, what a product means to you, and how the software manages that state. Max echoed this sentiment, noting that in the data world, tools constantly change, and having those architectural layers to separate concerns is critical.
Thank you for joining us for this insightful discussion with Sam Keen! His book, Clean Architecture in Python, offers invaluable guidance for any developer looking to build more robust, maintainable, and adaptable software.
Want to dive deeper? Head over to gotopia.tech to discover more high-quality dev talks and content from the brightest minds in software development!