Architecture Guide

Comprehensive overview of the Merge Conference platform structure, services, and dependencies

Project Overview

Merge Conference is a comprehensive multi-tenant video conferencing and instant messaging platform built with modern web technologies. It enables businesses to host HD video meetings with real-time collaboration tools (chat, whiteboard, screen sharing) and provides a WhatsApp-style messenger for business-scoped instant messaging.

Core Technologies

• Next.js 16 with React 19
• MongoDB for data persistence
• Socket.IO for real-time updates
• VideoSDK.live for video conferencing

Key Features

• Multi-tenant architecture with RBAC
• End-to-end calling with animations
• Real-time messaging & presence
• Audit trails & analytics

Frontend Architecture

📱Framework & Core

•Next.js 16 (App Router) with React 19
•TypeScript for type safety
•Tailwind CSS with custom design tokens
•shadcn/ui components for consistent design

🔄State Management & Data Fetching

•React hooks for local component state
•SWR for server state caching and synchronization
•Context API for global state (auth, socket, calls)
•LocalStorage for session token persistence

⚡Real-Time Communication

•Socket.IO client for real-time events
•Dual-token authentication (admin & messenger)
•Automatic reconnection with exponential backoff
•Business-level event isolation

✨UI/UX Features

•Framer Motion for smooth animations
•Dark/light mode with next-themes
•Arabic/English internationalization with RTL support
•Professional call modals with gradient backgrounds
•Responsive design for all screen sizes

📁Directory Structure

•/app - Next.js App Router pages and layouts
•/components - Reusable React components
•/lib - Utility functions, hooks, and contexts
•/public - Static assets (icons, sounds)
•/styles - Global CSS and Tailwind config

Backend Architecture

🛣️API Routes & Endpoints

•/api/admin/* - Admin authentication and management
•/api/messenger/* - Messaging, contacts, calls, conversations
•/api/meetings/* - Meeting lifecycle and in-meeting features
•/api/integrations/* - Third-party service integrations
•Organized by feature with clear separation of concerns

🔐Authentication & Authorization

•JWT-based authentication with separate token systems
•Admin users: JWT signed with JWT_SECRET
•Messenger users: JWT signed with MESSENGER_JWT_SECRET
•Role-Based Access Control (RBAC) with SYSTEM_SUPER_ADMIN, BUSINESS_ADMIN, SUPER_BUSINESS_ADMIN
•Server-side token validation on protected routes

🏢Multi-Tenancy & Data Isolation

•Business-level multi-tenancy
•All queries filtered by businessId for data privacy
•Separate messenger_users and users collections
•Messenger users treated as external contacts
•Cross-business isolation enforced at API level

🔌Real-Time Socket.IO Server

•Custom Socket.IO server integrated with Next.js
•Dual-token authentication during handshake
•User presence tracking and online status
•Message delivery and read receipt handling
•Typing indicators and real-time notifications
•Call signaling (initiate, answer, reject, end)

🗄️Database Design

•MongoDB Atlas for data persistence
•Collections: users, messenger_users, businesses, conversations
•Call records with full status tracking
•Audit logs for compliance and security
•Meeting records with participant tracking

External Services

VideoSDK.live

Core video conferencing platform

Features:

✓HD video and audio quality
✓Screen sharing and recording
✓Real-time room management
✓WebRTC-based peer-to-peer connections

VIDEOSDK_TOKEN

MongoDB Atlas

Cloud database for all application data

Features:

✓Scalable document storage
✓Flexible schema for various data types
✓Built-in authentication and encryption
✓Automatic backups and replication

MONGODB_URI

Vercel Blob Storage

Cloud storage for files and attachments

Features:

✓CDN-backed file storage
✓Automatic image optimization
✓Base64 fallback for small files
✓Secure token-based access

BLOB_READ_WRITE_TOKEN (optional)

Vercel Analytics

Application performance and usage analytics

Features:

✓Page view tracking
✓Event tracking
✓Performance metrics
✓User behavior insights

Built-in with @vercel/analytics

NPM Dependencies

UI & Styling

@radix-ui/*Accessible component primitives
tailwindcssUtility-first CSS framework
next-themesTheme management (dark/light)
lucide-reactIcon library
class-variance-authorityCSS class utilities
framer-motionAnimation library

Video & Real-Time Communication

@videosdk.live/react-sdkReact wrapper for VideoSDK
@videosdk.live/js-sdkCore VideoSDK library
socket.ioReal-time server (Node.js)
socket.io-clientSocket.IO client library
@dnd-kit/*Drag and drop library

Data & State Management

mongodbMongoDB driver for Node.js
swrData fetching with caching
react-day-pickerDate picker component
date-fnsDate utility functions

Security & Authentication

jsonwebtokenJWT creation and verification
bcryptjsPassword hashing and comparison
ua-parser-jsUser agent parsing

Development Tools

typescriptType checking for JavaScript
@types/*TypeScript type definitions
postcssCSS processing
tailwindcss-animateAnimation utilities

Key Architectural Decisions

Multi-Tenancy at Business Level

Each business is completely isolated with businessId filtering on all queries. This allows shared infrastructure while maintaining complete data privacy and separation.

Dual Authentication Systems

Separate JWT secrets for admin and messenger users. This provides different permission models - admin users manage the platform, while messenger users are external contacts for instant messaging.

Socket.IO for Real-Time Features

Custom Socket.IO server handles presence, messaging, read receipts, and call signaling. Provides true real-time experience with automatic reconnection and exponential backoff.

Separate User Collections

messenger_users vs users collections accommodate different lifecycles. Messenger users are external contacts, while admin users manage the platform.

Audit Trail & Compliance

Comprehensive logging of all user actions with extensive metadata. Critical for compliance, debugging, and understanding user behavior patterns.

Vercel Blob + Base64 Fallback

Primary storage via Vercel Blob with CDN integration. Base64 encoding for small files to reduce external API calls and improve performance.

Professional Call UI with Framer Motion

Smooth animations for call modals with color-coded differentiation between audio and video calls. Improved user experience with visual feedback and professional appearance.

Environment Configuration

Required Environment Variables

MONGODB_URI

MongoDB Atlas connection string for database access

VIDEOSDK_TOKEN

API token for VideoSDK.live conferencing service

JWT_SECRET

Secret key for signing admin user tokens

MESSENGER_JWT_SECRET

Secret key for signing messenger user tokens

NEXT_PUBLIC_APP_URL

Public URL of the application (accessible to frontend)

Optional Environment Variables

BLOB_READ_WRITE_TOKEN

Token for Vercel Blob storage (optional - enable file storage features)

Key Data Flows

User Authentication

User submits credentials on login page

Frontend sends POST to /api/*/auth/login

