# loopsociety/backend-loopsociety architecture

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

- Interactive diagram: https://gitdiagram.com/loopsociety/backend-loopsociety
- Repository: https://github.com/loopsociety/backend-loopsociety

## Overview

##### Project type and purpose
- This is a backend RESTful API (“LoopSociety API”) for a collaborative forum, built in Python with FastAPI, SQLModel, MySQL and Alembic.
- It exposes endpoints for threads, posts, users, categories and authentication (JWT/OAuth2).

##### High-level components
a. Client(s)
- Web/Mobile frontend or other HTTP clients
b. API Layer (FastAPI)
- app/main.py
- app/api/v1/endpoints/*.py (routers/controllers)
c. Core / Infrastructure
- app/core/dependencies.py (DI providers)
- app/core/security.py (JWT/OAuth2 handling)
d. Data Access
- SQLModel + MySQL engine (app/db/database.py, config.py)
- ORM models (app/models/*.py)
- Alembic migrations (alembic/…)
e. Business Logic (Services)
- app/services (not shown in tree but implied—codify use-cases here)
f. External services
- MySQL database
- OAuth2 identity providers (if used)
- (Optional) Docker / Docker Hub

##### Relationships and data flows
- Clients issue HTTP requests → API Layer (FastAPI routers).
- Routers resolve dependencies via app/core/dependencies → may call security routines to validate JWT.
- Routers invoke Service layer (business logic) to perform actions (e.g., create post).
- Services use Data Access layer (SQLModel sessions from app/db/database.py) to query/persist models (app/models).
- Alembic tracks and applies schema changes to MySQL.
- Responses propagate back through routers to clients.

##### Architectural patterns and principles
- Layered Architecture (Presentation → Application/Service → Data Access)
- Dependency Injection (FastAPI’s Depends)
- Modular code organization (clear separation of routers, core, models, migrations)
- Use of externalized configuration (.env, alembic.ini)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients Layer
    subgraph "Clients"
        direction TB
        Clients["Clients\n(Web/Mobile)"]:::external
    end

    %% API Layer
    subgraph "API (FastAPI)"
        direction TB
        Main["app/main.py"]:::api
        subgraph "Routers (app/api/v1/endpoints)"
            direction TB
            Auth["auth.py"]:::api
            Users["users.py"]:::api
            Categories["categories.py"]:::api
            Threads["threads.py"]:::api
            Posts["posts.py"]:::api
        end
    end

    %% Core Layer
    subgraph "Core / Infrastructure"
        direction TB
        Dependencies["dependencies.py"]:::core
        Security["security.py"]:::core
    end

    %% Services Layer
    subgraph "Services"
        direction TB
        Services["Business Logic\n(app/services)"]:::services
    end

    %% Data Access Layer
    subgraph "Data Access"
        direction TB
        Config["config.py"]:::data
        DatabaseSetup["database.py"]:::data
        subgraph "ORM Models"
            direction TB
            UserModel["user.py"]:::data
            UserSessionModel["user_session.py"]:::data
            CategoryModel["category.py"]:::data
            ThreadModel["thread.py"]:::data
            PostModel["post.py"]:::data
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        MySQL["MySQL Database"]:::db
        OAuth2["OAuth2 Provider"]:::cloud
        Alembic["Alembic Migrations"]:::migrations
    end

    %% Configuration Flow
    Env[".env\n(DATABASE_URL, SECRET_KEY)"]:::cloud

    %% Connections
    Clients -->|"HTTP Request"| Main
    Main -->|"Include Routers"| Auth
    Main --> Users
    Main --> Categories
    Main --> Threads
    Main --> Posts

    Auth -->|"Depends"| Dependencies
    Users --> Dependencies
    Categories --> Dependencies
    Threads --> Dependencies
    Posts --> Dependencies

    Auth -->|"Validate JWT"| Security
    Users --> Security
    Categories --> Security
    Threads --> Security
    Posts --> Security

    Auth -->|"Calls"| Services
    Users --> Services
    Categories --> Services
    Threads --> Services
    Posts --> Services

    Services -->|"Uses Session"| DatabaseSetup
    Services --> UserModel
    Services --> UserSessionModel
    Services --> CategoryModel
    Services --> ThreadModel
    Services --> PostModel

    DatabaseSetup -->|"Connects via SQL"| MySQL
    Config -->|"Configures"| DatabaseSetup
    Env --> Config
    Env --> Security

    Alembic --> MySQL

    %% Click Events
    click Main "https://github.com/loopsociety/backend-loopsociety/blob/main/app/main.py"
    click Auth "https://github.com/loopsociety/backend-loopsociety/blob/main/app/api/v1/endpoints/auth.py"
    click Users "https://github.com/loopsociety/backend-loopsociety/blob/main/app/api/v1/endpoints/users.py"
    click Categories "https://github.com/loopsociety/backend-loopsociety/blob/main/app/api/v1/endpoints/categories.py"
    click Threads "https://github.com/loopsociety/backend-loopsociety/blob/main/app/api/v1/endpoints/threads.py"
    click Posts "https://github.com/loopsociety/backend-loopsociety/blob/main/app/api/v1/endpoints/posts.py"
    click Dependencies "https://github.com/loopsociety/backend-loopsociety/blob/main/app/core/dependencies.py"
    click Security "https://github.com/loopsociety/backend-loopsociety/blob/main/app/core/security.py"
    click Config "https://github.com/loopsociety/backend-loopsociety/blob/main/app/db/config.py"
    click DatabaseSetup "https://github.com/loopsociety/backend-loopsociety/blob/main/app/db/database.py"
    click UserModel "https://github.com/loopsociety/backend-loopsociety/blob/main/app/models/user.py"
    click UserSessionModel "https://github.com/loopsociety/backend-loopsociety/blob/main/app/models/user_session.py"
    click CategoryModel "https://github.com/loopsociety/backend-loopsociety/blob/main/app/models/category.py"
    click ThreadModel "https://github.com/loopsociety/backend-loopsociety/blob/main/app/models/thread.py"
    click PostModel "https://github.com/loopsociety/backend-loopsociety/blob/main/app/models/post.py"
    click Alembic "https://github.com/loopsociety/backend-loopsociety/blob/main/alembic.ini"
    click Alembic "https://github.com/loopsociety/backend-loopsociety/blob/main/alembic/env.py"
    click Alembic "https://github.com/loopsociety/backend-loopsociety/tree/main/alembic/versions/"

    %% Styles
    classDef external fill:#F0F0F0,stroke:#333,stroke-width:1px
    classDef api fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef core fill:#D0FFD8,stroke:#333,stroke-width:1px
    classDef services fill:#FFE8B2,stroke:#333,stroke-width:1px
    classDef data fill:#FFF2B2,stroke:#333,stroke-width:1px
    classDef db fill:#FFD8D0,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef migrations fill:#F8D0FF,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef cloud fill:#E0E0E0,stroke:#666,stroke-width:1px,stroke-dasharray: 2 2
```
