Project Documentation

🚀 1. Overview

Comprehensive Project Overview: SOB (Social Online Broadcast) Backend

Project Purpose

The SOB (Social Online Broadcast) backend is a scalable, real-time, and secure Node.js API designed to power a social media platform with multimedia sharing, user authentication, and live interaction capabilities. The system integrates Google OAuth for authentication, Cloudinary for media storage, MongoDB for data persistence, and Socket.IO for real-time communication, making it suitable for applications requiring instant updates (e.g., live chats, notifications, or streaming). The project emphasizes security (JWT, rate limiting, Helmet), performance (compression, CORS), and scalability (MongoDB, Mux for video processing).

The backend is structured to support a React-based frontend (as inferred from CLIENT_URL in .env.example), enabling features like:

• User authentication (JWT, OAuth, email/password)
• Media uploads (Cloudinary, Multer)
• Real-time interactions (Socket.IO)
• Email notifications (Nodemailer)
• Rate-limited API endpoints (express-rate-limit)
• Secure headers (Helmet)

Core Tech Stack

The backend leverages a modern JavaScript/TypeScript stack with the following key technologies:

Primary Problem Solved

The SOB backend addresses the challenges of building a modern social media platform by providing:

1. Unified Authentication System

   • Supports email/password, Google OAuth, and JWT-based sessions for seamless user onboarding.
   • Refresh tokens (JWT_REFRESH_EXPIRES=7d) ensure long-lived sessions without repeated logins.

2. Real-Time Engagement

   • Socket.IO enables features like live chats, notifications, and collaborative updates (e.g., comments, reactions) without polling.

3. Scalable Media Management

   • Cloudinary handles image/video uploads with CDN delivery, while Mux processes video streams for optimized playback.
   • Multer manages file uploads before offloading to Cloudinary.

4. Security & Compliance

   • Helmet secures HTTP headers (e.g., X-Frame-Options, Content-Security-Policy).
   • Rate limiting (express-rate-limit) prevents abuse (e.g., brute-force attacks).
   • Environment variables (.env.example) ensure secrets (e.g., JWT secrets, DB URIs) are never hardcoded.

5. Developer Experience

   • ESNext modules (jsconfig.json) enable modern JavaScript features.
   • Nodemon streamlines development with automatic server restarts.

Architectural Highlights

• Modular Design: The backend follows a MVC-like structure (routes, controllers, models) for maintainability.
• Event-Driven: Socket.IO facilitates real-time updates (e.g., new messages, friend requests).
• Cloud-Native: Cloudinary and Mux offload media processing to third-party services, reducing server load.
• Type Safety: While not explicitly using TypeScript, the jsconfig.json hints at potential future adoption.

Potential Use Cases

The SOB backend is ideal for:

• Social networks (e.g., Twitter/X-like microblogging with media).
• Live streaming platforms (via Mux integration).
• Collaborative apps (e.g., real-time document editing with chat).
• Community forums with user-generated content and notifications.

Key Observations

• No Frontend Code: The repository appears to be backend-only, suggesting a decoupled architecture where the frontend (likely React) consumes this API.
• Video Focus: The inclusion of Mux (@mux/mux-node) implies video upload/streaming capabilities, differentiating it from text/image-only platforms.
• Enterprise-Grade: Features like rate limiting, JWT refresh tokens, and Helmet indicate a production-ready system.

This backend is a robust foundation for a social platform requiring real-time interaction, media handling, and security.

📂 2. Project Structure

Codebase File Structure Analysis

The provided codebase appears to follow a modular architecture with separate folders for configuration, controllers, middlewares, models, routes, socket handling, and utilities.

Below is a detailed Markdown table categorizing the files and their key responsibilities:

Architectural Patterns

The codebase seems to follow a combination of the Model-View-Controller (MVC) and Model-View-Router (MVR) architectural patterns. Here's a breakdown of the patterns observed:

• MVC Pattern:
  • Model: Defined in src/models, these represent the data structures and schema for the database.
  • View: Although not explicitly defined, the views are likely handled by a frontend framework or separate repository, with the src/controllers acting as an intermediary for data processing and presentation logic.
  • Controller: Found in src/controllers, these handle requests, interact with models, and return responses to the client.
• MVR Pattern:
  • Model: Same as in the MVC pattern, defined in src/models.
  • View: Similar to the MVC pattern, the views are not explicitly defined but likely handled by a frontend framework or separate repository.
  • Router: Defined in src/routes, these handle the mapping of client requests to specific controller actions.

Additionally, the codebase exhibits elements of Onion Architecture (also known as Clean Architecture), with the following layers:

• Entities (Domain Model): Represented by the database models in src/models.
• Use Cases (Application Logic): Implemented in src/controllers and src/middlewares.
• Interface Adapters: Defined in src/routes and src/middlewares.
• Frameworks and Drivers: Utilized in src/config for database, cloudinary, and other service configurations.

