Before Rubén Pérez (@anarthal) started writing code for the BoostServerTech Chat project, he had to figure out how everything would talk to everything else. The browser to the server. The server to Redis, MySQL, and an in-memory broadcast system. And so on.

Rubén is the author of Boost.MySQL and co-maintainer of Boost.Redis. He built this chat server as a case study in leveraging Boost libraries.

The first real design work had nothing to do with Boost. It was drawing the boundaries between systems and deciding what the messages between them look like.

There’s no C++ in this post, just the interface design that came first.

**App features**

Before diving into what the API should contain, we should first ask: “what do we want to support?”. There is a myriad of features that can be interesting, so we need to focus.

Ruben chose to start simple:

* Users can create their own accounts and login with a username and password.
* Users participate in group chats, called *rooms*. Rooms are currently static.

**Two protocols, one server**

Account creation and login are one-shot operations. The client sends a request and waits for a response. HTTP is fine for this.

Chat messages are different. When someone types something in a room, every connected client needs to see it right away. WebSockets give you a persistent connection where the server pushes data whenever it has something to say. So that’s what Rubén used.

The rule is simple: one-shot operations go over HTTP, real-time interaction goes over WebSocket.

The HTTP surface ended up tiny. Just two endpoints:

* `POST /api/create-account` for self-registration
* `POST /api/login` for authentication

Everything else goes through WebSocket.

**The WebSocket protocol**

A WebSocket is just a bidirectional pipe. You still need a message format. Rubén went with a simple envelope: every message is a JSON object with a `type` field and a `payload` field. Type tells you what it is, payload carries the data. One dispatch point on each side and easy to extend later.

**Connection: the hello event**

When a client opens a WebSocket connection, the server sends back a `hello` event. It contains everything the UI needs to render: the authenticated user, the room list, and recent message history for each room.

So there are no follow-up REST calls. The client connects once and has a fully populated screen. The tradeoff is a fat initial payload, but with a fixed set of rooms and a capped history window it stays manageable.

This is what a `hello` event looks like:

    {
      "type": "hello",
      "payload": {
        "me": { "id": 1, "username": "alice" },
        "rooms": [
          {
            "id": "beast",
            "name": "Boost.Beast",
            "messages": [
              {
                "id": "1697312400000-0",
                "content": "Has anyone tried the new...",
                "user": { "id": 2, "username": "bob" },
                "timestamp": 1697312400000
              }
            ],
            "hasMoreMessages": true
          }
        ]
      }
    }

**Broadcasting messages in real time**

`clientMessages`: sent by the client when the user hit send. Carries a room ID and an array of message objects (each just a `content` string). The array is there for extensibility, to allow batching.Currently, it’s always a single message.

`serverMessages`: the broadcast. When anyone sends a message, the server persists it, then pushes `serverMessages` to every connected client in that room, including the sender. Each message comes back with a server assigned ID, a timestamp, the content, and the sender's user info. The original sender uses this to confirm delivery.

**WebSocket: clientMessages (client to server)**

    {
      "type": "clientMessages",
      "payload": {
        "roomId": "beast",
        "messages": [
          { "content": "This is my message" }
        ]
      }
    }

**WebSocket: serverMessages (server to client)**

    {
      "type": "serverMessages",
      "payload": {
        "roomId": "beast",
        "messages": [
          {
            "id": "1697312500000-0",
            "content": "This is my message",
            "user": { "id": 1, "username": "alice" },
            "timestamp": 1697312500000
          }
        ]
      }
    }

**Room History**

The `hello` event contains only the most recent messages for each room, for efficiency reasons. Clients may request older messages with these messages:

`requestRoomHistory`: the user scrolled up past the messages loaded in `hello`. The client sends the room ID and the ID of the oldest message it has. The server responds with the next page of older messages. Cursor-based pagination basically.

`roomHistory`: the answer to `requestRoomHistory`. A batch of older messages plus a `hasMoreMessages` boolean so the client knows whether to keep paginating.

**WebSocket: requestRoomHistory (client to server)**

    {
      "type": "requestRoomHistory",
      "payload": {
        "roomId": "beast",
        "firstMessageId": "1697312400000-0"
      }
    }

