How cdddg/py-clean-arch works
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