# amrit2356/template-fastapi-rest architecture

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

- Interactive diagram: https://gitdiagram.com/amrit2356/template-fastapi-rest
- Repository: https://github.com/amrit2356/template-fastapi-rest

## Overview

##### Project Type & Purpose
- This is a production-ready, back-end-only FastAPI REST template built in Python (3.11+) using Clean Architecture principles.
- It provides a modular API layer (8 endpoints), enterprise-grade configuration, process & server management, structured logging, multiple authentication methods, file management, plugin support, and built-in monitoring.

##### Main Components
a. Entry Point
- app.py – boots the FastAPI app, wires in middleware, routers, managers.
b. API Layer (src/api)
- routes.py – defines HTTP endpoints (/api/v1/…).
- handlers.py – request handling logic, session tracking.
- models.py – Pydantic models for request/response schemas.
c. Authentication Module (src/auth)
- auth_factory.py – selects auth strategy (JWT, API-Key, Hybrid) based on config.
- middleware.py – intercepts requests, enforces security.
- handlers/ – individual implementations for JWT, API-Key, Hybrid.
- models.py – auth data structures.
d. Core Managers (src/core)
- server_manager.py – application lifecycle (startup, shutdown, housekeeping).
- process_manager.py – orchestrates stateful/stateless processes, performs cleanup.
- managers.py – utility functions to fetch manager instances from request context.
e. Business Services (src/services)
- services.py – generic service implementations and pipeline stubs.
- pipelines/ – placeholder for custom processing pipelines.
f. Utilities (src/utils)
- config/ – YAML + env-var overrides, validation, modular loaders/providers.
- io/ – file reader/writer abstractions.
- resources/ – logger configuration, resource helpers/downloader.
g. Runtime Storage (runtime/)
- temp, outputs, logs, models, uploads, assets – file system areas managed by server/process managers.
h. Plugins (src/plugins)
- empty directory – extension point for database, monitoring, cloud providers.
i. Tests & Docs
- tests/ – unit, integration, e2e.
- docs/ – security and architecture documentation.

##### Relationships & Data Flow
1. Client → HTTP → Uvicorn/FastAPI (app.py)
2. Middleware Chain:
– CORS & Security (src/auth/middleware.py)
– Logging & Metrics
3. Router Dispatch (src/api/routes.py) → Handler (src/api/handlers.py)
4. Handlers call → Core Managers (e.g., get_server_manager, get_process_manager)
5. Core Managers interact with → Services (src/services) and → Utilities (config, io, resources)
6. Services may launch background processes via Process Manager
7. Process Manager writes to runtime/ (temp, outputs) and tracks cleanup
8. Server Manager drives graceful startup/shutdown and housekeeping tasks
9. External calls (e.g., OpenAI, Google APIs) orchestrated by service code using API keys from config

