# cdddg/py-clean-arch architecture

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

- Interactive diagram: https://gitdiagram.com/cdddg/py-clean-arch
- Repository: https://github.com/cdddg/py-clean-arch

## Overview

##### Project type and purpose
- This is a backend service – a Pokémon API server – implemented in Python using FastAPI.
- It follows Uncle Bob’s Clean Architecture to expose two interfaces (REST and GraphQL) and supports multiple database backends (relational, document, key‐value).

##### High-level architectural layers
- Frameworks & Drivers (outermost)
– HTTP / REST controllers (src/entrypoints/http)
– GraphQL adapters (src/entrypoints/graphql)
– Database drivers & clients (SQLAlchemy async, Motor/CouchDB ODM, Redis client)
- Interface Adapters
– Repository implementations (src/repositories/relational_db, document_db, key_value_db)
– Mappers & ODM/ORM models
- Use Cases (application business rules)
– src/usecases/pokemon.py
- Entities (core domain)
– src/models/pokemon.py, exception definitions
- Cross-cutting/Infrastructure
– Dependency Injection & Unit of Work (src/di)
– Configuration (src/settings/db/*)
– Common utilities (src/common)

##### Main components
a. API Layer
- HTTP REST Router & Controllers
- GraphQL Schema, Queries, Mutations, Extensions
b. DI & UoW Layer
- DI Container (dependency_injection.py)
- UnitOfWork orchestrator (unit_of_work.py)
c. Use-Case Layer
- Pokémon use-cases (e.g., get, create, update operations)
d. Domain Layer
- Pokémon Entity
- Exceptions
e. Repository Abstractions
- IPokemonRepository interface
f. Repository Adapters
- RelationalDB Repository (ORM + SQLAlchemy async)
- DocumentDB Repository (ODM + MongoDB)
- KeyValueDB Repository (Redis/Memcached)
g. External Databases
- SQLite (in-memory / file)
- MySQL, PostgreSQL
- MongoDB
- Redis
h. Configuration & Scripts
- DB initialization scripts (docker-compose, scripts folder)
- Environment‐based DB URIs

##### Relationships & data flow
1. Client → HTTP or GraphQL endpoint
2. Endpoint → DI container wires in required Use Case & UnitOfWork
3. Use Case invokes repository interface methods
4. UnitOfWork manages transactional lifecycle across repository calls
5. Concrete repository adapter commits to the chosen database via async drivers
6. Response flows back through same layers to client

##### Architectural patterns & design principles
- Clean Architecture layering (Dependency Rule: outer layers depend on inner layers only)
- Dependency Injection to invert control and decouple modules
- Repository Pattern abstracts data access
- Unit Of Work Pattern groups multiple operations into a single transactional boundary
- Async I/O for scalable database access (SQLAlchemy Async, Motor, aioredis)

##### Relevant technologies & frameworks
- FastAPI (HTTP + OpenAPI)
- Strawberry or Graphene (GraphQL)
- SQLAlchemy 2.0 Async + asyncmy/asyncpg
- Motor / MongoDB ODM
- aioredis / Key-Value store libraries
- Docker & docker-compose for multi-DB orchestration
- Poetry for dependency management

## Diagram (Mermaid)

```mermaid
flowchart TB
    Client["Client"]:::external

    subgraph "API Layer"
        direction TB
        REST_ext["HTTP Extension"]:::api
        click REST_ext "https://github.com/cdddg/py-clean-arch/blob/master/src/entrypoints/http/extension.py"
        REST["HTTP REST Controller"]:::api
        click REST "https://github.com/cdddg/py-clean-arch/tree/master/src/entrypoints/http"
        P_router["Pokemon Router"]:::api
        click P_router "https://github.com/cdddg/py-clean-arch/blob/master/src/entrypoints/http/pokemon/router.py"
        P_schema["HTTP Pokemon Schema"]:::api
        click P_schema "https://github.com/cdddg/py-clean-arch/blob/master/src/entrypoints/http/pokemon/schema.py"
        P_mapper_http["HTTP Pokemon Mapper"]:::api
        click P_mapper_http "https://github.com/cdddg/py-clean-arch/blob/master/src/entrypoints/http/pokemon/mapper.py"

        GraphQL_ext["GraphQL Extension"]:::api
        click GraphQL_ext "https://github.com/cdddg/py-clean-arch/blob/master/src/entrypoints/graphql/extension.py"
        G_router["GraphQL Router"]:::api
        click G_router "https://github.com/cdddg/py-clean-arch/blob/master/src/entrypoints/graphql/pokemon/router.py"
        G_schema["GraphQL Pokemon Schema"]:::api
        click G_schema "https://github.com/cdddg/py-clean-arch/blob/master/src/entrypoints/graphql/pokemon/schema.py"
        G_query["GraphQL Pokemon Query"]:::api
        click G_query "https://github.com/cdddg/py-clean-arch/blob/master/src/entrypoints/graphql/pokemon/query.py"
        G_mutation["GraphQL Pokemon Mutation"]:::api
        click G_mutation "https://github.com/cdddg/py-clean-arch/blob/master/src/entrypoints/graphql/pokemon/mutation.py"
        G_mapper["GraphQL Pokemon Mapper"]:::api
        click G_mapper "https://github.com/cdddg/py-clean-arch/blob/master/src/entrypoints/graphql/pokemon/mapper.py"
    end

    subgraph "DI & UoW"
        direction TB
        DI["DI Container"]:::di
        click DI "https://github.com/cdddg/py-clean-arch/blob/master/src/di/dependency_injection.py"
        UoW["UnitOfWork"]:::di
        click UoW "https://github.com/cdddg/py-clean-arch/blob/master/src/di/unit_of_work.py"
    end

    subgraph "Use Cases & Domain"
        direction TB
        UseCase["PokemonUseCase"]:::usecase
        click UseCase "https://github.com/cdddg/py-clean-arch/blob/master/src/usecases/pokemon.py"
        Entity["Pokemon Entity"]:::domain
        click Entity "https://github.com/cdddg/py-clean-arch/blob/master/src/models/pokemon.py"
        Exc["Domain Exceptions"]:::domain
        click Exc "https://github.com/cdddg/py-clean-arch/blob/master/src/models/exception.py"
    end

    RepoAb["IPokemonRepository"]:::abstraction
    click RepoAb "https://github.com/cdddg/py-clean-arch/blob/master/src/repositories/abstraction/pokemon.py"

    subgraph "Repository Adapters"
        direction TB
        RelORM["Relational ORM Model"]:::adapter
        click RelORM "https://github.com/cdddg/py-clean-arch/blob/master/src/repositories/relational_db/pokemon/orm.py"
        RelRepo["Relational Repository"]:::adapter
        click RelRepo "https://github.com/cdddg/py-clean-arch/blob/master/src/repositories/relational_db/pokemon/repository.py"
        RelMap["Relational Mapper"]:::adapter
        click RelMap "https://github.com/cdddg/py-clean-arch/blob/master/src/repositories/relational_db/pokemon/mapper.py"

        DocODM["Document ODM Model"]:::adapter
        click DocODM "https://github.com/cdddg/py-clean-arch/blob/master/src/repositories/document_db/pokemon/odm.py"
        DocRepo["Document Repository"]:::adapter
        click DocRepo "https://github.com/cdddg/py-clean-arch/blob/master/src/repositories/document_db/pokemon/repository.py"
        DocMap["Document Mapper"]:::adapter
        click DocMap "https://github.com/cdddg/py-clean-arch/blob/master/src/repositories/document_db/pokemon/mapper.py"

        KVModel["KeyValue Model"]:::adapter
        click KVModel "https://github.com/cdddg/py-clean-arch/blob/master/src/repositories/key_value_db/pokemon/okvm.py"
        KVRepo["KeyValue Repository"]:::adapter
        click KVRepo "https://github.com/cdddg/py-clean-arch/blob/master/src/repositories/key_value_db/pokemon/repository.py"
        KVMap["KeyValue Mapper"]:::adapter
        click KVMap "https://github.com/cdddg/py-clean-arch/blob/master/src/repositories/key_value_db/pokemon/mapper.py"
    end

    subgraph "DB Settings & Init"
        direction TB
        BaseCfg["DB Base Config"]:::config
        click BaseCfg "https://github.com/cdddg/py-clean-arch/blob/master/src/settings/db/base.py"
        SQLite["SQLite Config"]:::config
        click SQLite "https://github.com/cdddg/py-clean-arch/blob/master/src/settings/db/sqlite.py"
        MySQL["MySQL Config"]:::config
        click MySQL "https://github.com/cdddg/py-clean-arch/blob/master/src/settings/db/mysql.py"
        Postgres["Postgres Config"]:::config
        click Postgres "https://github.com/cdddg/py-clean-arch/blob/master/src/settings/db/postgres.py"
        MongoCfg["MongoDB Config"]:::config
        click MongoCfg "https://github.com/cdddg/py-clean-arch/blob/master/src/settings/db/mongodb.py"
        RedisCfg["Redis Config"]:::config
        click RedisCfg "https://github.com/cdddg/py-clean-arch/blob/master/src/settings/db/redis.py"
        Compose["docker-compose.yml"]:::external
        click Compose "https://github.com/cdddg/py-clean-arch/blob/master/docker-compose.yml"
        MongoInit["MongoDB Init Script"]:::external
        click MongoInit "https://github.com/cdddg/py-clean-arch/blob/master/scripts/mongodb-init.sh"
        MySQLInit["MySQL Init Script"]:::external
        click MySQLInit "https://github.com/cdddg/py-clean-arch/blob/master/scripts/mysql-init.sql"
        PGInit["Postgres Init Script"]:::external
        click PGInit "https://github.com/cdddg/py-clean-arch/blob/master/scripts/postgres-init.sql"
    end

    %% Connections
    Client --> REST_ext
    Client --> GraphQL_ext
    REST_ext --> P_router
    P_router --> DI
    GraphQL_ext --> G_router
    G_router --> DI
    DI --> UoW
    DI --> UseCase
    UseCase --> RepoAb
    UseCase --> Entity
    UseCase --> Exc
    RepoAb --> RelRepo
    RepoAb --> DocRepo
    RepoAb --> KVRepo
    RelRepo --> RelORM
    DocRepo --> DocODM
    KVRepo --> KVModel
    RelORM --> SQLite
    RelORM --> MySQL
    RelORM --> Postgres
    DocODM --> MongoCfg
    KVModel --> RedisCfg

    classDef api fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef di fill:#FFA500,stroke:#000,stroke-width:1px;
    classDef usecase fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef domain fill:#98FB98,stroke:#000,stroke-width:1px;
    classDef abstraction fill:#EEE8AA,stroke:#000,stroke-width:1px;
    classDef adapter fill:#DDA0DD,stroke:#000,stroke-width:1px;
    classDef config fill:#F5F5F5,stroke:#000,stroke-width:1px;
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px;
```