Backend validates credentials and hashes password

JWT token issued and stored in localStorage

Subsequent requests include token in Authorization header

Making a Video Call

Caller initiates call via messenger UI

Frontend creates call record via POST /api/messenger/calls

Backend creates VideoSDK room and returns roomId

Frontend emits call:initiate socket event to receiver

Receiver's browser receives call:incoming with caller details

Receiver accepts call, both join meeting room

Real-Time Messaging

User types message in chat UI

Frontend emits message:send socket event

Backend validates and stores in messenger_messages collection

Backend broadcasts message:received to conversation participants

Receivers update their UI with new message

Read receipt emitted when message is seen

User Presence Updates

User connects to socket (after authentication)

Backend updates user_presence collection

Backend broadcasts user:online to business room

All users in business receive presence update

UI updates online status indicators

📚 Understand the Architecture

Explore how the system is organized, from frontend frameworks to backend services, database design, and external integrations.

You're currently here reading the complete architectural overview.

⚙️ Developer Guide

Start building with practical API examples, request/response formats, Socket.IO events, and best practices.

View Developer Guide →

Architecture Guide

Comprehensive overview of the Merge Conference platform structure, services, and dependencies

Project Overview

Core Technologies

• Next.js 16 with React 19
• MongoDB for data persistence
• Socket.IO for real-time updates
• VideoSDK.live for video conferencing

Key Features

• Multi-tenant architecture with RBAC
• End-to-end calling with animations
• Real-time messaging & presence
• Audit trails & analytics

Frontend Architecture

📱Framework & Core

•Next.js 16 (App Router) with React 19
•TypeScript for type safety
•Tailwind CSS with custom design tokens
•shadcn/ui components for consistent design

🔄State Management & Data Fetching

•React hooks for local component state
•SWR for server state caching and synchronization
•Context API for global state (auth, socket, calls)
•LocalStorage for session token persistence

⚡Real-Time Communication

•Socket.IO client for real-time events
•Dual-token authentication (admin & messenger)
•Automatic reconnection with exponential backoff
•Business-level event isolation

✨UI/UX Features

•Framer Motion for smooth animations
•Dark/light mode with next-themes
•Arabic/English internationalization with RTL support
•Professional call modals with gradient backgrounds
•Responsive design for all screen sizes

📁Directory Structure

•/app - Next.js App Router pages and layouts
•/components - Reusable React components
•/lib - Utility functions, hooks, and contexts
•/public - Static assets (icons, sounds)
•/styles - Global CSS and Tailwind config

Backend Architecture

🛣️API Routes & Endpoints

