Architecture Overview

This article provides a comprehensive overview of the messaging system's architecture, including all major components and how they interact.

Component Architecture

Detailed Component Interaction

        
    graph TB
        subgraph Client["Client Layer"]
            Browser["Web Browser"]
            SocketClient["Socket.IO Client"]
        end
        subgraph Reverse["Edge Layer"]
            Nginx["Nginx Reverse Proxy"]
        end
        subgraph API["API Layer"]
            Backend["Backend Server (Golang)"]
            Socket["Socket Server 1 (Socket.IO)"]
            Socket2["Socket Server N (Socket.IO)"]
        end
        subgraph Queue["Message Queue"]
            RabbitMQ["RabbitMQ (AMQP)"]
        end
        subgraph Workers["Worker Layer"]
            ChatWorker["Chat Worker (Message Processor)"]
        end
        subgraph State["State Layer"]
            Memcached["Memcached (User Sessions)"]
        end
        subgraph Database["Data Layer"]
            PostgreSQL["PostgreSQL (Persistent Storage)"]
        end
        Browser -->|HTTP| Nginx
        SocketClient -->|WebSocket| Nginx
        Nginx -->|HTTP| Backend
        Nginx -->|WebSocket| Socket
        Nginx -->|WebSocket| Socket2
        Backend <-->|TCP| PostgreSQL
        Socket <-->|AMQP| RabbitMQ
        Socket2 <-->|AMQP| RabbitMQ
        ChatWorker <-->|AMQP| RabbitMQ
        StatusWorker <-->|AMQP| RabbitMQ
        ChatWorker <-->|TCP| PostgreSQL
        Socket <-->|GET/SET/DEL| Memcached
        Socket2 <-->|GET/SET/DEL| Memcached
        Backend <-->|GET/SET/DEL| Memcached

Service Responsibilities

Backend API

Authentication: User login, registration, JWT token generation
User Management: Profile updates, contacts management
Group Operations: Create groups, add/remove members, manage channels
Messaging Operations: Handle message sending and read receipt updates via HTTP
- Forwards personal and group messages to RabbitMQ
- Forwards message status updates to RabbitMQ
- Handle new channels and joining groups
REST Endpoints: All stateless operations that don't require real-time communication
Database Interface: Direct access to PostgreSQL for data persistence
RabbitMQ Publisher: Publishes message events to queue for processing

Socket Server

WebSocket Connections: Manages client connections via Socket.IO
Real-time Event Delivery: Receives events from workers via RabbitMQ and forwards to connected clients
Presence Tracking: Typing indicators and online/offline status
Room Management: Handles Socket.IO rooms for group chats and subscription management

Chat Worker

Message Consumer: Subscribes to RabbitMQ message queues for incoming events from API
Database Persistence: Saves messages and updates to PostgreSQL
Read Receipt Processing: Updates message_recipients with delivery status
Event Publishing: Sends processed events back to RabbitMQ for socket server distribution

Data Flow Patterns

Real-time Message Flow

Message Processing Flow

        
sequenceDiagram
    participant Client as Client A
    participant API as Backend API
    participant RabbitMQ as RabbitMQ
    participant Worker as Chat Worker
    participant DB as PostgreSQL
    participant Socket as Socket Server
    participant Client2 as Client B
    Client->>Client: Create temp message (in memory)
    Client->>API: HTTP POST /api/messages/send/personal
    API->>RabbitMQ: Publish "personal.message" event
    API-->>Client: Return 200 OK
    RabbitMQ->>Worker: Dequeue "personal.message" event
    Worker->>DB: Insert message + message_recipients (status=SENT)
    Worker->>RabbitMQ: Publish "personal.message.persisted" event (status=SENT)
    RabbitMQ->>Socket: Route to recipient's user ID
    Socket-->>Client: Notify "sent" via socket
    Client->>Client: Replace temp message with actual message (Single tick)
    Socket->>Client2: Forward message to recipient
    Client2->>API: HTTP POST /api/messages/status/delivered
    API->>RabbitMQ: Publish "personal.delivered" event
    API-->>Client2: Return 200 OK
    RabbitMQ->>Worker: Dequeue "personal.delivered" event
    Worker->>DB: Update message_recipient.status = DELIVERED
    Worker->>RabbitMQ: Publish "personal.delivered" event (for sender)
    RabbitMQ->>Socket: Route to sender
    Socket-->>Client: Notify "delivered" via socket
    Client->>Client: Update message status "delivered" (Double tick)
    Client2->>API: HTTP POST /api/messages/status/read
    API->>RabbitMQ: Publish "personal.read" event
    RabbitMQ->>Worker: Dequeue "personal.read" event
    Worker->>DB: Update message_recipient.status = READ
    Worker->>RabbitMQ: Publish "personal.read" event (for sender)
    RabbitMQ->>Socket: Route to sender
    Socket-->>Client: Notify "read" via socket
    Client->>Client: Update message status "read" (Blue tick)

Group Message Flow (Channel-Based Routing)