Overall, the codebase employs a modular and layered architecture, combining elements of MVC, MVR, and Onion (Clean) Architecture to maintain separation of concerns and promote scalability.

🏗️ 3. Architecture & Data Flow

Deep-Dive Architecture Analysis: SOB Backend

1. Architecture Reasoning & Module Interactions

This repository represents a Node.js/Express.js backend for a social media application (SOB - "Social On Board"). The architecture follows a layered, modular design with clear separation of concerns, leveraging MVC (Model-View-Controller) and middleware-based request processing. Below is a detailed breakdown of the architectural layers, design patterns, and module interactions.

1.1. High-Level Architecture Overview

The system is structured into the following logical layers:

1.2. Core Design Patterns & Principles

1.2.1. Dependency Injection (DI) via Config Modules

• Pattern: Service Locator / DI Container
• Implementation:
  • Configuration files (cloudinary.js, db.js, nodemailer.js, etc.) act as singleton services that are imported and reused across the application.
  • Example:

    // src/config/cloudinary.js
    import { v2 as cloudinary } from 'cloudinary';
    import dotenv from 'dotenv';
    
    dotenv.config();
    
    const cloudinaryConfig = cloudinary.config({
      cloud_name: process.env.CLOUDINARY_CLOUD_NAME,
      api_key: process.env.CLOUDINARY_API_KEY,
      api_secret: process.env.CLOUDINARY_API_SECRET,
    });
    
    export default cloudinaryConfig;
    

  • Why?
    • Decouples configuration from business logic.
    • Centralizes third-party service initialization (Cloudinary, Mux, Nodemailer, etc.).
    • Easier to mock in tests.

1.2.2. Middleware Pipeline (Chain of Responsibility)

• Pattern: Middleware Chain
• Implementation:
  • Express.js middleware functions are composed in a pipeline where each middleware can:
    • Modify the request/response.
    • Short-circuit the request (e.g., auth failure).
    • Pass control to the next middleware.
  • Example:

    // src/app.js
    import express from 'express';
    import authMiddleware from './middlewares/auth.middleware.js';
    import postRoutes from './routes/post.routes.js';
    
    const app = express();
    
    app.use(express.json());
    app.use(authMiddleware.authenticate); // Auth middleware runs first
    app.use('/api/posts', postRoutes);     // Post routes run after auth
    

  • Key Middlewares:
    • auth.middleware.js: JWT validation & user attachment.
    • admin.middleware.js: Role-based access control.
    • upload.middleware.js: Multer-based file upload handling.
    • validate.middleware.js: Express-validator-based request validation.

1.2.3. Repository Pattern (Indirectly via Mongoose Models)

• Pattern: Repository
• Implementation:
  • Mongoose models (User.js, Post.js, etc.) act as repositories, abstracting database operations.
  • Example:

    // src/models/User.js
    import mongoose from 'mongoose';
    import bcrypt from 'bcrypt';
    
    const userSchema = new mongoose.Schema({
      email: { type: String, required: true, unique: true },
      password: { type: String, required: true },
      // ... other fields
    });
    
    userSchema.pre('save', async function (next) {
      if (!this.isModified('password')) return next();
      this.password = await bcrypt.hash(this.password, 10);
      next();
    });
    
    export default mongoose.model('User', userSchema);
    

  • Why?
    • Decouples business logic from database schema.
    • Provides a consistent interface for CRUD operations.

1.2.4. Strategy Pattern (Authentication Providers)

• Pattern: Strategy
• Implementation:
  • Multiple authentication strategies (Local, Google OAuth) are implemented as separate strategies and selected dynamically.
  • Example:

    // src/config/passport.js
    import { Strategy as GoogleStrategy } from 'passport-google-oauth20';
    import passport from 'passport';
    import User from '../models/User.js';
    
    passport.use(
      new GoogleStrategy(
        {
          clientID: process.env.GOOGLE_CLIENT_ID,
          clientSecret: process.env.GOOGLE_CLIENT_SECRET,
          callbackURL: process.env.GOOGLE_CALLBACK_URL,
        },
        async (accessToken, refreshToken, profile, done) => {
          // Strategy-specific logic (e.g., Google OAuth)
          const user = await User.findOne({ googleId: profile.id });
          if (user) return done(null, user);
          // ... create new user
        }
      )
    );
    

  • Why?
    • Allows extensibility (e.g., adding GitHub OAuth later).
    • Keeps authentication logic modular.

1.2.5. Observer Pattern (Real-Time Updates via Socket.IO)