•/api/admin/* - Admin authentication and management
•/api/messenger/* - Messaging, contacts, calls, conversations
•/api/meetings/* - Meeting lifecycle and in-meeting features
•/api/integrations/* - Third-party service integrations
•Organized by feature with clear separation of concerns

🔐Authentication & Authorization

•JWT-based authentication with separate token systems
•Admin users: JWT signed with JWT_SECRET
•Messenger users: JWT signed with MESSENGER_JWT_SECRET
•Role-Based Access Control (RBAC) with SYSTEM_SUPER_ADMIN, BUSINESS_ADMIN, SUPER_BUSINESS_ADMIN
•Server-side token validation on protected routes

🏢Multi-Tenancy & Data Isolation

•Business-level multi-tenancy
•All queries filtered by businessId for data privacy
•Separate messenger_users and users collections
•Messenger users treated as external contacts
•Cross-business isolation enforced at API level

🔌Real-Time Socket.IO Server

•Custom Socket.IO server integrated with Next.js
•Dual-token authentication during handshake
•User presence tracking and online status
•Message delivery and read receipt handling
•Typing indicators and real-time notifications
•Call signaling (initiate, answer, reject, end)

🗄️Database Design

•MongoDB Atlas for data persistence
•Collections: users, messenger_users, businesses, conversations
•Call records with full status tracking
•Audit logs for compliance and security
•Meeting records with participant tracking

External Services

VideoSDK.live

Core video conferencing platform

Features:

✓HD video and audio quality
✓Screen sharing and recording
✓Real-time room management
✓WebRTC-based peer-to-peer connections

VIDEOSDK_TOKEN

MongoDB Atlas

Cloud database for all application data

Features:

✓Scalable document storage
✓Flexible schema for various data types
✓Built-in authentication and encryption
✓Automatic backups and replication

MONGODB_URI

Vercel Blob Storage

Cloud storage for files and attachments

Features:

✓CDN-backed file storage
✓Automatic image optimization
✓Base64 fallback for small files
✓Secure token-based access

BLOB_READ_WRITE_TOKEN (optional)

Vercel Analytics

Application performance and usage analytics

Features:

✓Page view tracking
✓Event tracking
✓Performance metrics
✓User behavior insights

Built-in with @vercel/analytics

NPM Dependencies

UI & Styling

@radix-ui/*Accessible component primitives
tailwindcssUtility-first CSS framework
next-themesTheme management (dark/light)
lucide-reactIcon library
class-variance-authorityCSS class utilities
framer-motionAnimation library

Video & Real-Time Communication

@videosdk.live/react-sdkReact wrapper for VideoSDK
@videosdk.live/js-sdkCore VideoSDK library
socket.ioReal-time server (Node.js)
socket.io-clientSocket.IO client library
@dnd-kit/*Drag and drop library

Data & State Management

mongodbMongoDB driver for Node.js
swrData fetching with caching
react-day-pickerDate picker component
date-fnsDate utility functions

Security & Authentication

jsonwebtokenJWT creation and verification
bcryptjsPassword hashing and comparison
ua-parser-jsUser agent parsing

Development Tools

typescriptType checking for JavaScript
@types/*TypeScript type definitions
postcssCSS processing
tailwindcss-animateAnimation utilities

Key Architectural Decisions

Multi-Tenancy at Business Level

Each business is completely isolated with businessId filtering on all queries. This allows shared infrastructure while maintaining complete data privacy and separation.

Dual Authentication Systems

Separate JWT secrets for admin and messenger users. This provides different permission models - admin users manage the platform, while messenger users are external contacts for instant messaging.

Socket.IO for Real-Time Features

Custom Socket.IO server handles presence, messaging, read receipts, and call signaling. Provides true real-time experience with automatic reconnection and exponential backoff.

Separate User Collections

messenger_users vs users collections accommodate different lifecycles. Messenger users are external contacts, while admin users manage the platform.

Audit Trail & Compliance

Comprehensive logging of all user actions with extensive metadata. Critical for compliance, debugging, and understanding user behavior patterns.

Vercel Blob + Base64 Fallback

Primary storage via Vercel Blob with CDN integration. Base64 encoding for small files to reduce external API calls and improve performance.

Professional Call UI with Framer Motion

Smooth animations for call modals with color-coded differentiation between audio and video calls. Improved user experience with visual feedback and professional appearance.

Environment Configuration

Required Environment Variables

MONGODB_URI

MongoDB Atlas connection string for database access

VIDEOSDK_TOKEN

API token for VideoSDK.live conferencing service

JWT_SECRET

Secret key for signing admin user tokens

MESSENGER_JWT_SECRET

Secret key for signing messenger user tokens

NEXT_PUBLIC_APP_URL

Public URL of the application (accessible to frontend)

Optional Environment Variables

BLOB_READ_WRITE_TOKEN

Token for Vercel Blob storage (optional - enable file storage features)

Key Data Flows

User Authentication

User submits credentials on login page

Frontend sends POST to /api/*/auth/login

Backend validates credentials and hashes password

JWT token issued and stored in localStorage

Subsequent requests include token in Authorization header

Making a Video Call

Caller initiates call via messenger UI

Frontend creates call record via POST /api/messenger/calls

Backend creates VideoSDK room and returns roomId

Frontend emits call:initiate socket event to receiver

Receiver's browser receives call:incoming with caller details

Receiver accepts call, both join meeting room

Real-Time Messaging

User types message in chat UI

Frontend emits message:send socket event

Backend validates and stores in messenger_messages collection

Backend broadcasts message:received to conversation participants

Receivers update their UI with new message

Read receipt emitted when message is seen

User Presence Updates

User connects to socket (after authentication)

Backend updates user_presence collection

Backend broadcasts user:online to business room

All users in business receive presence update

UI updates online status indicators

📚 Understand the Architecture

Explore how the system is organized, from frontend frameworks to backend services, database design, and external integrations.

You're currently here reading the complete architectural overview.

⚙️ Developer Guide

Start building with practical API examples, request/response formats, Socket.IO events, and best practices.

View Developer Guide →