# jujumilk3/fastapi-clean-architecture architecture

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

- Interactive diagram: https://gitdiagram.com/jujumilk3/fastapi-clean-architecture
- Repository: https://github.com/jujumilk3/fastapi-clean-architecture

## Overview

##### Project Type and Purpose
- This is a backend RESTful API service built with FastAPI following a clean‐architecture approach.
- It exposes two API versions (v1, v2) for resources: user, auth, post, tag.
- It uses SQLAlchemy models, Alembic for migrations, dependency‐injector for DI, JWT for authentication, and runs on Uvicorn in containerized environments.

##### High‐Level Architectural Layers
- **API Layer (Interface / Delivery)**
- app/main.py – Uvicorn entry point
- app/api/v1/routes.py & endpoints/… – version 1 REST routes
- app/api/v2/routes.py & endpoints/… – version 2 REST routes
- Responsibilities: HTTP request/response, versioning, dependency wiring.
- **Core / Infrastructure**
- app/core/config.py – environment config
- app/core/container.py – DI container (service & repo providers)
- app/core/database.py – SQLAlchemy engine & session
- app/core/middleware.py – request/response middleware
- app/core/security.py – JWT utilities, role enforcement
- Alembic (alembic.ini, migrations/) – database migrations
- **Domain / Business Logic**
- app/services/*.py – business rules per entity (UserService, PostService, etc.)
- app/repository/*.py – data access layer (SQLAlchemy-based repositories)
- Interaction: Services invoke repositories; repositories execute DB queries.
- **Data Models and Schemas**
- app/model/*.py – SQLAlchemy ORM definitions (User, Post, Tag, PostTag)
- app/schema/*.py – Pydantic schemas for request/response validation
- **Utilities**
- app/util/*.py – helpers for hashing, date, object conversion, query building.
- **Testing**
- tests/unit_tests – isolated component tests (container, fixtures)
- tests/integration_tests – end‐to‐end API tests against real DB
- tests/test_data – sample JSON payloads.

##### Components and Interactions
- Client (e.g., browser, mobile app, CLI) issues HTTP requests →
- Uvicorn/app.main → FastAPI router picks correct versioned route →
- Route handler pulls dependencies from DI container →
- Controller calls Service layer →
- Service applies business logic, calls Repository →
- Repository uses SQLAlchemy session to query or persist to Database →
- DB (MySQL or PostgreSQL) returns results →
- Service returns domain objects →
- Route uses Pydantic schema to serialize response →
- Client receives JSON.
- Alembic migrations manage DB schema outside runtime.

##### Architectural Patterns and Principles
- Clean Architecture (separation of concerns: interface, application, domain, infrastructure)
- Service‐Repository pattern (services for business logic; repositories for persistence)
- Dependency Injection (via dependency‐injector container)
- Versioned API routing (v1, v2 separation)
- JWT authentication & role-based access control as cross‐cutting concerns via middleware

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Actor
    Client["Client"]:::external

    %% API Entry
    main["app/main.py\n(Uvicorn)"]:::interface
    click main "https://github.com/jujumilk3/fastapi-clean-architecture/blob/main/app/main.py"

    Client -->|"HTTP Request"| main

    %% API Layer
    subgraph "API Layer"
        v1router["v1 Routes"]:::interface
        click v1router "https://github.com/jujumilk3/fastapi-clean-architecture/blob/main/app/api/v1/routes.py"
        auth1["Auth Endpoint v1"]:::interface
        click auth1 "https://github.com/jujumilk3/fastapi-clean-architecture/blob/main/app/api/v1/endpoints/auth.py"
        user1["User Endpoint v1"]:::interface
        click user1 "https://github.com/jujumilk3/fastapi-clean-architecture/blob/main/app/api/v1/endpoints/user.py"
        post1["Post Endpoint v1"]:::interface
        click post1 "https://github.com/jujumilk3/fastapi-clean-architecture/blob/main/app/api/v1/endpoints/post.py"
        tag1["Tag Endpoint v1"]:::interface
        click tag1 "https://github.com/jujumilk3/fastapi-clean-architecture/blob/main/app/api/v1/endpoints/tag.py"

        v2router["v2 Routes"]:::interface
        click v2router "https://github.com/jujumilk3/fastapi-clean-architecture/blob/main/app/api/v2/routes.py"
        auth2["Auth Endpoint v2"]:::interface
        click auth2 "https://github.com/jujumilk3/fastapi-clean-architecture/blob/main/app/api/v2/endpoints/auth.py"
    end

    main -->|"routes include"| v1router
    main -->|"routes include"| v2router
    v1router --> auth1
    v1router --> user1
    v1router --> post1
    v1router --> tag1
    v2router --> auth2

    %% Core / Infrastructure
    subgraph "Core / Infrastructure"
        config["Config"]:::core
        click config "https://github.com/jujumilk3/fastapi-clean-architecture/blob/main/app/core/config.py"
        deps["Dependencies"]:::core
        click deps "https://github.com/jujumilk3/fastapi-clean-architecture/blob/main/app/core/dependencies.py"
        dbcore["Database Engine & Session"]:::core
        click dbcore "https://github.com/jujumilk3/fastapi-clean-architecture/blob/main/app/core/database.py"
        middleware["Middleware"]:::core
        click middleware "https://github.com/jujumilk3/fastapi-clean-architecture/blob/main/app/core/middleware.py"
        security["Security (JWT Utilities)"]:::core
        click security "https://github.com/jujumilk3/fastapi-clean-architecture/blob/main/app/core/security.py"
        exceptions["Exceptions"]:::core
        click exceptions "https://github.com/jujumilk3/fastapi-clean-architecture/blob/main/app/core/exceptions.py"
        container["DI Container"]:::core
        click container "https://github.com/jujumilk3/fastapi-clean-architecture/blob/main/app/core/container.py"
    end

    %% Dependency Wiring
    auth1 -->|"inject dependencies"| container
    user1 --> container
    post1 --> container
    tag1 --> container
    auth2 --> container

    container --> config
    container --> deps
    container --> dbcore
    container --> security

    %% Services Layer
    subgraph "Services"
        baseService["Base Service"]:::service
        click baseService "https://github.com/jujumilk3/fastapi-clean-architecture/blob/main/app/services/base_service.py"
        authService["Auth Service"]:::service
        click authService "https://github.com/jujumilk3/fastapi-clean-architecture/blob/main/app/services/auth_service.py"
        userService["User Service"]:::service
        click userService "https://github.com/jujumilk3/fastapi-clean-architecture/blob/main/app/services/user_service.py"
        postService["Post Service"]:::service
        click postService "https://github.com/jujumilk3/fastapi-clean-architecture/blob/main/app/services/post_service.py"
        tagService["Tag Service"]:::service
        click tagService "https://github.com/jujumilk3/fastapi-clean-architecture/blob/main/app/services/tag_service.py"
    end

    container --> baseService
    container --> authService
    container --> userService
    container --> postService
    container --> tagService

    auth1 -->|"call"| authService
    auth2 -->|"call"| authService
    user1 -->|"call"| userService
    post1 -->|"call"| postService
    tag1 -->|"call"| tagService

    %% Repositories Layer
    subgraph "Repositories"
        baseRepo["Base Repository"]:::repo
        click baseRepo "https://github.com/jujumilk3/fastapi-clean-architecture/blob/main/app/repository/base_repository.py"
        userRepo["User Repository"]:::repo
        click userRepo "https://github.com/jujumilk3/fastapi-clean-architecture/blob/main/app/repository/user_repository.py"
        postRepo["Post Repository"]:::repo
        click postRepo "https://github.com/jujumilk3/fastapi-clean-architecture/blob/main/app/repository/post_repository.py"
        tagRepo["Tag Repository"]:::repo
        click tagRepo "https://github.com/jujumilk3/fastapi-clean-architecture/blob/main/app/repository/tag_repository.py"
    end

    baseService -->|"uses"| baseRepo
    authService --> baseRepo
    authService --> userRepo
    userService --> userRepo
    postService --> postRepo
    tagService --> tagRepo

    baseRepo --> dbcore
    userRepo --> dbcore
    postRepo --> dbcore
    tagRepo --> dbcore

    %% Data Models & Schemas
    subgraph "Data Models & Schemas"
        baseModel["Base Model"]:::model
        click baseModel "https://github.com/jujumilk3/fastapi-clean-architecture/blob/main/app/model/base_model.py"
        userModel["User Model"]:::model
        click userModel "https://github.com/jujumilk3/fastapi-clean-architecture/blob/main/app/model/user.py"
        postModel["Post Model"]:::model
        click postModel "https://github.com/jujumilk3/fastapi-clean-architecture/blob/main/app/model/post.py"
        tagModel["Tag Model"]:::model
        click tagModel "https://github.com/jujumilk3/fastapi-clean-architecture/blob/main/app/model/tag.py"
        postTagModel["PostTag Model"]:::model
        click postTagModel "https://github.com/jujumilk3/fastapi-clean-architecture/blob/main/app/model/post_tag.py"
        authSchema["Auth Schema"]:::model
        click authSchema "https://github.com/jujumilk3/fastapi-clean-architecture/blob/main/app/schema/auth_schema.py"
        baseSchema["Base Schema"]:::model
        click baseSchema "https://github.com/jujumilk3/fastapi-clean-architecture/blob/main/app/schema/base_schema.py"
        postTagSchema["PostTag Schema"]:::model
        click postTagSchema "https://github.com/jujumilk3/fastapi-clean-architecture/blob/main/app/schema/post_tag_schema.py"
        userSchema["User Schema"]:::model
        click userSchema "https://github.com/jujumilk3/fastapi-clean-architecture/blob/main/app/schema/user_schema.py"
    end

    userRepo --> userModel
    postRepo --> postModel
    tagRepo --> tagModel
    baseRepo --> baseModel
    postRepo --> postTagModel

    auth1 --> authSchema
    user1 --> userSchema
    post1 --> postTagSchema

    %% Utilities
    subgraph "Utilities"
        utilClass["Class/Object Helpers"]:::util
        click utilClass "https://github.com/jujumilk3/fastapi-clean-architecture/blob/main/app/util/class_object.py"
        utilDate["Date Helpers"]:::util
        click utilDate "https://github.com/jujumilk3/fastapi-clean-architecture/blob/main/app/util/date.py"
        utilHash["Hashing Helpers"]:::util
        click utilHash "https://github.com/jujumilk3/fastapi-clean-architecture/blob/main/app/util/hash.py"
        utilQuery["Query Builder"]:::util
        click utilQuery "https://github.com/jujumilk3/fastapi-clean-architecture/blob/main/app/util/query_builder.py"
        utilSchema["Schema Conversion"]:::util
        click utilSchema "https://github.com/jujumilk3/fastapi-clean-architecture/blob/main/app/util/schema.py"
    end

    authService --> utilHash
    postService --> utilDate
    userService --> utilSchema
    postRepo --> utilQuery

    %% Database and Migrations
    db["Database\n(MySQL/PostgreSQL)"]:::database
    migrations["Alembic Migrations"]:::migrations
    click migrations "https://github.com/jujumilk3/fastapi-clean-architecture/blob/main/alembic.ini"
    migdir["migrations/"]:::migrations
    click migdir "https://github.com/jujumilk3/fastapi-clean-architecture/tree/main/migrations/"

    dbcore --> db
    migrations --> db

    %% Return flow to client
    db -->|"query result"| baseRepo
    baseRepo -->|"domain objects"| baseService
    baseService -->|"response data"| auth1
    auth1 -->|"JSON Response"| Client

    %% Styles
    classDef interface fill:#D6E9FF,stroke:#333,stroke-width:1px
    classDef core fill:#FFF3CA,stroke:#333,stroke-width:1px
    classDef service fill:#D4F4DD,stroke:#333,stroke-width:1px
    classDef repo fill:#FFE4B2,stroke:#333,stroke-width:1px
    classDef model fill:#EDEDED,stroke:#333,stroke-width:1px
    classDef util fill:#F0F0F0,stroke:#333,stroke-width:1px
    classDef database fill:#CFFFE5,stroke:#333,stroke-width:1px
    classDef migrations fill:#FFEBE8,stroke:#333,stroke-width:1px
    classDef external fill:#FFEFDB,stroke:#333,stroke-width:1px
```