• Pattern: Observer (Pub/Sub)
• Implementation:
  • socket.js sets up a WebSocket server that listens for events (e.g., new post, comment) and broadcasts updates to connected clients.
  • Example:

    // src/socket/socket.js
    import { Server } from 'socket.io';
    
    export const setupSocket = (server) => {
      const io = new Server(server, {
        cors: { origin: process.env.CLIENT_URL },
      });
    
      io.on('connection', (socket) => {
        console.log('New client connected:', socket.id);
    
        socket.on('joinRoom', (userId) => {
          socket.join(userId); // Join a room for the user
        });
    
        // Broadcast new post to followers
        socket.on('newPost', (post) => {
          io.to(post.authorId).emit('postCreated', post);
        });
      });
    };
    

  • Why?
    • Enables real-time features (notifications, live feeds).
    • Decouples real-time logic from HTTP controllers.

1.2.6. Decorator Pattern (API Response Wrappers)

• Pattern: Decorator
• Implementation:
  • apiResponse.js wraps API responses in a consistent format (success/error).
  • Example:

    // src/utils/apiResponse.js
    export const successResponse = (res, data, status = 200) => {
      res.status(status).json({
        success: true,
        data,
      });
    };
    
    export const errorResponse = (res, error, status = 400) => {
      res.status(status).json({
        success: false,
        message: error.message || 'Something went wrong',
      });
    };
    

  • Why?
    • Ensures consistent API responses across all endpoints.
    • Reduces boilerplate in controllers.

1.3. Module Interactions & Data Flow

1.3.1. Request Lifecycle

1. Request Ingress:
   • HTTP request enters via server.js → app.js → middleware pipeline.
2. Authentication & Authorization:
   • auth.middleware.js validates JWT (if present) and attaches the user to req.user.
   • admin.middleware.js checks roles (e.g., req.user.role === 'admin').
3. Validation:
   • validate.middleware.js uses express-validator to validate request bodies/params.
4. Controller Execution:
   • Route handler (e.g., post.controller.js) processes the request, interacts with models, and returns a response.
5. Response Egress:
   • Response is formatted via apiResponse.js and sent back to the client.
6. Real-Time Updates (Optional):
   • If the action triggers a real-time event (e.g., new post), socket.js broadcasts it to connected clients.

1.3.2. Key Interactions

1.4. Advanced Concerns

1.4.1. Security

• JWT Authentication:
  • Short-lived access tokens (15m) + long-lived refresh tokens (7d).
  • Refresh tokens are stored in HTTP-only cookies.
• Rate Limiting:
  • express-rate-limit protects against brute-force attacks.
• Helmet & CORS:
  • helmet sets secure HTTP headers.
  • CORS restricted to CLIENT_URL.
• Input Sanitization:
  • express-validator sanitizes user input to prevent XSS/SQLi.

1.4.2. Scalability

• Database:
  • MongoDB Atlas (scalable cloud DB).
• File Storage:
  • Cloudinary (scalable CDN for images/videos).
• Real-Time:
  • Socket.IO with Redis adapter (not shown, but implied for multi-server setups).

1.4.3. Error Handling

• Centralized Error Middleware:
  • Uncaught errors are caught and formatted via errorResponse.
• Mongoose Validation:
  • Schema-level validation (e.g., required, unique).

1.4.4. Environment Management

• .env.example:
  • Documents required environment variables.
• envValidator.js:
  • Validates .env at startup (not shown in file tree, but implied).

2. Data Flow & State Transitions

3. Mermaid.js Architecture Diagram

4. Summary of Key Takeaways

1. Modular & Layered Design:

   • Clear separation of concerns (config, models, controllers, routes, middlewares).
   • Follows MVC with additional real-time and utility layers.

2. Design Patterns:

   • Middleware Chain (Express.js).
   • Repository (Mongoose models).
   • Strategy (Authentication providers).
   • Observer (Socket.IO).
   • Decorator (API response wrappers).

3. Scalability & Security:

   • JWT + refresh tokens for auth.
   • Rate limiting, CORS, Helmet for security.
   • Cloudinary/Mux for scalable media handling.

4. Real-Time Capabilities:

   • Socket.IO for live updates (posts, notifications).

5. Extensibility:

   • Easy to add new routes, middlewares, or authentication strategies.

This architecture is well-structured for a social media backend, balancing modularity, scalability, and real-time functionality.

📈 System Architecture Diagram

🛠️ 4. Function Breakdowns

Analysis of Provided Source Files

The provided source files are mostly configuration files and do not contain actual code. However, we can still analyze the content of these files to understand the project structure and dependencies.

.env.example

This file contains environment variables used by the application. The following table summarizes the key variables:

jsconfig.json

This file contains configuration settings for JavaScript compilation. The following table summarizes the key settings:

package-lock.json

This file contains a snapshot of the dependencies and their versions used by the application. The following table summarizes the key dependencies: