# beingmusthafa/bitweet-api architecture

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

- Interactive diagram: https://gitdiagram.com/beingmusthafa/bitweet-api
- Repository: https://github.com/beingmusthafa/bitweet-api

## Overview

##### Project Type and Purpose
- This is a monolithic backend API for a Twitter-clone application, built with FastAPI, exposing REST and WebSocket endpoints to support user authentication, tweeting, following, real-time notifications, and audio chat rooms. It also includes a Celery worker for asynchronous tasks (emails, push notifications, OTP).

##### File Structure Analysis
Top-Level Files
- Dockerfile / docker-compose.yml / .env* → Containerization and environment setup
- start.sh / dev.sh → Launch scripts for prod/dev
- requirements.txt / pyrightconfig.json → Dependencies and type checking

app/
- controllers/ → HTTP & WebSocket route handlers (auth, tweets, notifications, rooms, connections, users)
- services/ → Business logic layer, invoked by controllers (auth_service, tweet_service, notification_service, user_service, connections_service, websocket_manager)
- database/ → SQLAlchemy connection management & model definitions
- prisma/schema.prisma → Database schema definition (used to generate models)
- schemas/ → Pydantic schemas for request/response validation
- utils/ → Middleware (JWT auth, security), token/email helpers, notification utilities
- main.py → FastAPI app initialization, router registration, middleware configuration
- worker.py → Celery worker entry point

##### Key Architectural Insights from README
- Layers: Controllers → Services → Database
- Asynchronous tasks: Celery + Redis broker
- Real-time communication: WebSockets managed via Redis + FastAPI
- Persistence: PostgreSQL

a. Main Components
- API Application (FastAPI / Uvicorn)
- Celery Worker
- PostgreSQL Database
- Redis (as Celery broker & pub/sub for WebSocket events)
- External Clients (Web UI / Mobile)

b. Relationships & Data Flows
1. Clients send HTTP requests (REST) to FastAPI → Controllers invoke Services → Services read/write PostgreSQL via SQLAlchemy.
2. For authentication, controllers use utils/token_utils to generate/verify JWT.
3. When an action triggers a background job (e.g., send email, push notification), Service enqueues Celery task via Redis broker → Celery Worker picks up tasks and executes.
4. For real-time notifications and audio room events, controllers/WebSocket endpoints publish or subscribe via Redis pub/sub → FastAPI WebSocket manager pushes messages to connected clients.

c. Architectural Patterns & Principles
- Layered (Presentation → Controller → Service → Data)
- Asynchronous messaging (Celery tasks via Redis)
- Event‐driven real‐time updates (WebSocket + Redis pub/sub)
- Dependency injection via FastAPI for database sessions and settings
- Separation of concerns: controllers (API surface), services (business logic), utils (cross-cutting middleware)

d. Technologies & Frameworks
- FastAPI / Uvicorn (HTTP + WebSocket server)
- SQLAlchemy + Alembic (ORM + migrations)
- Pydantic (validation)
- Celery + Redis (task queue)
- PostgreSQL (relational data store)
- Docker / Docker-Compose (container orchestration)

##### Detail Level
- Major API domains (Auth, Tweets, Connections, Notifications, Rooms) as subcomponents or grouped under “Controllers.”
- How middleware (JWT, security) sits on the request path before controllers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Clients"
        UI["Web & Mobile Clients"]:::external
    end

    subgraph "Backend"
        direction TB
        API["FastAPI/Uvicorn App"]:::compute
        MWJWT["JWT Auth Middleware"]:::compute
        MWSec["Security Middleware"]:::compute

        subgraph "Controllers"
            direction TB
            AuthC["Auth Controller"]:::compute
            TweetC["Tweet Controller"]:::compute
            ConnC["Connections Controller"]:::compute
            NotifC["Notification Controller"]:::compute
            RoomC["Room Controller"]:::compute
            UserC["User Controller"]:::compute
        end

        subgraph "Services"
            direction TB
            AuthS["Auth Service"]:::compute
            TweetS["Tweet Service"]:::compute
            ConnS["Connections Service"]:::compute
            NotifS["Notification Service"]:::compute
            UserS["User Service"]:::compute
            WSMan["WebSocket Manager"]:::compute
        end

        Cel["Celery Worker"]:::compute
    end

    subgraph "Infrastructure"
        PG["PostgreSQL Database"]:::data
        REDIS["Redis (Broker & Pub/Sub)"]:::data
    end

    %% Flows
    UI -->|"HTTP/REST & WS"| API
    API --> MWJWT --> MWSec
    MWSec --> AuthC
    MWSec --> TweetC
    MWSec --> ConnC
    MWSec --> NotifC
    MWSec --> RoomC
    MWSec --> UserC

    AuthC --> AuthS
    TweetC --> TweetS
    ConnC --> ConnS
    NotifC --> NotifS
    RoomC --> WSMan
    UserC --> UserS

    AuthS --> PG
    TweetS --> PG
    ConnS --> PG
    NotifS --> PG
    UserS --> PG

    NotifS -->|"enqueue task"| REDIS
    AuthS -->|"enqueue task"| REDIS

    REDIS -->|"dequeue task"| Cel
    Cel --> PG

    WSMan -->|"publish/subscribe"| REDIS
    REDIS -->|"pub/sub events"| WSMan
    WSMan -->|"WS messages"| UI

    %% Click Events
    click API "https://github.com/beingmusthafa/bitweet-api/blob/main/app/main.py"
    click AuthC "https://github.com/beingmusthafa/bitweet-api/blob/main/app/controllers/auth_controller.py"
    click TweetC "https://github.com/beingmusthafa/bitweet-api/blob/main/app/controllers/tweet_controller.py"
    click ConnC "https://github.com/beingmusthafa/bitweet-api/blob/main/app/controllers/connections_controller.py"
    click NotifC "https://github.com/beingmusthafa/bitweet-api/blob/main/app/controllers/notification_controller.py"
    click RoomC "https://github.com/beingmusthafa/bitweet-api/blob/main/app/controllers/room_controller.py"
    click UserC "https://github.com/beingmusthafa/bitweet-api/blob/main/app/controllers/user_controller.py"
    click AuthS "https://github.com/beingmusthafa/bitweet-api/blob/main/app/services/auth_service.py"
    click TweetS "https://github.com/beingmusthafa/bitweet-api/blob/main/app/services/tweet_service.py"
    click ConnS "https://github.com/beingmusthafa/bitweet-api/blob/main/app/services/connections_service.py"
    click NotifS "https://github.com/beingmusthafa/bitweet-api/blob/main/app/services/notification_service.py"
    click UserS "https://github.com/beingmusthafa/bitweet-api/blob/main/app/services/user_service.py"
    click WSMan "https://github.com/beingmusthafa/bitweet-api/blob/main/app/services/websocket_manager.py"
    click Cel "https://github.com/beingmusthafa/bitweet-api/blob/main/app/worker.py"
    click PG "https://github.com/beingmusthafa/bitweet-api/blob/main/app/database/models.py"
    click REDIS "https://github.com/beingmusthafa/bitweet-api/blob/main/docker-compose.yml"

    %% Styles
    classDef compute fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef data fill:#FFA500,stroke:#000,stroke-width:1px
    classDef external fill:#90EE90,stroke:#000,stroke-width:1px
```
