How packtpublishing/clean-architecture-with-python works
Project type and purpose
• This repository is a multi-chapter codebase for “Clean Architecture with Python.” Each Chapter_X folder shows a progressive state of two exemplar applications (primarily a TodoApp, and in Chapter_11 an EcomApp). These are lightweight full-stack Python sample apps that demonstrate Clean Architecture layers (domain, application, interface adapters, frameworks & drivers).
File structure
• Top-level chapters (Chapter_1…Chapter_12), each containing:
• A README.md with instructions.
• chapter_code_excerpts (non-runnable code snippets).
• A runnable application folder (e.g., Chapter_10/TodoApp, Chapter_11/EcomApp).
• Within each application (e.g., Chapter_10/TodoApp/todo_app):
• domain – core entities, value objects, domain services, exceptions.
• application – DTOs (data transfer objects), use case implementations, repository/service ports.
• interfaces – controllers (input adapters), presenters (output adapters), view models.
• infrastructure – concrete implementations: CLI (Click), Web (Flask + Jinja2), persistence (file, memory, sqlite), notifications (SendGrid), configuration and DI container, logging.
Key insights from README
• The book teaches a layered Clean Architecture in Python:
• Dependency Rule (inner layers know nothing of outer layers).
• SOLID and DDD principles.
• Testability via clear separation of concerns.
• The ultimate goal is to show how the Domain stays pure, Use Cases orchestrate business logic, and adapters/infrastructure sit at the edges.
• Domain Layer
• Entities (Task, Project, Order, Product)
• Value Objects & Domain Services
• Application Layer
• Use Cases (create_task, complete_task, create_order, etc.)
• DTOs & Operation Results
• Service & Repository Ports (interfaces)
• Interface Adapters Layer
• Controllers (CLI controllers, Web controllers)
• Presenters (CLI presenter, Web presenter)
• View Models
• Frameworks & Drivers Layer
• CLI App (Click)
• Web App (Flask + Jinja2 templates)
• Persistence (In-memory, File, SQLite)
• Notifications (SendGrid, in-memory recorder)
• Configuration & Dependency Injection Container
• Logging & Tracing
b. Relationships & interactions
• Controllers receive input (CLI args or HTTP requests) → invoke Use Cases via ports
• Use Cases orchestrate business logic by:
• Calling Domain entities / services
• Interacting with Repository Ports to save/load data
• Emitting notifications via Notification Ports
• Infrastructure layer implements those ports (e.g., FileRepository, SendGridNotifier)
• Presenters transform domain/application results into view models or CLI output
• DI Container wires concrete implementations into controllers and use cases
c. Architectural patterns and principles
• Layered Clean Architecture (inner circles independent of outer)
• Dependency Inversion: application/domain layers define interfaces, infrastructure implements them
• Single Responsibility: each class has one role (entity vs. use case vs. controller vs. adapter)
• Testability: layers can be tested in isolation by mocking ports
d. Technologies & frameworks
• Python 3.13
• Click for CLI
• Flask + Jinja2 for Web UI
• uv or pip for dependency management (pyproject.toml, requirements.txt)
• Pytest for tests
• SendGrid for email notifications
Detailed capture of essential architectural elements
• DI Container in the outermost edge, indicating it wires up controllers → use cases → repository/notifier implementations.
• That both CLI and Web controllers depend on the same application/use case layer, illustrating reusability.
• Notes on tests sitting outside (e.g., a separate “tests” package) to indicate test coverage of each layer.