Group Message Flow

        
sequenceDiagram
    participant ClientA as Client A (Server 1)
    participant API as Backend API
    participant RabbitMQ as RabbitMQ
    participant Worker as Chat Worker
    participant DB as PostgreSQL
    participant Socket1 as Socket Server 1
    participant Socket2 as Socket Server 2
    participant ClientB as Client B (Server 2)
    ClientA->>ClientA: Create temp message (in memory)
    ClientA->>API: HTTP POST /api/messages/send/group
    API->>RabbitMQ: Publish "group.message" event
    API-->>ClientA: Return 200 OK
    RabbitMQ->>Worker: Dequeue "group.message" event
    Worker->>DB: Insert message + message_recipients (status=SENT)
    Worker->>RabbitMQ: Publish to "group.outgoing.message" (routing key = channel:X)
    RabbitMQ->>Socket1: Route if binding exists
    RabbitMQ->>Socket2: Route if binding exists
    Socket1->>Socket1: Emit to Socket.IO room
    Socket1-->>ClientA: MESSAGE_SENT
    Socket1->>ClientA: MESSAGE_RECEIVE
    Socket2->>Socket2: Emit to Socket.IO room
    Socket2->>ClientB: MESSAGE_RECEIVE

Presence Update Flow

Online/Offline Status Flow

        
sequenceDiagram
    participant Client as User A Client
    participant ClientB as User B Client
    participant Socket as Socket Server 1
    participant SocketB as Socket Server 2
    participant Memcached as Memcached
    participant RabbitMQ as RabbitMQ
    Client->>Socket: Connect (websocket)
    Socket->>Memcached: SET user:1:online
    Memcached->>Memcached: user:1:online (ttl=60 seconds)
    Memcached-->>Socket: OK
    Client-->>Socket: Ping (every 25 seconds)
    Socket->>Socket: Accumulate pings from all users for 5 seconds
    Socket-->>Memcached: Bulk refresh TTL
    Client->>Socket: Fetch online status userIds:2,3,4 (every 12 seconds)
    Socket->>Memcached: GET user:2:online ...
    Socket-->>Client: userId: 2=offline, 3=offline, 4=offline
    ClientB->>SocketB: Connect (websocket)
    SocketB->>Memcached: SET user:2:online
    Memcached->>Memcached: user:1:online, user:2:online (ttl=60 seconds)
    Memcached-->>SocketB: OK
    Client->>Socket: Fetch online status userIds:2,3,4 (every 12 seconds)
    Socket->>Memcached: GET user:2:online ...
    Socket-->>Client: userId: 2=online, 3=offline, 4=offline
    Client->>Client: Show User B (userId=2) as online

Scalability Features

Horizontal Scaling with Multiple Socket Servers

The system supports running multiple Socket.IO instances:

# Docker Compose configuration
socket_server_1:
  environment:
    SERVER_ID: server-1
    RABBITMQ_HOST: rabbitmq
    MEMCACHED_HOST: memcached

socket_server_2:
  environment:
    SERVER_ID: server-2
    RABBITMQ_HOST: rabbitmq
    MEMCACHED_HOST: memcached

Key Benefits:

Load balancing across servers (Nginx reverse proxy)
Message routing via RabbitMQ (all servers receive events)
Shared session state in Memcached (consistent presence across servers)
Workers process queued events asynchronously

RabbitMQ Message Queue Pattern

// Socket server publishes to RabbitMQ
await rabbitMQ.publishEvent('messages', {
  type: 'message:sent',
  payload: {
    messageId: msg.id,
    channelId: msg.channel_id,
    senderId: msg.sender_id,
    content: msg.content,
  },
})

// Chat worker consumes from RabbitMQ
consumer.subscribe('messages', async event => {
  if (event.type === 'message:sent') {
    await messageRepository.save(event.payload)
    await messageRecipientRepository.createForChannel(event.payload)
  }
})

This decouples the real-time layer (Socket) from the persistence layer (Worker).

Communication Protocols

Client to Server

REST API: HTTP/HTTPS for stateless operations
- Authentication
- User profile updates
- Group management
- Contact management
WebSocket: WSS (Secure WebSocket) for real-time events
- Messages
- Typing indicators
- Read receipts
- Presence status

Server to Server

RabbitMQ (AMQP): Asynchronous event distribution
- Message events
- Status events
TCP: Direct database connections
- Data persistence
- Query operations
Memcached Protocol: Binary cache protocol
- Session storage
- Status lookups

Database Connection Pattern

// TypeORM manages database connections
const dataSource = new DataSource({
  type: 'postgres',
  host: process.env.DB_HOST,
  port: 5432,
  username: process.env.DB_USERNAME,
  password: process.env.DB_PASSWORD,
  database: process.env.DB_NAME,
  entities: [User, Message, MessageRecipient, Chat, ...],
  logging: true
})

// Used by Backend API
app.get('/api/chats/:chatId', async (req, res) => {
  const messages = await dataSource.getRepository(Message).find({
    where: { chat_id: req.params.chatId }
  })
})

// Used by Chat Worker
consumer.subscribe('messages', async (event) => {
  await dataSource.getRepository(Message).save(event.payload)
})