How beingmusthafa/bitweet-api works
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.