# melbanna3/blog-ai architecture

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

- Interactive diagram: https://gitdiagram.com/melbanna3/blog-ai
- Repository: https://github.com/melbanna3/blog-ai

## Overview

##### Project type and purpose
- This is a standalone backend service: a RESTful Blog API built with FastAPI.
- Purpose: Manage users, categories, posts, and comments over HTTP, backed by PostgreSQL, secured with JWT.

##### File structure
- Top-level files:
- main.py – entry point where the FastAPI app, routers, and middleware are wired up.
- requirements.txt, runtime.txt – list Python dependencies & specify Python runtime (e.g., for Heroku).
- .env – environment variables (DB URL, JWT secret).
- Procfile – deployment command (e.g., `web: uvicorn main:app`).
- No separate “frontend” or “services” directories: this is a monolithic service.

##### Key README insights
- Endpoints grouped by resource (Users, Categories, Posts, Comments).
- Uses SQLAlchemy ORM for DB models.
- JWT for stateless authentication.
- Interactive docs (Swagger) at `/docs`.

##### Main components
a. Clients
- Web/Mobile clients or API clients (curl, Postman).
b. API Layer
- FastAPI app instance
- Routers/controllers for each resource (users, auth, categories, posts, comments)
- Dependency injection (DB session, security)
c. Business Logic
- Services or use-case modules (e.g., user_service, post_service)
- Data validation (Pydantic schemas)
d. Persistence Layer
- PostgreSQL database
- Tables: users, categories, posts, comments
- SQLAlchemy ORM (models + session management)
e. Security
- JWT authentication/authorization component
- Token issuance (`/token` endpoint)
- Protected endpoints requiring `Authorization: Bearer`
f. Infrastructure / Deployment
- Uvicorn ASGI server
- Hosting environment (Heroku, AWS, Docker, etc.)
- Environment variables (.env)

##### Relationships and data flows
- Client → HTTP request → FastAPI router
- Router → Validate input (Pydantic) → Delegate to service
- Service → Query/modify DB via SQLAlchemy session
- Service → Return domain object → Router → Serialize to JSON response
- For protected endpoints: Router checks JWT (via FastAPI dependency), rejects or injects current user
- Deployment: Procfile invokes Uvicorn, reads env variables to configure DB and JWT.

##### Architectural patterns & design principles
- Layered architecture: Presentation (routers) → Application (services) → Persistence (ORM)
- Stateless REST API, relying on JWT for auth (no server-side sessions)
- Dependency injection pattern for DB sessions and security credentials
- Single codebase monolith, but cleanly separated modules (routers, models, schemas, services)

##### Final checklist
- [ ] Clear labels on all components (Client, FastAPI API, Routers, Services, DB, Auth)
- [ ] Call out environment variables and deployment entrypoint (Procfile → Uvicorn)
- [ ] Show tables (users, categories, posts, comments) inside the DB component

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    Client["Web/Mobile Clients<br>(curl, Postman)"]:::external

    %% API Layer
    subgraph "API Layer"
        direction TB
        FastAPIApp["FastAPI App (main.py)"]:::api
        UsersRouter["Users Router"]:::api
        AuthRouter["Auth Router"]:::api
        CategoriesRouter["Categories Router"]:::api
        PostsRouter["Posts Router"]:::api
        CommentsRouter["Comments Router"]:::api
    end

    %% Business Logic Layer
    subgraph "Business Logic"
        direction TB
        UserService["User Service"]:::service
        AuthService["Auth Service"]:::service
        CategoryService["Category Service"]:::service
        PostService["Post Service"]:::service
        CommentService["Comment Service"]:::service
    end

    %% Security Module
    JWTService["JWT Authentication Service"]:::security

    %% Persistence Layer
    subgraph "Persistence Layer"
        direction TB
        SQLAlchemy["SQLAlchemy ORM"]:::persistence
        PostgreSQLDB[(PostgreSQL DB)]:::db
        UsersTable["users<br>categories<br>posts<br>comments"]:::db
    end

    %% Deployment / Infra
    subgraph "Deployment & Infra"
        direction TB
        ProcfileCmd["Procfile<br>(Uvicorn ASGI)"]:::infra
        EnvVars["Environment Variables (.env)"]:::infra
        Requirements["requirements.txt"]:::infra
        Runtime["runtime.txt"]:::infra
        Docs["README.md"]:::infra
    end

    %% Relationships
    Client -->|"HTTP Request"| FastAPIApp
    FastAPIApp --> UsersRouter
    FastAPIApp --> AuthRouter
    FastAPIApp --> CategoriesRouter
    FastAPIApp --> PostsRouter
    FastAPIApp --> CommentsRouter

    UsersRouter -->|"validate & delegate"| UserService
    AuthRouter -->|"validate & delegate"| AuthService
    CategoriesRouter -->|"validate & delegate"| CategoryService
    PostsRouter -->|"validate & delegate"| PostService
    CommentsRouter -->|"validate & delegate"| CommentService

    AuthRouter -->|"token issuance & validation"| JWTService
    JWTService --> AuthService

    UserService --> SQLAlchemy
    AuthService --> SQLAlchemy
    CategoryService --> SQLAlchemy
    PostService --> SQLAlchemy
    CommentService --> SQLAlchemy

    SQLAlchemy --> PostgreSQLDB
    PostgreSQLDB --> UsersTable

    ProcfileCmd --> FastAPIApp
    EnvVars --> FastAPIApp
    Requirements --> FastAPIApp
    Runtime --> FastAPIApp
    Docs --> FastAPIApp

    %% Click Events
    click FastAPIApp "https://github.com/melbanna3/blog-ai/blob/main/main.py"
    click ProcfileCmd "https://github.com/melbanna3/blog-ai/tree/main/Procfile"
    click EnvVars "https://github.com/melbanna3/blog-ai/blob/main/.env"
    click Requirements "https://github.com/melbanna3/blog-ai/blob/main/requirements.txt"
    click Runtime "https://github.com/melbanna3/blog-ai/blob/main/runtime.txt"
    click Docs "https://github.com/melbanna3/blog-ai/blob/main/README.md"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef api fill:#bbdefb,stroke:#1e88e5,stroke-width:1px
    classDef service fill:#ffe082,stroke:#ffa000,stroke-width:1px
    classDef persistence fill:#c8e6c9,stroke:#388e3c,stroke-width:1px
    classDef db fill:#a5d6a7,stroke:#2e7d32,stroke-width:1px
    classDef security fill:#ffccbc,stroke:#d84315,stroke-width:1px
    classDef infra fill:#e1bee7,stroke:#8e24aa,stroke-width:1px
```
