A horizontally scalable, real-time document collaboration engine built with Python, FastAPI, and WebSockets. This project demonstrates advanced distributed system design by handling concurrent text edits across multiple server nodes using a custom Operational Transformation (OT) algorithm and a Redis Pub/Sub message broker.
Unlike standard WebSocket chat apps that run on a single server, this architecture is designed to sit behind a Load Balancer. It utilizes a centralized message broker to route real-time operations between independent backend nodes.
- Frontend: Vanilla JavaScript and Tailwind CSS. Calculates character-level deltas (Insert/Delete) based on cursor position.
- Backend Nodes: FastAPI & WebSockets. Maintains the Authoritative Master State in memory.
- Message Broker: Redis Pub/Sub. Routes keystroke payloads across the server cluster in milliseconds.
- Orchestration: Docker & Docker Compose. Spins up the entire microservice matrix (Redis + multiple API nodes) locally.
During development, several critical concurrency and network challenges were solved:
- The "Last-Write-Wins" Flaw: Implemented Operational Transformation (OT) logic so the server processes exact string splices (
{action: "insert", char: "A", position: 14}) instead of blindly overwriting the document. - Split-Brain Memory Desync: Fixed state divergence across multiple nodes by forcing every server to listen to the Redis channel and apply peer operations to their local
DocumentStorememory. - Memory Address Collisions: Replaced default CPython object ID tracking with Cryptographic UUIDs to prevent dropped packets when identical memory addresses were generated across different container instances.
- Docker DNS Race Conditions: Implemented asynchronous exponential backoff (Retry Loops) during server boot-up to prevent FastAPI from crashing before the Redis container finished propagating its DNS inside the Docker network.
You can boot up the entire distributed cluster using Docker Compose.
# Clone the repository
git clone https://github.com/g75tsnhg4y-star/realtime-collab-engine.git
cd realtime-collab-engine
# Boot the Redis broker and two independent FastAPI nodes
docker-compose up --build