Distributed Real-Time Chat Platform

A production-oriented distributed real-time messaging platform built with TypeScript, WebSockets, Kafka, Redis, PostgreSQL, and Docker.

A microservices-based chat platform designed to explore the engineering challenges behind low-latency communication, event-driven architecture, horizontal scalability, and distributed system reliability.

🚀 Overview

The platform separates authentication, real-time connections, message processing, and notifications into independently deployable services.

The architecture uses:

WebSockets for real-time communication
Apache Kafka for asynchronous event streaming
Redis for low-latency state and caching
PostgreSQL for persistent data
Docker Compose for local infrastructure
TypeScript for type-safe service development

🏗️ Architecture

                         ┌──────────────────┐
                         │      Client      │
                         └────────┬─────────┘
                                  │
                            WebSocket / HTTP
                                  │
                         ┌────────▼─────────┐
                         │ WebSocket Gateway│
                         │      :4000       │
                         └────────┬─────────┘
                                  │
                    ┌─────────────┼─────────────┐
                    │             │             │
                    ▼             ▼             ▼
             ┌────────────┐ ┌────────────┐ ┌──────────────┐
             │    Auth    │ │   Message  │ │ Notification │
             │   :4001    │ │   :4002    │ │    :4003     │
             └─────┬──────┘ └──────┬─────┘ └──────┬───────┘
                   │               │              │
                   └───────────────┼──────────────┘
                                   │
                         ┌─────────▼─────────┐
                         │       Kafka       │
                         │  Event Streaming  │
                         └─────────┬─────────┘
                                   │
                         ┌─────────▼─────────┐
                         │      Redis        │
                         │ Cache / State     │
                         └───────────────────┘
                                   │
                         ┌─────────▼─────────┐
                         │    PostgreSQL     │
                         │ Persistent Data   │
                         └───────────────────┘

🧩 Services

Service	Port	Responsibility
WebSocket Gateway	`4000`	Maintains real-time client connections and routes events
Auth Service	`4001`	Authentication, authorization, and identity management
Message Service	`4002`	Message processing, persistence, and event publishing
Notification Service	`4003`	Asynchronous notification processing

🛠️ Tech Stack

Backend

Node.js
TypeScript
WebSockets

Distributed Systems

Apache Kafka
Redis

Database

PostgreSQL

Infrastructure

Docker
Docker Compose
npm Workspaces

Observability

Structured JSON logging
Service health endpoints

📁 Project Structure

distributed-real-time-chat-platform/
│
├── apps/
│   ├── gateway/
│   │   └── ...
│   ├── auth/
│   │   └── ...
│   ├── message/
│   │   └── ...
│   └── notification/
│       └── ...
│
├── packages/
│   └── shared/
│       └── ...
│
├── docker-compose.yml
├── package.json
├── package-lock.json
└── README.md

⚡ Getting Started

Prerequisites

Make sure you have the following installed:

Node.js
npm
Docker
Docker Compose

1. Clone the repository

git clone <repository-url>
cd distributed-real-time-chat-platform

2. Install dependencies

npm install

3. Start the complete environment

npm run compose:up

This starts:

PostgreSQL
Redis
Kafka
WebSocket Gateway
Auth Service
Message Service
Notification Service

🔍 Health Checks

Every service exposes a /health endpoint.

Service	Endpoint
WebSocket Gateway	`http://localhost:4000/health`
Auth	`http://localhost:4001/health`
Message	`http://localhost:4002/health`
Notification	`http://localhost:4003/health`

Example:

curl http://localhost:4000/health

Expected response:

{
  "status": "ok"
}

🧪 Development

Run individual services locally:

npm run dev:gateway

npm run dev:auth

npm run dev:message

npm run dev:notification

Run TypeScript type checking:

npm run typecheck

Start the Docker environment:

npm run compose:up

🔄 Message Flow

A typical message flow through the platform is:

Client
  │
  │ WebSocket
  ▼
WebSocket Gateway
  │
  │ Publish Message Event
  ▼
Kafka
  │
  ├──────────────────────┐
  │                      │
  ▼                      ▼
Message Service    Notification Service
  │                      │
  ▼                      ▼
PostgreSQL           Notification

The gateway handles persistent client connections while Kafka decouples message processing from downstream consumers.

This allows message processing and notification workloads to scale independently.

⚙️ Distributed System Design

WebSockets

Persistent WebSocket connections provide low-latency bidirectional communication between clients and the gateway.

Kafka

Kafka acts as the event backbone between services.

It provides:

Asynchronous processing
Service decoupling
Event replay
Consumer groups
Traffic buffering

Redis

Redis is intended for latency-sensitive and ephemeral data such as:

User presence
Connection metadata
Caching
Distributed state

PostgreSQL

PostgreSQL provides durable persistence for authoritative application data such as:

Users
Conversations
Messages
Message metadata

📊 Current Status

Phase 0 — Infrastructure & Service Scaffold

Phase 1 — Authentication & Users

Phase 2 — Real-Time Messaging

Phase 3 — Event-Driven Architecture

Phase 4 — Distributed State

Phase 5 — Reliability & Observability

Phase 6 — Production Deployment

🎯 Engineering Goals

The project focuses on understanding the practical engineering problems involved in building distributed real-time systems.

1. Low-Latency Communication

Use persistent WebSocket connections to minimize communication overhead and provide real-time message delivery.

2. Service Isolation

Authentication, messaging, notifications, and connection management remain separate services with clear responsibilities.

3. Asynchronous Processing

Kafka decouples producers and consumers, allowing downstream workloads to process events independently.

4. Fast Ephemeral State

Redis provides a low-latency storage layer for presence, caching, and distributed connection state.

5. Durable Persistence

PostgreSQL acts as the persistent source of truth for application data.

6. Horizontal Scalability

Services are designed so multiple instances can run concurrently as system traffic increases.

🗺️ Roadmap

Phase 0
Infrastructure & Scaffolding
        │
        ▼
Phase 1
Authentication & Users
        │
        ▼
Phase 2
Real-Time Messaging
        │
        ▼
Phase 3
Kafka Event Architecture
        │
        ▼
Phase 4
Redis Presence & Horizontal Scaling
        │
        ▼
Phase 5
Observability & Reliability
        │
        ▼
Phase 6
Load Testing & Production Deployment

📌 Project Philosophy

The goal is to understand how real-time systems behave when traffic increases, services fail, messages are duplicated, and individual components need to scale independently.

The architecture therefore prioritizes:

Reliability
     ↓
Consistency
     ↓
Scalability
     ↓
Observability
     ↓
Performance

Complexity is introduced only when it solves a measurable engineering problem.

📄 License

This project is currently intended as an engineering and learning project.

Name		Name	Last commit message	Last commit date
apps/web		apps/web
docs		docs
packages		packages
services		services
.gitignore		.gitignore
Dockerfile.service		Dockerfile.service
README.md		README.md
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json
tsconfig.base.json		tsconfig.base.json
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation