# cicerojuniorf/python-clean-arch-showcase architecture

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

- Interactive diagram: https://gitdiagram.com/cicerojuniorf/python-clean-arch-showcase
- Repository: https://github.com/cicerojuniorf/python-clean-arch-showcase

## Overview

##### Overall Project Type and Purpose
- This is a backend API service. Its primary function is to handle customer data and their associated favorite products. It follows best practices by separating concerns into application logic, domain rules (entities and business rules), and infrastructure (persistence, gateway, queries, and security).
- It supports OAuth2-based service-to-service authentication, making it ideally suited as a microservice or standalone backend component.

##### Main Components
- Presentation Layer:
- Represented by the files in src/presentation (e.g., auth_controller.py, customer_controller.py, favorite_product_controller.py).
- This layer handles incoming API calls (e.g., via Swagger endpoints).

- Application Layer:
- Found in src/application, this contains use-case services such as create_customer, update_customer, add_product_to_favorites, and remove_customer actions.
- Also contains error handling logic specific to application flows.

- Domain Layer:
- Includes core business entities (customer, favorite_product) in src/domain/entities and business rules or validations.
- Interfaces for repositories, gateways, and ID generation are defined here (src/domain/interfaces).

- Infrastructure Layer:
- Implements the abstractions defined in the Domain layer.
- Contains implementations for persistence in both MongoDB and in-memory versions (src/infrastructure/repositories, src/infrastructure/queries, src/infrastructure/gateway).
- Also includes the OAuth2 client credentials service in src/infrastructure/security and ID generators.

- Configuration & Dependencies:
- Files like src/config.py, src/dependencies.py, .env, docker-compose.yml, and makefile indicate external configuration, environment management, and container orchestration.

##### Relationships & Data Flow
- API gateway receiving HTTP requests (Authentication, Customer Endpoints), passing them through to the corresponding controllers in the Presentation layer.
- The controllers interact with the Application layer, which then leverages Domain logic and performs business validations.
- Domain logic then calls on Infrastructure components (Repositories, Queries, and Gateway implementations) to persist data or call external services (like the product service or MongoDB) as needed.
- Authentication is handled via an infrastructure-level OAuth2 service that validates client credentials for secured endpoints.

##### Architectural Patterns
- Layered (or hexagonal) architecture: clear separation into presentation, application, domain, and infrastructure layers.
- Use of dependency inversion: Domain interfaces (like repositories or gateways) allow switching between in-memory and MongoDB implementations.
- Security concerns are separated into a dedicated infrastructure security module.

