Build a Scalable Instant Messaging Server from Scratch – IM1.0.0 Features Explained

Good News: IM1.0.0 Released

Private chat sending text/file

Sent/delivered/read receipts

LDAP login support

External authentication integration

Client jar package provided

GitHub link: github.com/yuanrw/IM

Preface

Instant messaging (IM) technology is used for chat (QQ, WeChat), live streaming, real‑time location sharing, multiplayer games, and any high‑real‑time scenario.

This article guides you from scratch to build a lightweight IM server that includes:

One‑to‑one text and file messaging

Sent/delivered/read receipts for each message

Offline message storage

User login, friend relationships and basic functions

Easy horizontal scalability

What You Will Learn

The project covers essential backend knowledge:

RPC communication

Database

Cache

Message queue

Distributed high‑concurrency architecture design

Docker deployment

Message Communication

Text Message

We start with the simplest feature: sending a normal message. The message format is:

message ChatMsg{
    id = 1; // message id
    fromId = Alice; // sender userId
    destId = Bob; // receiver userId
    msgBody = hello; // message body
}

Two users, Alice and Bob, connect to the server. When Alice sends message(hello), the server processes it.

Send Acknowledgement

To implement receipts we define an ACK message with three types: sent (already sent), delivered (delivered), and read (read).

message AckMsg {
    id; // message id
    fromId; // sender id
    destId; // receiver id
    msgType; // message type
    ackMsgId; // id of the confirmed message
}
enum MsgType {
    DELIVERED;
    READ;
}

When the server receives Alice’s message it sends a sent(hello) ACK to Alice.

message AckMsg {
    id = 2;
    fromId = Alice;
    destId = Bob;
    msgType = SENT;
    ackMsgId = 1;
}

The server then forwards delivered(hello) to Bob, and after Bob reads it, a read(hello) ACK is sent back.

message AckMsg {
    id = 3;
    fromId = Bob;
    destId = Alice;
    msgType = DELIVERED;
    ackMsgId = 1;
}

message AckMsg {
    id = 4;
    fromId = Bob;
    destId = Alice;
    msgType = READ;
    ackMsgId = 1;
}

Horizontal Scaling

When user count grows, multiple server instances are needed. We store which user is connected to which machine.

User Status Management

The user status module provides three interfaces:

public interface UserStatusService {
    // Store userId ↔ connectorId when user comes online
    String online(String userId, String connectorId);
    // User goes offline
    void offline(String userId);
    // Retrieve connectorId by userId
    String getConnectorId(String userId);
}

Redis is used to keep the user‑to‑connector mapping.

Message Forwarding

A transfer module forwards messages between different connector machines. The workflow:

Alice connects to machine [1] and registers online.

Alice sends a message to Bob; machine [1] checks if Bob is connected locally.

If not, it queries user status to get Bob’s connector (machine [2]) and forwards the message via transfer.

Offline Messages

If the recipient is offline, the message is persisted in MySQL and enqueued for later delivery when the user logs in.

User Login and Friend Relations

Registration, login, account management, and friend relationships are exposed as a RESTful HTTP service.

Overall Architecture

The final architecture consists of connector modules for long‑lived connections, a transfer module for inter‑machine routing, a user‑status service backed by Redis, offline storage in MySQL, and a RESTful API for user management.

Summary

Introduce user status for connection management and transfer for cross‑machine forwarding, enabling horizontal scaling.

Maintain long connections between each connector and the transfer module to achieve real‑time forwarding.