##### Architectural Patterns & Principles
- Clean Architecture: clear separation between API, domain (services), infrastructure (utils), and orchestration (core).
- Dependency Injection: managers and settings injected into handlers and services.
- Plugin Architecture: src/plugins illustrates extension points.
- Strategy Pattern: auth_factory chooses auth handler.
- Pipeline Pattern: placeholder pipelines for customizable processing.
- Configuration as Code: YAML + env-vars, modular loaders, validators.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    Client["Client"]:::external
    Client -->|"HTTP Request"| UVICORN

    %% Presentation Layer
    subgraph "Presentation Layer" 
        UVICORN["Uvicorn/FastAPI"]:::presentation
        APP["app.py"]:::presentation
        UVICORN --> APP
    end

    %% Cross-cutting Middleware
    subgraph "Cross-cutting (Auth, Logging, Metrics)" 
        AUTH_MW["src/auth/middleware.py"]:::crosscut
        AUTH_FACTORY["src/auth/auth_factory.py"]:::crosscut
        AUTH_MODELS["src/auth/models.py"]:::crosscut
        JWT_HANDLER["JWT Handler"]:::crosscut
        API_KEY_HANDLER["API-Key Handler"]:::crosscut
        HYBRID_HANDLER["Hybrid Handler"]:::crosscut
        AUTH_FACTORY --> JWT_HANDLER
        AUTH_FACTORY --> API_KEY_HANDLER
        AUTH_FACTORY --> HYBRID_HANDLER
        APP --> AUTH_MW
        AUTH_MW --> AUTH_FACTORY
        AUTH_MW -->|loads models| AUTH_MODELS
    end

    %% API Layer
    subgraph "API Layer" 
        ROUTES["src/api/routes.py"]:::application
        HANDLERS["src/api/handlers.py"]:::application
        API_MODELS["src/api/models.py"]:::application
        AUTH_MW --> ROUTES
        ROUTES --> HANDLERS
        HANDLERS --> API_MODELS
    end

    %% Application Domain
    subgraph "Application Domain (Services & Pipelines)" 
        SERVICES["src/services/services.py"]:::domain
        PIPELINES["Pipelines"]:::domain
        HANDLERS --> SERVICES
        SERVICES --> PIPELINES
    end

    %% Core Managers
    subgraph "Core Managers" 
        MANAGERS["src/core/managers.py"]:::domain
        SERVER_MGR["src/core/server_manager.py"]:::domain
        PROCESS_MGR["src/core/process_manager.py"]:::domain
        HANDLERS --> MANAGERS
        MANAGERS --> SERVER_MGR
        MANAGERS --> PROCESS_MGR
        SERVICES --> PROCESS_MGR
        SERVER_MGR -->|manages| APP
    end

    %% Infrastructure Layer
    subgraph "Infrastructure (Utils & Config)" 
        subgraph "Configuration System"
            CONFIG_YAML["config.yaml"]:::infra
            SETTINGS["settings.py"]:::infra
            INTERFACES["interfaces.py"]:::infra
            LOADERS["loaders.py"]:::infra
            PROVIDERS["providers.py"]:::infra
            SECTION_PROVIDERS["section_providers.py"]:::infra
            PROCESSORS["processors.py"]:::infra
            VALIDATORS["validators.py"]:::infra
            CONFIG_YAML --- SETTINGS
            SETTINGS --> INTERFACES
            SETTINGS --> LOADERS
            SETTINGS --> PROVIDERS
            SETTINGS --> SECTION_PROVIDERS
            SETTINGS --> PROCESSORS
            SETTINGS --> VALIDATORS
        end
        subgraph "IO"
            READER["reader.py"]:::infra
            WRITER["writer.py"]:::infra
            SERVICES --> READER
            SERVICES --> WRITER
        end
        subgraph "Resources"
            LOGGER["logger.py"]:::infra
            HELPER["helper.py"]:::infra
            SERVICES --> LOGGER
            SERVICES --> HELPER
        end
    end

    %% Plugins
    PLUGINS["src/plugins"]:::domain
    APP --> PLUGINS

    %% Runtime Storage
    RUNTIME["runtime/"]:::storage
    PROCESS_MGR -->|writes to| RUNTIME
    SERVER_MGR -->|cleanup| RUNTIME

    %% External Services
    subgraph "External Services"
        AUTH_PROVIDERS["Auth Providers"]:::external
        THIRD_PARTY["3rd-Party APIs"]:::external
        SERVICES --> AUTH_PROVIDERS
        SERVICES --> THIRD_PARTY
    end

    %% Documentation & Tests
    docs["docs/AUTH.md"]:::external
    tests["tests/"]:::external
    APP --> docs
    APP --> tests

    %% Click Events
    click APP "https://github.com/amrit2356/template-fastapi-rest/blob/production/app.py"
    click ROUTES "https://github.com/amrit2356/template-fastapi-rest/blob/production/src/api/routes.py"
    click HANDLERS "https://github.com/amrit2356/template-fastapi-rest/blob/production/src/api/handlers.py"
    click API_MODELS "https://github.com/amrit2356/template-fastapi-rest/blob/production/src/api/models.py"
    click AUTH_FACTORY "https://github.com/amrit2356/template-fastapi-rest/blob/production/src/auth/auth_factory.py"
    click AUTH_MW "https://github.com/amrit2356/template-fastapi-rest/blob/production/src/auth/middleware.py"
    click AUTH_MODELS "https://github.com/amrit2356/template-fastapi-rest/blob/production/src/auth/models.py"
    click JWT_HANDLER "https://github.com/amrit2356/template-fastapi-rest/blob/production/src/auth/handlers/jwt_handler.py"
    click API_KEY_HANDLER "https://github.com/amrit2356/template-fastapi-rest/blob/production/src/auth/handlers/api_key_handler.py"
    click HYBRID_HANDLER "https://github.com/amrit2356/template-fastapi-rest/blob/production/src/auth/handlers/hybrid_handler.py"
    click SERVER_MGR "https://github.com/amrit2356/template-fastapi-rest/blob/production/src/core/server_manager.py"
    click PROCESS_MGR "https://github.com/amrit2356/template-fastapi-rest/blob/production/src/core/process_manager.py"
    click MANAGERS "https://github.com/amrit2356/template-fastapi-rest/blob/production/src/core/managers.py"
    click SERVICES "https://github.com/amrit2356/template-fastapi-rest/blob/production/src/services/services.py"
    click PIPELINES "https://github.com/amrit2356/template-fastapi-rest/blob/production/src/services/pipelines/__init__.py"
    click CONFIG_YAML "https://github.com/amrit2356/template-fastapi-rest/blob/production/src/utils/config/config.yaml"
    click SETTINGS "https://github.com/amrit2356/template-fastapi-rest/blob/production/src/utils/config/settings.py"
    click INTERFACES "https://github.com/amrit2356/template-fastapi-rest/blob/production/src/utils/config/modules/interfaces.py"
    click LOADERS "https://github.com/amrit2356/template-fastapi-rest/blob/production/src/utils/config/modules/loaders.py"
    click PROVIDERS "https://github.com/amrit2356/template-fastapi-rest/blob/production/src/utils/config/modules/providers.py"
    click SECTION_PROVIDERS "https://github.com/amrit2356/template-fastapi-rest/blob/production/src/utils/config/modules/section_providers.py"
    click PROCESSORS "https://github.com/amrit2356/template-fastapi-rest/blob/production/src/utils/config/modules/processors.py"
    click VALIDATORS "https://github.com/amrit2356/template-fastapi-rest/blob/production/src/utils/config/modules/validators.py"
    click READER "https://github.com/amrit2356/template-fastapi-rest/blob/production/src/utils/io/reader.py"
    click WRITER "https://github.com/amrit2356/template-fastapi-rest/blob/production/src/utils/io/writer.py"
    click LOGGER "https://github.com/amrit2356/template-fastapi-rest/blob/production/src/utils/resources/logger.py"
    click HELPER "https://github.com/amrit2356/template-fastapi-rest/blob/production/src/utils/resources/helper.py"
    click PLUGINS "https://github.com/amrit2356/template-fastapi-rest/blob/production/src/plugins/__init__.py"
    click docs "https://github.com/amrit2356/template-fastapi-rest/blob/production/docs/AUTH.md"
    click tests "https://github.com/amrit2356/template-fastapi-rest/tree/production/tests/"

    %% Style Definitions
    classDef presentation fill:#D0E8FF,stroke:#0366d6,color:#0366d6,stroke-width:1px;
    classDef application fill:#E1F8E7,stroke:#1e8e3e,color:#1e8e3e,stroke-width:1px;
    classDef domain fill:#FFF4E5,stroke:#d9822b,color:#d9822b,stroke-width:1px;
    classDef infra fill:#FFEFEF,stroke:#d04437,color:#d04437,stroke-width:1px;
    classDef crosscut fill:#F3E8FF,stroke:#8250df,color:#8250df,stroke-width:1px;
    classDef external fill:#F0F0F0,stroke:#6c757d,color:#6c757d,stroke-width:1px;
    classDef storage fill:#E5F6FF,stroke:#1ba1ec,color:#1ba1ec,stroke-width:1px;
```
