# packtpublishing/clean-architecture-with-python architecture

> Architecture diagram of the GitHub repository packtpublishing/clean-architecture-with-python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/packtpublishing/clean-architecture-with-python
- Repository: https://github.com/packtpublishing/clean-architecture-with-python

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frameworks & Drivers Layer (Outer)
    subgraph "Frameworks & Drivers Layer"
        direction TB
        CLI_Main["cli_main.py"]:::frameworks
        ClickApp["click_cli_app.py"]:::frameworks
        FlaskApp["app.py"]:::frameworks
        Routes["routes.py"]:::frameworks
        Templates["templates"]:::frameworks
        FileRepo["file.py"]:::frameworks
        MemoryRepo["memory.py"]:::frameworks
        SendGrid["sendgrid.py"]:::frameworks
        Recorder["recorder.py"]:::frameworks
        Factory["factory.py"]:::frameworks
        DIContainer["container.py"]:::frameworks
        AppConfig["config.py"]:::frameworks
        LogConfig["config.py"]:::frameworks
        Tracing["trace.py"]:::frameworks
    end

    %% Interface Adapters Layer
    subgraph "Interface Adapters Layer"
        direction TB
        Controllers["controllers"]:::adapters
        Presenters["presenters"]:::adapters
        ViewModels["view_models"]:::adapters
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        DTOs["dtos"]:::application
        UseCases["use_cases"]:::application
        NotificationPorts["notifications.py"]:::application
        TaskRepoPort["task_repository.py"]:::application
        ProjectRepoPort["project_repository.py"]:::application
    end

    %% Domain Layer
    subgraph "Domain Layer"
        direction TB
        DomainPkg["domain"]:::domain
        Entities["entities"]:::domain
        Services["task_priority_calculator.py"]:::domain
        ValueObjects["value_objects.py"]:::domain
        Exceptions["exceptions.py"]:::domain
    end

    %% Dependencies and Data Flow
    CLI_Main --> ClickApp
    ClickApp --> Controllers
    FlaskApp --> Controllers
    Routes --> Controllers
    Controllers -->|invokes| UseCases
    UseCases -->|uses| Entities
    UseCases -->|uses| Services
    UseCases -->|uses| ValueObjects
    UseCases -->|raises| Exceptions
    UseCases -->|calls| TaskRepoPort
    UseCases -->|calls| ProjectRepoPort
    UseCases -->|sends via| NotificationPorts
    UseCases -->|returns| DTOs
    UseCases -->|outputs to| Presenters
    Presenters --> ViewModels
    ViewModels --> Templates

    %% DI wiring
    DIContainer --> ClickApp
    DIContainer --> FlaskApp
    DIContainer --> UseCases
    DIContainer --> TaskRepoPort
    DIContainer --> ProjectRepoPort
    DIContainer --> NotificationPorts

    %% Port implementations (dashed)
    TaskRepoPort -.-> FileRepo
    TaskRepoPort -.-> MemoryRepo
    ProjectRepoPort -.-> FileRepo
    ProjectRepoPort -.-> MemoryRepo
    NotificationPorts -.-> SendGrid
    NotificationPorts -.-> Recorder
    NotificationPorts -.-> Factory

    %% Click Events
    click DomainPkg "https://github.com/packtpublishing/clean-architecture-with-python/tree/main/Chapter_10/TodoApp/todo_app/domain"
    click Entities "https://github.com/packtpublishing/clean-architecture-with-python/tree/main/Chapter_10/TodoApp/todo_app/domain/entities"
    click Services "https://github.com/packtpublishing/clean-architecture-with-python/blob/main/Chapter_10/TodoApp/todo_app/domain/services/task_priority_calculator.py"
    click ValueObjects "https://github.com/packtpublishing/clean-architecture-with-python/blob/main/Chapter_10/TodoApp/todo_app/domain/value_objects.py"
    click Exceptions "https://github.com/packtpublishing/clean-architecture-with-python/blob/main/Chapter_10/TodoApp/todo_app/domain/exceptions.py"
    click DTOs "https://github.com/packtpublishing/clean-architecture-with-python/tree/main/Chapter_10/TodoApp/todo_app/application/dtos"
    click UseCases "https://github.com/packtpublishing/clean-architecture-with-python/tree/main/Chapter_10/TodoApp/todo_app/application/use_cases"
    click NotificationPorts "https://github.com/packtpublishing/clean-architecture-with-python/blob/main/Chapter_10/TodoApp/todo_app/application/service_ports/notifications.py"
    click TaskRepoPort "https://github.com/packtpublishing/clean-architecture-with-python/blob/main/Chapter_10/TodoApp/todo_app/application/repositories/task_repository.py"
    click ProjectRepoPort "https://github.com/packtpublishing/clean-architecture-with-python/blob/main/Chapter_10/TodoApp/todo_app/application/repositories/project_repository.py"
    click Controllers "https://github.com/packtpublishing/clean-architecture-with-python/tree/main/Chapter_10/TodoApp/todo_app/interfaces/controllers"
    click Presenters "https://github.com/packtpublishing/clean-architecture-with-python/tree/main/Chapter_10/TodoApp/todo_app/interfaces/presenters"
    click ViewModels "https://github.com/packtpublishing/clean-architecture-with-python/tree/main/Chapter_10/TodoApp/todo_app/interfaces/view_models"
    click CLI_Main "https://github.com/packtpublishing/clean-architecture-with-python/blob/main/Chapter_10/TodoApp/cli_main.py"
    click ClickApp "https://github.com/packtpublishing/clean-architecture-with-python/blob/main/Chapter_10/TodoApp/todo_app/infrastructure/cli/click_cli_app.py"
    click FlaskApp "https://github.com/packtpublishing/clean-architecture-with-python/blob/main/Chapter_10/TodoApp/todo_app/infrastructure/web/app.py"
    click Routes "https://github.com/packtpublishing/clean-architecture-with-python/blob/main/Chapter_10/TodoApp/todo_app/infrastructure/web/routes.py"
    click Templates "https://github.com/packtpublishing/clean-architecture-with-python/tree/main/Chapter_10/TodoApp/todo_app/infrastructure/web/templates"
    click FileRepo "https://github.com/packtpublishing/clean-architecture-with-python/blob/main/Chapter_10/TodoApp/todo_app/infrastructure/persistence/file.py"
    click MemoryRepo "https://github.com/packtpublishing/clean-architecture-with-python/blob/main/Chapter_10/TodoApp/todo_app/infrastructure/persistence/memory.py"
    click SendGrid "https://github.com/packtpublishing/clean-architecture-with-python/blob/main/Chapter_10/TodoApp/todo_app/infrastructure/notifications/sendgrid.py"
    click Recorder "https://github.com/packtpublishing/clean-architecture-with-python/blob/main/Chapter_10/TodoApp/todo_app/infrastructure/notifications/recorder.py"
    click Factory "https://github.com/packtpublishing/clean-architecture-with-python/blob/main/Chapter_10/TodoApp/todo_app/infrastructure/notifications/factory.py"
    click DIContainer "https://github.com/packtpublishing/clean-architecture-with-python/blob/main/Chapter_10/TodoApp/todo_app/infrastructure/configuration/container.py"
    click AppConfig "https://github.com/packtpublishing/clean-architecture-with-python/blob/main/Chapter_10/TodoApp/todo_app/infrastructure/config.py"
    click LogConfig "https://github.com/packtpublishing/clean-architecture-with-python/blob/main/Chapter_10/TodoApp/todo_app/infrastructure/logging/config.py"
    click Tracing "https://github.com/packtpublishing/clean-architecture-with-python/blob/main/Chapter_10/TodoApp/todo_app/infrastructure/logging/trace.py"

    %% Style Definitions
    classDef domain fill:#D6EAF8,stroke:#1B4F72,stroke-width:1px;
    classDef application fill:#D5F5E3,stroke:#196F3D,stroke-width:1px;
    classDef adapters fill:#FCF3CF,stroke:#7D6608,stroke-width:1px;
    classDef frameworks fill:#FADBD8,stroke:#9A1F1F,stroke-width:1px;
```
