# carlosmmorera/fastapi-ms-base architecture

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

- Interactive diagram: https://gitdiagram.com/carlosmmorera/fastapi-ms-base
- Repository: https://github.com/carlosmmorera/fastapi-ms-base

## Overview

##### Project Type & Purpose
- This is a microservice designed using Python and FastAPI.
- Its purpose is to offer a base template for building FastAPI microservices.
- It includes API endpoints, middleware, configuration management, and a storage layer (with PostgreSQL as an example connector).

##### Analyzing the File Structure
- Top-level files (.env, .gitignore, Dockerfile, README.md) indicate environment configuration and containerization.
- The config/ directory with JSON files (default, dev, and pro configurations) suggests environment-specific configuration management.
- The src/ folder is the heart of the application and contains:
- The main FastAPI application file (app.py and main.py)
- An api/ subdirectory that holds several important elements:
- controllers (e.g., health.py): for business logic tied to API endpoints.
- exceptions: where custom HTTP exceptions are defined.
- middleware (mdw): which includes authentication checks and logging.
- routers: to establish paths for configuration and example API endpoints.
- schema: for request/response validation using Pydantic models.
- A config/ subdirectory inside src for application-specific configuration files (e.g., postgresql settings, API versioning).
- A storage/ subdirectory responsible for data persistence, including connectors for PostgreSQL, CRUD operations, and entity definitions.
- Additional support files like the Postman collection imply integrated API testing.

##### Key Components
a. Front-facing API Layer:
- Subdivide into Routers and Controllers:
- Routers handle endpoint definitions (src/api/routers).
- Controllers process business logic (src/api/controllers).
- Middleware components:
- Authentication and logging middleware (src/api/mdw) that pre-process requests.
- Exception handling (src/api/exceptions) to standardize error responses.
- API Schema:
- Data validation and serialization (src/api/schema).
b. Configuration Management:
- A configuration module reading from config/ and envs/ directories.
- This allows dynamic configuration based on environments (development, production, etc.).
c. Storage Layer:
- Database connectivity shown via a PostgreSQL connector (src/storage/connectors/postgresql.py).
- CRUD operations and entity models in src/storage/crud and src/storage/entities.
d. External & Development Tools:
- Dockerfile (containerization).
- Postman collection for API testing.
- Uvicorn as the ASGI server running the application.

##### Architectural Patterns & Relationships
- The separation of concerns is clear: API (presentation) → Controllers (logic) → Storage (data).
- The project adopts a layered architecture:
- The API layer communicates with middleware (e.g., authcheck, logging) before dispatching to controllers.
- Controllers interact with a storage layer that abstracts database operations.
- Configuration and environment management is isolated from the core business logic, ensuring flexibility.

## Diagram (Mermaid)

