# hmarcuzzo/fastgear architecture

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

- Interactive diagram: https://gitdiagram.com/hmarcuzzo/fastgear
- Repository: https://github.com/hmarcuzzo/fastgear

## Overview

##### Project type and purpose
- FastGear is an open-source Python library for FastAPI that enhances SQLAlchemy (sync & async) and Redis (async) support, with built-in pagination, error handling, session management, and dynamic query building.
- It is not a standalone application but a reusable toolkit meant to be imported into FastAPI projects.

##### File structure
- Top-level `fastgear/` package subdivided into:
- `applications.py` – entry-point helpers for wiring into FastAPI
- `common/database` – repository abstractions and concrete implementations (SQLAlchemy async/sync, Redis)
- `common/schema` – Pydantic schema bases and exception schemas
- `constants` – shared regex or other constants
- `decorators` – function-level wrappers for sessions, pagination, search
- `handlers` – HTTP exception handler
- `middlewares` – FastAPI middleware for DB session injection
- `types` – custom types, result wrappers, options objects
- `utils` – helper functions for enums, JSON, logging, pagination
- Support files: `pyproject.toml`, CI workflows, linting, test suite under `tests/`.

##### README for insights
- Confirms FastAPI orientation, dependencies on SQLAlchemy 2.0, Pydantic v2, Redis.
- Highlights features: async/sync DB ops, Redis caching, offset pagination, error handling, session context manager.