**WebSocket: roomHistory (server to client)**

    {
      "type": "roomHistory",
      "payload": {
        "roomId": "beast",
        "messages": [ ... ],
        "hasMoreMessages": false
      }
    }

**The HTTP API**

The HTTP API handles authentication. Server-side, clients are authenticated with a session ID generated when the client authenticates using the `/api/login` endpoint and stored server-side. Client side, this session ID is stored in a cookie with the appropriate security attributes and sent to the server on subsequent requests.

Upon success, both `/api/create-account` and `/api/login` return a successful HTTP status and an empty response.  On error, they return a matching status and a JSON response with details to feed back to the end user.

**HTTP: Create Account Request**

    {
      "username": "alice",
      "email": "alice@example.com",
      "password": "hunter2"
    }

**HTTP: Login Request**

    {
      "email": "alice@example.com",
      "password": "hunter2"
    }

**HTTP: Error Response**

    {
      "id": "EMAIL_EXISTS",
      "message": "An account with this email already exists"
    }

**Behind the server: three backend systems**

The frontend contract is settled. Now how does the server actually fulfill it? Three systems, each owning one kind of data.

**MySQL owns users.** Account creation, credential lookups, resolving user IDs to usernames. If it’s about identity, it lives in MySQL. Messages don’t, at least not yet. Recall that MySQL is slower than Redis, but it provides the necessary ACID guarantees that identity management requires.

**Redis owns messages.** Each chat room is a [Redis stream](https://redis.io/docs/latest/develop/data-types/streams/), an append only log. When the server stores a message, Redis assigns a stream ID. That becomes the message ID the client sees (those `1697312400000-0` strings in the JSON above). Redis also handles session storage: session ID mapped to user ID, with a 7-day TTL. When the key expires, the session is gone. So no cleanup job is needed.

**An in-memory pub/sub system owns broadcast.** After a message is persisted to Redis, the server publishes it through a process-local data structure. Every WebSocket client subscribed to that room gets the event immediately. This isn’t Redis pub/sub. It’s entirely in-process. That’s a direct consequence of the single-threaded, single-connection Asio architecture: one process, one thread, so an in-memory structure is both fast and safe without locking. It also means the server only works as a single instance. Rubén accepted that constraint deliberately. Replacing it with something distributed is on the roadmap.

Here’s the message flow when someone hits send:

1. Client sends `clientMessages` over WebSocket
2. Server stores the messages in the room's Redis stream
3. Redis returns assigned IDs, server attaches timestamps
4. Server looks up the sender's username. This is already in memory at this point, so no database lookup is required.
5. Server publishes `serverMessages` through the in-memory pub/sub
6. Every connected client in that room gets the broadcast

And the login flow:

1. Client sends `POST /api/login`
2. Server finds the user by email in MySQL
3. Server checks the password hash (scrypt)
4. Server generates a 16 byte session ID, stores it in Redis with 7-day TTL
5. Server sends back a Set-Cookie (HttpOnly, SameSite=Strict)
6. The WebSocket connection later includes that cookie in the HTTP upgrade request

**Why split things this way**

You could put everything in one database. But the access patterns in this case are clearly different: user data is relational and looked up by email or ID, messages are append only and read by range, and broadcast is ephemeral. Matching each backend to its access pattern keeps things clean, and it means each layer can change independently. The plan to eventually offload old messages from Redis to MySQL for archival only touches the message layer. Nothing else moves.

**An open question**

Right now the room list is hardcoded. Four rooms, defined at compile time: "Boost.Beast", "Boost.Async", "Database connectors", "Web assembly". Rubén did this to keep early development focused on the messaging pipeline. But it’s the most obvious thing to change. If you were adding dynamic room creation to a system like this, where would rooms live? A MySQL table? Redis, next to the streams? Something else? If you have built this, what worked?

Full source:[ ](https://github.com/anarthal/servertech-chat)[github.com/anarthal/servertech-chat](http://github.com/anarthal/servertech-chat).

This is the second post in a series exploring the engineering decisions behind this project. The first, on the single-threaded Asio architecture, is[ here](https://www.reddit.com/r/cpp/comments/1to5dg2/what_happens_when_you_build_a_chat_server_on_one/).



How a Chat Server Talks to Everything: Designing the Interface Layer