# 1shisir/fastapi_backend architecture

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

- Interactive diagram: https://gitdiagram.com/1shisir/fastapi_backend
- Repository: https://github.com/1shisir/fastapi_backend

## Overview

##### Project Type and Purpose
- This is a backend-only REST API service built with FastAPI (Python).
- Its domain is a social-network style application supporting users, posts, likes, groups, messaging, connection requests, and notifications.
- It uses PostgreSQL for data persistence and Cloudinary for storing images.

##### File Structure
- Top-level files:
- main.py: application entry point where the FastAPI app is instantiated and routers are included.
- requirements.txt: Python dependencies.
- readme.txt: setup instructions.
- app/api/v1: API layer modules (auth.py, user.py) that define endpoint handlers.
- app/routers: higher-level routers grouping endpoints by feature (admin, chat, connections, groups, like, post).
- app/db:
- session.py: SQLAlchemy session management.
- base.py: base ORM metadata.
- models/: SQLAlchemy ORM models mapping to DB tables (user, post, message, etc.).
- app/core/security.py: security utilities (password hashing, JWT).

##### Extract Key Insights from the README
- Uses a .env file to configure PostgreSQL connection and Cloudinary credentials.
- Launches with “uvicorn main:app --reload” and exposes Swagger UI at /docs for interactive API testing.
- Cloudinary is the sole external service for image storage.

##### Main Components
a. External Client(s):
- Web or mobile frontend (not in repo) consuming the API via HTTP/HTTPS.
b. FastAPI Application:
- Request Handlers (routers & api modules)
- Business Logic & Security (core/security)
- Data Validation Layer (schemas)
c. Database Layer:
- PostgreSQL instance
- SQLAlchemy ORM (models, session)
d. External Service:
- Cloudinary for image uploads and storage
e. Deployment/Runtime:
- Uvicorn ASGI server hosting the FastAPI app

##### Relationships & Data Flows
- Client → FastAPI (HTTP requests)
- FastAPI → Database (SQLAlchemy session queries/inserts/updates)
- FastAPI → Cloudinary (upload/download images via Cloudinary API)
- FastAPI → Client (HTTP responses, JSON payloads)
- FastAPI components link: routers call API modules, which use schemas for validation and models for persistence, with security utilities applied on protected endpoints.

##### Architectural Patterns & Design Principles
- Layered architecture:
- API/Controller layer (routers & app/api)
- Service/Business layer (app/core)
- Data/Repository layer (app/db + SQLAlchemy models)
- DTO layer (Pydantic schemas)
- Separation of concerns: authentication/authorization is encapsulated in core/security, persistence is encapsulated in db/session & models.
- Configuration via environment variables ensures 12-factor compliance.
- Async support via FastAPI/Uvicorn for high concurrency.

