# b0llu/stories-backend architecture

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

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

## Overview

##### Project type and purpose
- This is a backend-only, RESTful API service built with FastAPI.
- Its primary role is to provide CRUD operations for “stories” along with user authentication and management.
- Key use cases: user signup/login, creating/updating/deleting stories, listing stories, handling media uploads via Cloudinary.

##### File structure
- Top-level:
- alembic/ & alembic.ini – database migration tooling (SQLAlchemy + Alembic)
- app/ – main application code
- run.py – entry point that boots the FastAPI server
- requirements.txt – Python dependencies
- app/ submodules:
- main.py – creates FastAPI instance, attaches routers and middleware
- database.py – session/engine setup for PostgreSQL
- models.py & schemas.py – SQLAlchemy models and Pydantic schemas
- routers/ – REST endpoints grouped by domain (auth, users, stories)
- auth/ – authentication logic, JWT handling (in utils.py)
- middleware/ – request-level middleware (auth enforcement)
- utils/cloudinary.py – wrapper around Cloudinary for media uploads

##### README for additional insights
- Tech stack: Python 3.8+, FastAPI, PostgreSQL, SQLAlchemy, Alembic, Pydantic, Cloudinary.
- Runtime: run.py launches Uvicorn/Starlette server with auto-docs at /docs and /redoc.
- Database workflow: Alembic for versioned migrations invoked via CLI.

##### Detail but avoid over-segmenting
- Related routers under a single “API Endpoints” block if desired, but call out auth vs. stories vs. users.
- Both persistent state (DB) and external state (Cloudinary).
- Offline migration process distinctly from the live request flow.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Client
    Client["Client (Browser/Mobile)"]:::external

    %% FastAPI Server Entry Point
    FastAPIServer["FastAPI Server<br/>Uvicorn ASGI"]:::server
    click FastAPIServer "https://github.com/b0llu/stories-backend/blob/main/run.py"

    %% FastAPI Application Setup
    FastAPIApp["FastAPI Application"]:::server
    click FastAPIApp "https://github.com/b0llu/stories-backend/blob/main/app/main.py"

    %% Middleware Layer
    AuthMiddleware["Authentication Middleware<br/>(JWT enforcement)"]:::middleware
    click AuthMiddleware "https://github.com/b0llu/stories-backend/blob/main/app/middleware/auth.py"

    %% Routers Layer
    subgraph "API Endpoints"
        AuthRouter["Auth Router<br/>(signup/login)"]:::router
        click AuthRouter "https://github.com/b0llu/stories-backend/blob/main/app/routers/auth.py"
        UsersRouter["Users Router<br/>(user management)"]:::router
        click UsersRouter "https://github.com/b0llu/stories-backend/blob/main/app/routers/users.py"
        StoriesRouter["Stories Router<br/>(stories CRUD)"]:::router
        click StoriesRouter "https://github.com/b0llu/stories-backend/blob/main/app/routers/stories.py"
    end

    %% Business Logic Utilities
    AuthUtils["Auth Utilities<br/>(JWT gen/val)"]:::util
    click AuthUtils "https://github.com/b0llu/stories-backend/blob/main/app/auth/utils.py"
    CloudinaryUtils["Cloudinary Utilities<br/>(media upload)"]:::util
    click CloudinaryUtils "https://github.com/b0llu/stories-backend/blob/main/app/utils/cloudinary.py"

    %% Data Layer
    DatabaseConfig["DB Config & ORM Session"]:::data
    click DatabaseConfig "https://github.com/b0llu/stories-backend/blob/main/app/database.py"
    Models["SQLAlchemy Models"]:::data
    click Models "https://github.com/b0llu/stories-backend/blob/main/app/models.py"
    Schemas["Pydantic Schemas"]:::data
    click Schemas "https://github.com/b0llu/stories-backend/blob/main/app/schemas.py"
    PostgreSQL["PostgreSQL Database"]:::data

    %% Migration Subsystem
    subgraph "Migrations (Offline)"
        AlembicConfig["alembic.ini"]:::migrations
        click AlembicConfig "https://github.com/b0llu/stories-backend/blob/main/alembic.ini"
        AlembicEnv["alembic/env.py"]:::migrations
        click AlembicEnv "https://github.com/b0llu/stories-backend/blob/main/alembic/env.py"
        AlembicVersions["versions/*.py"]:::migrations
        click AlembicVersions "https://github.com/b0llu/stories-backend/tree/main/alembic/versions/"
    end

    %% External Service
    Cloudinary["Cloudinary Service"]:::externalService

    %% Flow Connections
    Client -->|HTTP Requests| FastAPIServer
    FastAPIServer --> FastAPIApp
    FastAPIApp -->|Depends on| AuthMiddleware
    FastAPIApp -->|Registers| AuthRouter
    FastAPIApp -->|Registers| UsersRouter
    FastAPIApp -->|Registers| StoriesRouter

    AuthMiddleware -->|Validates JWT| AuthUtils

    AuthRouter -->|Uses| AuthUtils
    StoriesRouter -->|Uploads media via| CloudinaryUtils
    StoriesRouter -->|CRUD via| DatabaseConfig
    UsersRouter -->|CRUD via| DatabaseConfig

    DatabaseConfig -->|Session uses| Models
    DatabaseConfig -->|Schemas for I/O| Schemas
    Models -->|Persist data| PostgreSQL
    DatabaseConfig -->|Commits| PostgreSQL

    Models -->|Schema source| AlembicEnv
    AlembicEnv -->|Reads config| AlembicConfig
    AlembicEnv -->|Generates| AlembicVersions
    AlembicEnv -->|Applies migrations to| PostgreSQL

    CloudinaryUtils -->|Calls API| Cloudinary

    %% Styles
    classDef external fill:#f2f2f2,stroke:#333,stroke-width:1px
    classDef server fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef middleware fill:#ffe0b2,stroke:#333,stroke-width:1px
    classDef router fill:#dcedc8,stroke:#333,stroke-width:1px
    classDef util fill:#fff3b0,stroke:#333,stroke-width:1px
    classDef data fill:#f8d7da,stroke:#333,stroke-width:1px
    classDef migrations fill:#f4cccc,stroke:#333,stroke-width:1px
    classDef externalService fill:#d0e0e3,stroke:#333,stroke-width:1px
```