##### Main components
a. Library core modules:
- Applications module
- Database layer: AbstractRepository, AsyncBaseRepository (SQLAlchemy), SyncBaseRepository, Redis client
- Schema layer: BaseSchema, ExceptionResponseSchema
- Decorators & middleware: DB session decorator, pagination decorators, DB session middleware
- Handlers: HTTP exception handler
- Utilities & types
b. External dependencies:
- FastAPI framework (router & request lifecycle)
- SQL database (PostgreSQL, MySQL, …) via SQLAlchemy 2.0
- Redis instance for cache/other operations
c. Data flow & interactions:
- FastAPI receives request → middleware injects DB session
- Route handlers can use fastgear decorators for session management & pagination
- Handler invokes repository methods (async/sync) → SQLAlchemy session or Redis client
- Exceptions bubble up → fastgear exception handler serializes via Pydantic schemas
- Response serialized by Pydantic schemas and returned
d. Architectural patterns & design principles:
- Repository pattern (abstract + concrete)
- Decorator pattern for augmenting handlers
- Middleware for cross-cutting concerns (session management)
- Schema-first validation (Pydantic)
- Clear separation of concerns: data access, error handling, pagination, application wiring

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% FastAPI Layer
    subgraph "FastAPI App & Request Lifecycle"
        direction TB
        FA[FastAPI App Router]:::framework
        FA -->|"receive request"| DB_MW
    end

    %% Core Layer
    subgraph "FastGear Core"
        direction TB
        APPL[Applications Module]:::core
        DB_MW[DB Session Middleware]:::core
        DB_DEC[DB Session Decorator]:::core
        PAG_DEC1[Simple Pagination Decorator]:::core
        PAG_DEC2[Pagination with Search Decorator]:::core
        EXC_HND[HTTP Exception Handler]:::core

        DB_MW -->|inject session| DB_DEC
        DB_DEC -->|wrap handler| APPL
        APPL -->|apply pagination| PAG_DEC1
        APPL -->|apply search pagination| PAG_DEC2
        APPL -->|handle exceptions| EXC_HND
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        AR[Abstract Repository]:::data
        ASYNC[Async SQLAlchemy Repository]:::data
        SYNC[Sync SQLAlchemy Repository]:::data
        SESS_MGMT[SQLAlchemy Session Management]:::data
        REDIS[Redis Client]:::data

        AR -->|implemented by| ASYNC
        AR -->|implemented by| SYNC
        ASYNC -->|use session| SESS_MGMT
        SYNC -->|use session| SESS_MGMT
    end

    %% Schemas & Types
    subgraph "Schemas & Types"
        direction TB
        BASE_SCHEMA[Base Pydantic Schema]:::schema
        CUSTOM_SCHEMA[Custom Base Model Schema]:::schema
        EXC_SCHEMA[Exception Response Schema]:::schema
        ENUM_UTIL[Enum Helpers]:::utils
        JSON_UTIL[JSON Helpers]:::utils
        LOG_UTIL[Logger Helpers]:::utils
        PAG_UTIL[Pagination Helpers]:::utils
        CONSTS[Shared Constants]:::utils
        TYPES_EXC[Custom Exception Base]:::types
        TYPES_PAG[Pagination Types]:::types
        TYPES_RES[Result Types]:::types

        EXC_HND -->|serialize error| EXC_SCHEMA
        APPL -->|serialize response| BASE_SCHEMA
        APPL -->|model schema| CUSTOM_SCHEMA
        PAG_DEC1 -->|use helpers| PAG_UTIL
        PAG_DEC2 -->|use helpers| PAG_UTIL
        APPL -->|log events| LOG_UTIL
        APPL -->|json output| JSON_UTIL
    end

    %% External Resources
    subgraph "External Dependencies"
        direction TB
        FGDB[(SQL Database)]:::external
        REDIS_SRV[(Redis Instance)]:::external

        SESS_MGMT -->|connect| FGDB
        REDIS -->|connect| REDIS_SRV
        APPL -->|cache ops| REDIS
    end

    %% Click Events
    click APPL "https://github.com/hmarcuzzo/fastgear/blob/main/fastgear/applications.py"
    click AR "https://github.com/hmarcuzzo/fastgear/blob/main/fastgear/common/database/abstract_repository.py"
    click ASYNC "https://github.com/hmarcuzzo/fastgear/blob/main/fastgear/common/database/sqlalchemy/async_base_repository.py"
    click SYNC "https://github.com/hmarcuzzo/fastgear/blob/main/fastgear/common/database/sqlalchemy/sync_base_repository.py"
    click SESS_MGMT "https://github.com/hmarcuzzo/fastgear/blob/main/fastgear/common/database/sqlalchemy/session.py"
    click REDIS "https://github.com/hmarcuzzo/fastgear/blob/main/fastgear/common/database/redis/client.py"
    click BASE_SCHEMA "https://github.com/hmarcuzzo/fastgear/blob/main/fastgear/common/schema/base_schema.py"
    click CUSTOM_SCHEMA "https://github.com/hmarcuzzo/fastgear/blob/main/fastgear/common/schema/custom_base_model_schema.py"
    click EXC_SCHEMA "https://github.com/hmarcuzzo/fastgear/blob/main/fastgear/common/schema/exception_response_schema.py"
    click DB_DEC "https://github.com/hmarcuzzo/fastgear/blob/main/fastgear/decorators/db_session_decorator.py"
    click PAG_DEC1 "https://github.com/hmarcuzzo/fastgear/blob/main/fastgear/decorators/simple_pagination_decorator.py"
    click PAG_DEC2 "https://github.com/hmarcuzzo/fastgear/blob/main/fastgear/decorators/pagination_with_search_decorator.py"
    click DB_MW "https://github.com/hmarcuzzo/fastgear/blob/main/fastgear/middlewares/db_session_middleware.py"
    click EXC_HND "https://github.com/hmarcuzzo/fastgear/blob/main/fastgear/handlers/http_exceptions_handler.py"
    click ENUM_UTIL "https://github.com/hmarcuzzo/fastgear/blob/main/fastgear/utils/enum_utils.py"
    click JSON_UTIL "https://github.com/hmarcuzzo/fastgear/blob/main/fastgear/utils/json_utils.py"
    click LOG_UTIL "https://github.com/hmarcuzzo/fastgear/blob/main/fastgear/utils/logger_utils.py"
    click PAG_UTIL "https://github.com/hmarcuzzo/fastgear/blob/main/fastgear/utils/pagination_utils.py"
    click TYPES_EXC "https://github.com/hmarcuzzo/fastgear/blob/main/fastgear/types/custom_base_exception.py"
    click TYPES_PAG "https://github.com/hmarcuzzo/fastgear/blob/main/fastgear/types/pagination.py"
    click TYPES_PAG "https://github.com/hmarcuzzo/fastgear/blob/main/fastgear/types/custom_pages.py"
    click TYPES_RES "https://github.com/hmarcuzzo/fastgear/blob/main/fastgear/types/find_one_options.py"
    click TYPES_RES "https://github.com/hmarcuzzo/fastgear/blob/main/fastgear/types/find_many_options.py"
    click TYPES_RES "https://github.com/hmarcuzzo/fastgear/blob/main/fastgear/types/update_result.py"
    click TYPES_RES "https://github.com/hmarcuzzo/fastgear/blob/main/fastgear/types/delete_result.py"
    click CONSTS "https://github.com/hmarcuzzo/fastgear/blob/main/fastgear/constants/regex_expressions.py"

    %% Styles
    classDef framework fill:#E3F2FD,stroke:#1976D2,color:#0D47A1;
    classDef core fill:#E8F5E9,stroke:#388E3C,color:#1B5E20;
    classDef data fill:#FFF3E0,stroke:#FB8C00,color:#E65100;
    classDef schema fill:#F3E5F5,stroke:#8E24AA,color:#4A148C;
    classDef utils fill:#ECEFF1,stroke:#455A64,color:#263238;
    classDef types fill:#FFEBEE,stroke:#D32F2F,color:#B71C1C;
    classDef external fill:#EEEEEE,stroke:#757575,color:#424242;
```