##### Specific Technical Elements
- Mention key libraries or technologies if known (i.e., Python, Docker, docker-compose, MongoDB).
- Interface definitions and how multiple implementations (memory vs. MongoDB) are connected through dependency injection.
- Call out OAuth2 authentication flow details based on the provided fixed credentials.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Client
    Client["Client (Swagger UI)"]:::client

    %% Presentation Layer
    subgraph "Presentation Layer"
        auth["Auth Controller"]:::presentation
        customer["Customer Controller"]:::presentation
        favorite["Favorite Product Controller"]:::presentation
    end

    %% Application Layer
    subgraph "Application Layer"
        ac["Create Customer"]:::application
        au["Update Customer"]:::application
        ar["Remove Customer"]:::application
        aa["Add Product to Favorites"]:::application
        af["Remove Product from Favorites"]:::application
        aerr["Application Errors"]:::application
    end

    %% Domain Layer
    subgraph "Domain Layer"
        dce["Customer Entity"]:::domain
        dfp["Favorite Product Entity"]:::domain
        dgateway["Domain Gateway"]:::domain
        drepos["Domain Repositories"]:::domain
        didgen["Domain ID Generator"]:::domain
        derr["Domain Errors"]:::domain
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        %% Persistence - Repositories
        imcr["MongoDB Customer Repository"]:::infrastructure
        imfpr["MongoDB FavoriteProduct Repository"]:::infrastructure
        imr["Memory Customer Repository"]:::infrastructure
        imfp["Memory FavoriteProduct Repository"]:::infrastructure

        %% Queries
        imcq["MongoDB Customer Query"]:::infrastructure
        imfpq["MongoDB FavoriteProduct Query"]:::infrastructure
        imcqm["Memory Customer Query"]:::infrastructure
        imfpmq["Memory FavoriteProduct Query"]:::infrastructure

        %% Gateway & Security
        ipsg["Product Service Gateway"]:::infrastructure
        ios["OAuth2 Client Service"]:::infrastructure

        %% ID Generators
        imid["MongoDB ID Generator"]:::infrastructure
        iuuid["UUID ID Generator"]:::infrastructure
    end

    %% Configuration & Dependencies
    subgraph "Configuration & Dependencies"
        conf["Configuration (config.py)"]:::config
        env["Environment (.env)"]:::config
        dc["Docker Compose (docker-compose.yml)"]:::config
        dep["Dependencies (dependencies.py)"]:::config
        ep["Entrypoint (main.py)"]:::config
    end

    %% Connections from Client to Presentation Layer
    Client -->|"HTTP_Request"| auth

    %% Connections from Presentation Layer to Application Layer
    customer -->|"calls"| ac
    customer -->|"calls"| au
    customer -->|"calls"| ar
    favorite -->|"calls"| aa
    favorite -->|"calls"| af
    auth -->|"secures"| ios

    %% Bootstrapping via Configuration
    ep -->|"boot"| auth
    dep -->|"inject"| ac

    %% Connections from Application Layer to Domain Layer
    ac -->|"validates"| dce
    ac -->|"saves"| drepos
    au -->|"validates"| dce
    au -->|"updates"| drepos
    ar -->|"validates"| dce
    ar -->|"deletes"| drepos
    aa -->|"associates"| dfp
    aa -->|"calls"| dgateway
    af -->|"dissociates"| dfp
    af -->|"calls"| dgateway
    aerr -->|"maps"| derr

    %% Connections from Domain Layer to Infrastructure Layer
    drepos -->|"mongodb_impl"| imcr
    drepos -->|"memory_impl"| imr
    drepos -->|"query"| imcq
    drepos -->|"query"| imcqm
    drepos -->|"mongodb_impl"| imfpr
    drepos -->|"memory_impl"| imfp
    drepos -->|"query"| imfpq
    drepos -->|"query"| imfpmq

    dgateway -->|"impl"| ipsg
    didgen -->|"impl"| imid
    didgen -->|"impl"| iuuid

    %% Configuration to Infrastructure (sample configuration wiring)
    conf -->|"configure"| imcr

    %% Styling Classes
    class Client client
    class auth,customer,favorite presentation
    class ac,au,ar,aa,af,aerr application
    class dce,dfp,dgateway,drepos,didgen,derr domain
    class imcr,imfpr,imr,imfp,imcq,imfpq,imcqm,imfpmq,ipsg,ios,imid,iuuid infrastructure
    class conf,env,dc,dep,ep config

    %% Click Events - Presentation Layer
    click auth "https://github.com/cicerojuniorf/python-clean-arch-showcase/blob/develop/src/presentation/auth_controller.py"
    click customer "https://github.com/cicerojuniorf/python-clean-arch-showcase/blob/develop/src/presentation/customer_controller.py"
    click favorite "https://github.com/cicerojuniorf/python-clean-arch-showcase/blob/develop/src/presentation/favorite_product_controller.py"

    %% Click Events - Application Layer
    click ac "https://github.com/cicerojuniorf/python-clean-arch-showcase/blob/develop/src/application/create_customer.py"
    click au "https://github.com/cicerojuniorf/python-clean-arch-showcase/blob/develop/src/application/update_customer.py"
    click ar "https://github.com/cicerojuniorf/python-clean-arch-showcase/blob/develop/src/application/remove_customer.py"
    click aa "https://github.com/cicerojuniorf/python-clean-arch-showcase/blob/develop/src/application/add_product_to_favorites.py"
    click af "https://github.com/cicerojuniorf/python-clean-arch-showcase/blob/develop/src/application/remove_product_from_favorites.py"
    click aerr "https://github.com/cicerojuniorf/python-clean-arch-showcase/tree/develop/src/application/errors"

    %% Click Events - Domain Layer
    click dce "https://github.com/cicerojuniorf/python-clean-arch-showcase/blob/develop/src/domain/entities/customer.py"
    click dfp "https://github.com/cicerojuniorf/python-clean-arch-showcase/blob/develop/src/domain/entities/favorite_product.py"
    click dgateway "https://github.com/cicerojuniorf/python-clean-arch-showcase/tree/develop/src/domain/interfaces/gateway"
    click drepos "https://github.com/cicerojuniorf/python-clean-arch-showcase/tree/develop/src/domain/interfaces/repositories"
    click didgen "https://github.com/cicerojuniorf/python-clean-arch-showcase/blob/develop/src/domain/interfaces/id_generator.py"
    click derr "https://github.com/cicerojuniorf/python-clean-arch-showcase/tree/develop/src/domain/errors"

    %% Click Events - Infrastructure Layer
    click imcr "https://github.com/cicerojuniorf/python-clean-arch-showcase/blob/develop/src/infrastructure/repositories/db/mongodb/customer_repository_mongodb.py"
    click imfpr "https://github.com/cicerojuniorf/python-clean-arch-showcase/blob/develop/src/infrastructure/repositories/db/mongodb/favorite_product_repository_mongodb.py"
    click imr "https://github.com/cicerojuniorf/python-clean-arch-showcase/blob/develop/src/infrastructure/repositories/memory/customer_repository_memory.py"
    click imfp "https://github.com/cicerojuniorf/python-clean-arch-showcase/blob/develop/src/infrastructure/repositories/memory/favorite_product_repository_memory.py"
    click imcq "https://github.com/cicerojuniorf/python-clean-arch-showcase/blob/develop/src/infrastructure/queries/mongodb/customer_list_mongodb_query.py"
    click imfpq "https://github.com/cicerojuniorf/python-clean-arch-showcase/blob/develop/src/infrastructure/queries/mongodb/favorite_product_list_mongodb_query.py"
    click imcqm "https://github.com/cicerojuniorf/python-clean-arch-showcase/blob/develop/src/infrastructure/queries/memory/customer_list_memory_query.py"
    click imfpmq "https://github.com/cicerojuniorf/python-clean-arch-showcase/blob/develop/src/infrastructure/queries/memory/favorite_product_list_memory_query.py"
    click ipsg "https://github.com/cicerojuniorf/python-clean-arch-showcase/blob/develop/src/infrastructure/gateway/product_service_memory.py"
    click ios "https://github.com/cicerojuniorf/python-clean-arch-showcase/blob/develop/src/infrastructure/security/oauth2_client_credentials_service.py"
    click imid "https://github.com/cicerojuniorf/python-clean-arch-showcase/blob/develop/src/infrastructure/mongodb_id_generator.py"
    click iuuid "https://github.com/cicerojuniorf/python-clean-arch-showcase/blob/develop/src/infrastructure/uuid_id_generator.py"

    %% Click Events - Configuration & Dependencies
    click conf "https://github.com/cicerojuniorf/python-clean-arch-showcase/blob/develop/src/config.py"
    click env "https://github.com/cicerojuniorf/python-clean-arch-showcase/blob/develop/.env"
    click dc "https://github.com/cicerojuniorf/python-clean-arch-showcase/blob/develop/docker-compose.yml"
    click dep "https://github.com/cicerojuniorf/python-clean-arch-showcase/blob/develop/src/dependencies.py"
    click ep "https://github.com/cicerojuniorf/python-clean-arch-showcase/blob/develop/src/main.py"
```
