# yogeshgit11/socialhub-api architecture

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

- Interactive diagram: https://gitdiagram.com/yogeshgit11/socialhub-api
- Repository: https://github.com/yogeshgit11/socialhub-api

## Overview

##### Project type and purpose
- This is a backend-only FastAPI service (“SocialHub API”) for a social media platform.
- It handles user authentication, CRUD operations for posts, follows, likes, comments, and real-time notifications.

##### File structure
- Top-level: only `.gitignore` and `README.md` are present, which confirms this is purely the API component.
- No separate “frontend” or “microservice” folders—this is a single monolithic service, likely organized under a `src/` or `app/` directory in the future.

##### Key insights from the README
- Core features: user auth, posts, follows, likes, comments, real-time notifications.
- Technology: FastAPI (Python), so uvicorn or similar ASGI server at runtime.
- Notifications hint at a WebSocket or pub/sub component (e.g., Redis).

##### Main components
a. API Server
- FastAPI application served by an ASGI server (uvicorn or hypercorn).
- Endpoints grouped by domain: /auth, /users, /posts, /follows, /likes, /comments, /notifications.
b. Authentication
- JWT tokens or OAuth2 mechanism implemented in FastAPI dependencies.
c. Database
- Relational DB (PostgreSQL, MySQL, etc.) storing users, posts, relationships, comments, likes.
d. Cache / Message Broker
- Redis for caching hot data (e.g., user sessions, feed caching) and for pub/sub to drive real-time notifications.
e. Real-time Notification Engine
- WebSocket manager within FastAPI or a separate microservice subscribing to Redis channels, pushing events to connected clients.
f. External Services (optional, if in scope)
- Email/SMS provider for password resets or notifications.
- Object storage (S3 or similar) for media uploads.

##### Relationships and data flows
- Client (mobile/web) → HTTPS request → ASGI server → FastAPI routers → business logic → Database or Redis → response back to client.
- Upon comment/like/follow event → FastAPI publishes event to Redis channel → Notification Engine subscribes → pushes WebSocket message to the target user’s open socket.
- Auth middleware intercepts requests, validates JWT against secret or token store in Redis/DB.

##### Architectural patterns and principles
- Layered architecture:
- Presentation/API layer (FastAPI routers)
- Service/business layer (use-case functions)
- Persistence layer (ORM or raw SQL)
- Separation of concerns: authentication, data access, notification logic.
- Pub/Sub pattern for decoupling real-time events from core API.
- Horizontal scalability: multiple FastAPI worker processes behind a load balancer, a Redis cluster, and a managed database.

##### Technologies, frameworks, and libraries
- Python 3.x, FastAPI, Pydantic for models, SQLAlchemy or Tortoise ORM, uvicorn.
- Redis (for cache and pub/sub), PostgreSQL.
- WebSocket support via FastAPI’s `WebSocket` routes.
- Optional: Celery or RQ for background tasks (e.g., sending emails).

##### Elements
- Client → API → DB/Redis
- API → Redis pub/sub → Notification Engine → Client WebSocket

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client["Client (Web/Mobile)"]:::external

    %% Load Balancer / ASGI Server
    Client -->|HTTP/HTTPS| LB["Load Balancer"]:::infra
    LB -->|forwards request| ASGI["ASGI Server\n(uvicorn)"]:::api

    %% API Layer
    ASGI --> FastAPIApp["FastAPI Application"]:::api

    subgraph "API Layer"
        direction TB
        AuthRouter["/auth Router"]:::api
        UserRouter["/users Router"]:::api
        PostsRouter["/posts Router"]:::api
        FollowsRouter["/follows Router"]:::api
        LikesRouter["/likes Router"]:::api
        CommentsRouter["/comments Router"]:::api
        NotifRouter["/notifications Router"]:::api
    end

    FastAPIApp --> AuthRouter
    FastAPIApp --> UserRouter
    FastAPIApp --> PostsRouter
    FastAPIApp --> FollowsRouter
    FastAPIApp --> LikesRouter
    FastAPIApp --> CommentsRouter
    FastAPIApp --> NotifRouter

    %% Persistence Layer
    DB["Relational DB\n(PostgreSQL)"]:::persistence
    Cache["Redis\n(Cache & Pub/Sub)"]:::persistence

    AuthRouter -->|Validate credentials / Issue JWT| DB
    AuthRouter -->|Token store / blacklisting| Cache

    UserRouter -->|CRUD users| DB
    PostsRouter -->|CRUD posts| DB
    PostsRouter -->|cache feed| Cache
    FollowsRouter -->|manage follows| DB
    LikesRouter -->|manage likes| DB
    CommentsRouter -->|manage comments| DB

    NotifRouter -->|subscribe events| Cache

    %% Real-time Notification Engine
    Cache -->|PUBLISH on 'notifications'| NotificationEngine["Notification Engine\n(WebSocket Manager)"]:::realtime
    NotificationEngine -->|WebSocket push| Client

    %% External Services
    EmailService["Email/SMS Provider"]:::external
    ObjectStorage["Object Storage\n(S3)"]:::external

    AuthRouter -->|Send reset email| EmailService
    PostsRouter -->|Upload media| ObjectStorage

    %% Styles
    classDef api fill:#E3F2FD,stroke:#2196F3,stroke-width:2px
    classDef persistence fill:#E8F5E9,stroke:#4CAF50,stroke-width:2px
    classDef realtime fill:#FFF3E0,stroke:#FF9800,stroke-width:2px
    classDef external fill:#F3E5F5,stroke:#9C27B0,stroke-width:2px
    classDef infra fill:#ECEFF1,stroke:#607D8B,stroke-width:2px
```
