# 0xtheprodev/fastapi-clean-example architecture

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

- Interactive diagram: https://gitdiagram.com/0xtheprodev/fastapi-clean-example
- Repository: https://github.com/0xtheprodev/fastapi-clean-example

## Overview

##### Main Components
- Main Entry Point: The main.py file is the entry point that wires up the FastAPI application.
- Routers: Located under the “routers” directory (with versioning under routers/v1), these modules define the REST endpoints for Authors and Books.
- GraphQL Schemas: Inside the “schemas/graphql” directory, these files define the GraphQL types, queries, and mutations.
- Business Logic (Services): The “services” directory encapsulates the core business logic for Authors and Books.
- Data Access (Repositories): The “repositories” directory implements the Repository Pattern. It abstracts data handling and storage mechanics for the different entities.
- Domain Models: Found in the “models” directory, these files outline the database or domain representation (including relationships like BookAuthorAssociation).
- Configurations: The “configs” directory holds setup information for Database connections, GraphQL configuration, and environment settings.
- Metadata & Schemas (Validation): The “metadata” and “schemas/pydantic” directories provide extra context and request/response validation using Pydantic.
- Testing: While not a runtime part of the architecture, the __tests__ directory shows where unit tests for services and repositories reside.

##### Relationships and Interactions
- The FastAPI entry (main.py) initializes the application and loads configurations.
- Routers (REST endpoints) route incoming HTTP requests to their corresponding service methods.
- Services implement the business logic; they are invoked by the routers and, in turn, call the repositories for data persistence or retrieval.
- Repositories abstract the underlying data access layer and interact with the models which represent the database schema.
- GraphQL endpoints similarly leverage GraphQL schemas which connect to business logic, potentially reusing the same service or repository classes used for REST.
- Configurations are referenced throughout to provide environmental settings (such as database connections), while metadata supplements the domain logic.

##### Architectural Patterns and Design Principles
- Hexagonal (Clean) Architecture: The system is designed to separate the core business logic (services and models) from external concerns (routers, GraphQL interface, database configurations).
- Repository Pattern: To abstract data access and provide a consistent interface for interacting with domain models.
- Separation of Concerns: Each layer (routers, services, repositories, configurations) is decoupled, making the system easier to test and maintain.
- Use of Pydantic: For schema validation and type checking, found in the “schemas/pydantic” portion.

##### Technologies, Framework, and Libraries
- FastAPI: The underlying framework that provides asynchronous web handling and OpenAPI integration.
- Uvicorn: The ASGI server used to run the application.
- GraphQL: Enabled via dedicated schemas for flexible API interactions.
- Pydantic: For data validation within request/response schemas.
- Pipenv: Used for dependency management.
- Python 3 and standard testing frameworks (unittest, pytest) for test automation.