```mermaid
flowchart TD
    CLIENT("Client Requests"):::client

    subgraph "API Layer"
        subgraph "Entrypoints"
            APP("FastAPI App (app.py)"):::app
            MAIN("Main (main.py)"):::app
        end
        ROUTERS("API Routers"):::routers
        subgraph "Middleware"
            AUTH("Auth Middleware (authcheck.py)"):::middleware
            LOG("Log Middleware (logmiddleware.py)"):::middleware
            AUTHTYPES("Auth Types (authchecktypes)"):::middleware
        end
        EXCEPT("Exception Handling (HTTP Exceptions)"):::exceptions
        CONTROLLERS("API Controllers (health.py)"):::controllers
        subgraph "API Schema"
            EXREQ("Example Request (examplerequest.py)"):::schema
            EXRESP("Example Responses (exampleresponses.py)"):::schema
            HEALTHRESP("Health Response (healthresponse.py)"):::schema
            REQ("Generic Request (request.py)"):::schema
        end
    end

    subgraph "Configuration Management"
        CONFIGS("Config Files (default.json, dev.json, pro.json)"):::config
        SRCCONFIG("Src Configuration (config.py, api.py, postgresql.py, version.py)"):::config
    end

    subgraph "Storage Layer"
        CONNECTOR("PostgreSQL Connector (postgresql.py)"):::storage
        CRUD("CRUD Module (example.py)"):::storage
        ENTITIES("Entities (example.py)"):::storage
        DB("PostgreSQL Database"):::database
    end

    subgraph "External & Development Tools"
        DOCKER("Dockerfile"):::external
        ENVFILE(".env File"):::external
        POSTMAN("Postman Collection"):::external
        UVICORN("Uvicorn ASGI Server"):::external
    end

    CLIENT -->|"HTTPRequest"| APP
    CLIENT -->|"HTTPRequest"| MAIN
    APP -->|"Initializes"| ROUTERS
    MAIN -->|"Initializes"| ROUTERS
    ROUTERS -->|"Forwards"| AUTH
    ROUTERS -->|"Forwards"| LOG
    ROUTERS -->|"Forwards"| AUTHTYPES
    AUTH -->|"Authenticates"| CONTROLLERS
    LOG -->|"Logs"| CONTROLLERS
    AUTHTYPES -->|"ProvidesTypes"| CONTROLLERS
    CONTROLLERS -->|"HandlesErrors"| EXCEPT
    CONTROLLERS -->|"Validates"| EXREQ
    CONTROLLERS -->|"Validates"| EXRESP
    CONTROLLERS -->|"Validates"| HEALTHRESP
    CONTROLLERS -->|"Validates"| REQ
    CONTROLLERS -->|"Calls"| CONNECTOR
    CONNECTOR -->|"Executes"| CRUD
    CRUD -->|"Interacts"| ENTITIES
    ENTITIES -->|"StoresData"| DB

    CONFIGS -->|"Loads"| APP
    SRCCONFIG -->|"Configures"| AUTH
    SRCCONFIG -->|"Configures"| CONTROLLERS
    SRCCONFIG -->|"Configures"| CONNECTOR

    DOCKER -->|"Containerizes"| APP
    ENVFILE -->|"ProvidesVars"| APP
    POSTMAN -->|"Tests"| APP
    UVICORN -->|"Serves"| APP

    %% Click Events
    click APP "https://github.com/carlosmmorera/fastapi-ms-base/blob/main/src/app.py"
    click MAIN "https://github.com/carlosmmorera/fastapi-ms-base/blob/main/src/main.py"
    click ROUTERS "https://github.com/carlosmmorera/fastapi-ms-base/tree/main/src/api/routers"
    click CONTROLLERS "https://github.com/carlosmmorera/fastapi-ms-base/blob/main/src/api/controllers/health.py"
    click AUTH "https://github.com/carlosmmorera/fastapi-ms-base/blob/main/src/api/mdw/authcheck.py"
    click LOG "https://github.com/carlosmmorera/fastapi-ms-base/blob/main/src/api/mdw/logmiddleware.py"
    click AUTHTYPES "https://github.com/carlosmmorera/fastapi-ms-base/tree/main/src/api/mdw/authchecktypes/"
    click EXCEPT "https://github.com/carlosmmorera/fastapi-ms-base/blob/main/src/api/exceptions/httpexception.py"
    click EXREQ "https://github.com/carlosmmorera/fastapi-ms-base/blob/main/src/api/schema/examplerequest.py"
    click EXRESP "https://github.com/carlosmmorera/fastapi-ms-base/blob/main/src/api/schema/exampleresponses.py"
    click HEALTHRESP "https://github.com/carlosmmorera/fastapi-ms-base/blob/main/src/api/schema/healthresponse.py"
    click REQ "https://github.com/carlosmmorera/fastapi-ms-base/blob/main/src/api/schema/request.py"
    click CONFIGS "https://github.com/carlosmmorera/fastapi-ms-base/tree/main/config/"
    click SRCCONFIG "https://github.com/carlosmmorera/fastapi-ms-base/tree/main/src/config"
    click CONNECTOR "https://github.com/carlosmmorera/fastapi-ms-base/blob/main/src/storage/connectors/postgresql.py"
    click CRUD "https://github.com/carlosmmorera/fastapi-ms-base/blob/main/src/storage/crud/example.py"
    click ENTITIES "https://github.com/carlosmmorera/fastapi-ms-base/blob/main/src/storage/entities/example.py"
    click DOCKER "https://github.com/carlosmmorera/fastapi-ms-base/tree/main/Dockerfile"
    click ENVFILE "https://github.com/carlosmmorera/fastapi-ms-base/blob/main/.env"
    click POSTMAN "https://github.com/carlosmmorera/fastapi-ms-base/blob/main/fastapi-ms-base.postman_collection.json"

    %% Styles
    classDef client fill:#f9c,stroke:#333,stroke-width:2px;
    classDef app fill:#bbf,stroke:#333,stroke-width:2px;
    classDef routers fill:#ccf,stroke:#333,stroke-width:2px;
    classDef middleware fill:#cfc,stroke:#333,stroke-width:2px;
    classDef exceptions fill:#fcc,stroke:#333,stroke-width:2px;
    classDef controllers fill:#fcf,stroke:#333,stroke-width:2px;
    classDef schema fill:#ffc,stroke:#333,stroke-width:2px;
    classDef config fill:#def,stroke:#333,stroke-width:2px;
    classDef storage fill:#fed,stroke:#333,stroke-width:2px;
    classDef database fill:#fdd,stroke:#333,stroke-width:2px;
    classDef external fill:#dfd,stroke:#333,stroke-width:2px;
```