##### Detailed Component Break-Out
- Routers (chat, connections, groups, like, post, admin)
- API modules (app/api/v1/auth.py, user.py)
- Core/security
- Database interface (session + models)
- Link each router to the corresponding schema and model sets (e.g. post router uses post schema & post model).

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["External Client"]:::external
    Cloudinary["Cloudinary Service"]:::external
    Postgres[(PostgreSQL DB)]:::db

    subgraph "Uvicorn ASGI Server"
        UV["Uvicorn"]:::service
        subgraph "FastAPI Application"
            direction TB
            Entry["main.py"]:::entry

            subgraph "Configuration"
                Req["requirements.txt"]:::entry
                Read["readme.txt"]:::entry
            end

            subgraph "Routers"
                direction TB
                AdminR["admin.py"]:::api
                ChatR["chat.py"]:::api
                ConR["connections.py"]:::api
                GroupsR["groups.py"]:::api
                LikeR["like.py"]:::api
                PostR["post.py"]:::api
            end

            subgraph "API Controllers (V1)"
                AuthAPI["auth.py"]:::api
                UserAPI["user.py"]:::api
            end

            Sec["security.py"]:::core

            subgraph "Schemas (Pydantic DTOs)"
                direction TB
                ConnReqS["connection_request.py"]:::schema
                GroupsS["groups.py"]:::schema
                MsgS["message.py"]:::schema
                NotifS["notifications.py"]:::schema
                PostS["post.py"]:::schema
                TokenS["token.py"]:::schema
                UserS["user.py"]:::schema
                UserInfoS["user_info.py"]:::schema
            end

            subgraph "DB Interface"
                Sess["session.py"]:::db
                Base["base.py"]:::db
                subgraph "Models"
                    direction TB
                    ConnReqM["connection_request.py"]:::model
                    GroupM["group.py"]:::model
                    LikeM["like.py"]:::model
                    MsgM["message.py"]:::model
                    NotifM["notifications.py"]:::model
                    PostM["post.py"]:::model
                    UserM["user.py"]:::model
                    UserInfoM["user_info.py"]:::model
                end
            end
        end
    end

    Client -->|"HTTP request"| UV
    UV -->|"invoke"| Entry
    Entry --> Req
    Entry --> Read
    Entry --> AdminR
    Entry --> ChatR
    Entry --> ConR
    Entry --> GroupsR
    Entry --> LikeR
    Entry --> PostR

    AdminR --> AuthAPI
    ChatR --> UserAPI
    ConR --> AuthAPI
    GroupsR --> AuthAPI
    LikeR --> AuthAPI
    PostR --> AuthAPI

    AuthAPI --> Sec
    UserAPI --> Sec

    AuthAPI -->|"validate"| ConnReqS
    AuthAPI -->|"validate"| TokenS
    UserAPI -->|"validate"| UserS

    Sec -->|"hash & sign JWT"| TokenS

    AdminR --> GroupsS
    ChatR --> MsgS
    ConR --> ConnReqS
    GroupsR --> GroupsS
    LikeR --> LikeM
    PostR --> PostS

    AuthAPI -->|"query/modify"| Sess
    UserAPI -->|"query/modify"| Sess

    Sess --> Base
    Base --> ConnReqM
    Base --> GroupM
    Base --> LikeM
    Base --> MsgM
    Base --> NotifM
    Base --> PostM
    Base --> UserM
    Base --> UserInfoM
    Sess --> Postgres

    PostR -->|"upload/download image"| Cloudinary
    UV -->|"HTTP response"| Client

    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef service fill:#bbf,stroke:#333,stroke-width:1px
    classDef entry fill:#bfb,stroke:#333,stroke-width:1px
    classDef api fill:#fbf,stroke:#333,stroke-width:1px
    classDef core fill:#ffb,stroke:#333,stroke-width:1px
    classDef schema fill:#fbb,stroke:#333,stroke-width:1px
    classDef db fill:#bff,stroke:#333,stroke-width:1px
    classDef model fill:#fdc,stroke:#333,stroke-width:1px

    click Entry "https://github.com/1shisir/fastapi_backend/blob/main/main.py"
    click AuthAPI "https://github.com/1shisir/fastapi_backend/blob/main/app/api/v1/auth.py"
    click UserAPI "https://github.com/1shisir/fastapi_backend/blob/main/app/api/v1/user.py"
    click AdminR "https://github.com/1shisir/fastapi_backend/blob/main/app/routers/admin.py"
    click ChatR "https://github.com/1shisir/fastapi_backend/blob/main/app/routers/chat.py"
    click ConR "https://github.com/1shisir/fastapi_backend/blob/main/app/routers/connections.py"
    click GroupsR "https://github.com/1shisir/fastapi_backend/blob/main/app/routers/groups.py"
    click LikeR "https://github.com/1shisir/fastapi_backend/blob/main/app/routers/like.py"
    click PostR "https://github.com/1shisir/fastapi_backend/blob/main/app/routers/post.py"
    click Sec "https://github.com/1shisir/fastapi_backend/blob/main/app/core/security.py"
    click ConnReqS "https://github.com/1shisir/fastapi_backend/blob/main/app/schemas/connection_request.py"
    click GroupsS "https://github.com/1shisir/fastapi_backend/blob/main/app/schemas/groups.py"
    click MsgS "https://github.com/1shisir/fastapi_backend/blob/main/app/schemas/message.py"
    click NotifS "https://github.com/1shisir/fastapi_backend/blob/main/app/schemas/notifications.py"
    click PostS "https://github.com/1shisir/fastapi_backend/blob/main/app/schemas/post.py"
    click TokenS "https://github.com/1shisir/fastapi_backend/blob/main/app/schemas/token.py"
    click UserS "https://github.com/1shisir/fastapi_backend/blob/main/app/schemas/user.py"
    click UserInfoS "https://github.com/1shisir/fastapi_backend/blob/main/app/schemas/user_info.py"
    click Sess "https://github.com/1shisir/fastapi_backend/blob/main/app/db/session.py"
    click Base "https://github.com/1shisir/fastapi_backend/blob/main/app/db/base.py"
    click ConnReqM "https://github.com/1shisir/fastapi_backend/blob/main/app/db/models/connection_request.py"
    click GroupM "https://github.com/1shisir/fastapi_backend/blob/main/app/db/models/group.py"
    click LikeM "https://github.com/1shisir/fastapi_backend/blob/main/app/db/models/like.py"
    click MsgM "https://github.com/1shisir/fastapi_backend/blob/main/app/db/models/message.py"
    click NotifM "https://github.com/1shisir/fastapi_backend/blob/main/app/db/models/notifications.py"
    click PostM "https://github.com/1shisir/fastapi_backend/blob/main/app/db/models/post.py"
    click UserM "https://github.com/1shisir/fastapi_backend/blob/main/app/db/models/user.py"
    click UserInfoM "https://github.com/1shisir/fastapi_backend/blob/main/app/db/models/user_info.py"
    click Req "https://github.com/1shisir/fastapi_backend/blob/main/requirements.txt"
    click Read "https://github.com/1shisir/fastapi_backend/blob/main/readme.txt"
```