- Start at the top with the “Client” (representing API consumers that access REST endpoints or GraphQL).
- Next, from “Services,” branch out to “Repositories” which then connect to “Domain Models.”
- On the side, place “Configs” that supply necessary settings (database, environment, GraphQL config) to appropriate components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers
    A["Client"]:::client
    B["FastAPI App"]:::api
    A --> B

    %% API Layer (Endpoints)
    subgraph "API Layer (Endpoints)"
        subgraph "REST Endpoints"
            C["AuthorRouter"]:::api
            D["BookRouter"]:::api
        end
        subgraph "GraphQL Endpoints"
            E["GraphQL Author"]:::api
            F["GraphQL Book"]:::api
            G["Mutation"]:::api
            H["Query"]:::api
        end
    end
    B --> C
    B --> D
    B --> E
    B --> F
    B --> G
    B --> H

    %% Business Logic (Services)
    subgraph "Business Logic (Services)"
        I["AuthorService"]:::service
        J["BookService"]:::service
    end
    C --> I
    E --> I
    G --> I
    H --> I
    D --> J
    F --> J
    G --> J
    H --> J

    %% Data Access (Repositories)
    subgraph "Data Access (Repositories)"
        K["AuthorRepository"]:::repository
        L["BookRepository"]:::repository
    end
    I --> K
    J --> L

    %% Domain Models
    subgraph "Domain Models"
        M["AuthorModel"]:::domain
        N["BookModel"]:::domain
        O["BookAuthorAssociation"]:::domain
        P["BaseModel"]:::domain
    end
    K --> M
    L --> N
    K --> O
    L --> O
    M --> P
    N --> P

    %% Configurations
    subgraph "Configurations"
        Q["Database Config"]:::config
        R["Environment Config"]:::config
        S["GraphQL Config"]:::config
    end
    R --- B
    Q --- K
    S --- E

    %% Validation & Metadata
    subgraph "Validation & Metadata"
        T["Metadata (Tags)"]:::metadata
        U["Author Pydantic Schema"]:::metadata
        V["Book Pydantic Schema"]:::metadata
    end
    T --- I
    T --- J
    U --- I
    V --- J

    %% Testing
    subgraph "Testing"
        W["Repository Tests"]:::testing
        X["Service Tests"]:::testing
    end
    W --- K
    W --- L
    X --- I
    X --- J

    %% Classes for styling
    classDef client fill:#C3E88D,stroke:#333,stroke-width:2px;
    classDef api fill:#82AAFF,stroke:#333,stroke-width:2px;
    classDef service fill:#C792EA,stroke:#333,stroke-width:2px;
    classDef repository fill:#FFCB6B,stroke:#333,stroke-width:2px;
    classDef domain fill:#89DDFF,stroke:#333,stroke-width:2px;
    classDef config fill:#F78C6C,stroke:#333,stroke-width:2px;
    classDef metadata fill:#FF5370,stroke:#333,stroke-width:2px;
    classDef testing fill:#C3E88D,stroke:#333,stroke-width:2px;

    %% Click Events
    click B "https://github.com/0xtheprodev/fastapi-clean-example/blob/main/main.py"
    click C "https://github.com/0xtheprodev/fastapi-clean-example/blob/main/routers/v1/AuthorRouter.py"
    click D "https://github.com/0xtheprodev/fastapi-clean-example/blob/main/routers/v1/BookRouter.py"
    click E "https://github.com/0xtheprodev/fastapi-clean-example/blob/main/schemas/graphql/Author.py"
    click F "https://github.com/0xtheprodev/fastapi-clean-example/blob/main/schemas/graphql/Book.py"
    click G "https://github.com/0xtheprodev/fastapi-clean-example/blob/main/schemas/graphql/Mutation.py"
    click H "https://github.com/0xtheprodev/fastapi-clean-example/blob/main/schemas/graphql/Query.py"
    click I "https://github.com/0xtheprodev/fastapi-clean-example/blob/main/services/AuthorService.py"
    click J "https://github.com/0xtheprodev/fastapi-clean-example/blob/main/services/BookService.py"
    click K "https://github.com/0xtheprodev/fastapi-clean-example/blob/main/repositories/AuthorRepository.py"
    click L "https://github.com/0xtheprodev/fastapi-clean-example/blob/main/repositories/BookRepository.py"
    click M "https://github.com/0xtheprodev/fastapi-clean-example/blob/main/models/AuthorModel.py"
    click N "https://github.com/0xtheprodev/fastapi-clean-example/blob/main/models/BookModel.py"
    click O "https://github.com/0xtheprodev/fastapi-clean-example/blob/main/models/BookAuthorAssociation.py"
    click P "https://github.com/0xtheprodev/fastapi-clean-example/blob/main/models/BaseModel.py"
    click Q "https://github.com/0xtheprodev/fastapi-clean-example/blob/main/configs/Database.py"
    click R "https://github.com/0xtheprodev/fastapi-clean-example/blob/main/configs/Environment.py"
    click S "https://github.com/0xtheprodev/fastapi-clean-example/blob/main/configs/GraphQL.py"
    click T "https://github.com/0xtheprodev/fastapi-clean-example/blob/main/metadata/Tags.py"
    click U "https://github.com/0xtheprodev/fastapi-clean-example/blob/main/schemas/pydantic/AuthorSchema.py"
    click V "https://github.com/0xtheprodev/fastapi-clean-example/blob/main/schemas/pydantic/BookSchema.py"
    click W "https://github.com/0xtheprodev/fastapi-clean-example/tree/main/__tests__/repositories/"
    click X "https://github.com/0xtheprodev/fastapi-clean-example/tree/main/__tests__/services/"
```
