Realtime Collaboration

· 10 min read

Building a real-time collaborative code editor with WebSockets, operational transformation, and presence awareness.

Why Real-Time Collaboration?

Modern developers expect Google Docs-style collaboration in their code editors. Multiple cursors, live edits, and instant feedback create a seamless team experience.

We built a VS Code-like editor that supports:

  • Real-time editing - See changes as teammates type
  • Presence indicators - Know who’s viewing what
  • Conflict resolution - Automatic merge of concurrent edits
  • Offline support - Work disconnected, sync later

Architecture Overview

Components

┌─────────────┐     WebSocket      ┌─────────────┐
│   Client A  │◄──────────────────►│             │
└─────────────┘                    │   Server    │
                                   │   (Node.js) │
┌─────────────┐     WebSocket      │             │
│   Client B  │◄──────────────────►│             │
└─────────────┘                    └─────────────┘
                                          │
                                          ▼
                                   ┌─────────────┐
                                   │   Redis     │
                                   │   (PubSub)  │
                                   └─────────────┘

Technology Stack

  • Frontend: React + Monaco Editor
  • Backend: Node.js + Socket.IO
  • Sync: Operational Transformation (OT)
  • Storage: PostgreSQL + Redis
  • Hosting: AWS ECS + ALB

The Document Model

Every document needs a consistent representation:

class Document {
  constructor(id, content = '') {
    this.id = id
    this.content = content
    this.version = 0
    this.history = [] // Operation history
  }

  apply(operation) {
    this.content = operation.apply(this.content)
    this.version++
    this.history.push(operation)
  }

  getText() {
    return this.content
  }
}

Operational Transformation

OT is the algorithm that resolves concurrent edits. When two users edit simultaneously, their operations must be transformed to maintain consistency.

Operation Types

class Operation {
  constructor(type, position, data) {
    this.type = type // 'insert' or 'delete'
    this.position = position
    this.data = data
    this.version = 0 // Document version when created
  }
}

class InsertOperation extends Operation {
  constructor(position, text) {
    super('insert', position, text)
  }

  apply(content) {
    return content.slice(0, this.position) +
           this.data +
           content.slice(this.position)
  }
}

class DeleteOperation extends Operation {
  constructor(position, length) {
    super('delete', position, length)
  }

  apply(content) {
    return content.slice(0, this.position) +
           content.slice(this.position + this.data)
  }
}

Transform Function

The heart of OT - transforming operations:

function transform(op1, op2) {
  if (op1.type === 'insert' && op2.type === 'insert') {
    if (op1.position < op2.position) {
      return [op1, new InsertOperation(
        op2.position + op1.data.length,
        op2.data
      )]
    } else if (op1.position > op2.position) {
      return [new InsertOperation(
        op1.position + op2.data.length,
        op1.data
      ), op2]
    } else {
      // Same position - use replica ID to break tie
      if (op1.replicaId < op2.replicaId) {
        return [op1, new InsertOperation(
          op2.position + op1.data.length,
          op2.data
        )]
      } else {
        return [new InsertOperation(
          op1.position + op2.data.length,
          op1.data
        ), op2]
      }
    }
  }

  if (op1.type === 'insert' && op2.type === 'delete') {
    if (op1.position <= op2.position) {
      return [op1, new DeleteOperation(
        op2.position + op1.data.length,
        op2.data
      )]
    } else if (op1.position >= op2.position + op2.data) {
      return [new InsertOperation(
        op1.position - op2.data,
        op1.data
      ), op2]
    } else {
      // Insert position is within delete range
      return [new InsertOperation(
        op2.position,
        op1.data
      ), op2]
    }
  }

  if (op1.type === 'delete' && op2.type === 'insert') {
    // Mirror of above
    const [op2Prime, op1Prime] = transform(op2, op1)
    return [op1Prime, op2Prime]
  }

  if (op1.type === 'delete' && op2.type === 'delete') {
    if (op1.position + op1.data <= op2.position) {
      return [op1, new DeleteOperation(
        op2.position - op1.data,
        op2.data
      )]
    } else if (op2.position + op2.data <= op1.position) {
      return [new DeleteOperation(
        op1.position - op2.data,
        op1.data
      ), op2]
    } else {
      // Overlapping deletes - complex case
      const start = Math.min(op1.position, op2.position)
      const end1 = op1.position + op1.data
      const end2 = op2.position + op2.data
      const end = Math.max(end1, end2)

      return [
        new DeleteOperation(start, end - start - op2.data),
        new DeleteOperation(start, end - start - op1.data)
      ]
    }
  }
}

Server Implementation

WebSocket Server

const io = require('socket.io')(server, {
  cors: { origin: '*' }
})

const documents = new Map() // documentId -> Document
const clients = new Map()   // socketId -> { userId, documentId, cursor }

io.on('connection', (socket) => {
  console.log('Client connected:', socket.id)

  socket.on('join', async (data) => {
    const { documentId, userId, userName } = data

    // Load or create document
    if (!documents.has(documentId)) {
      const content = await loadDocumentFromDB(documentId)
      documents.set(documentId, new Document(documentId, content))
    }

    // Join room
    socket.join(documentId)

    // Track client
    clients.set(socket.id, {
      userId,
      userName,
      documentId,
      cursor: { line: 0, column: 0 }
    })

    // Send current document state
    const doc = documents.get(documentId)
    socket.emit('init', {
      content: doc.content,
      version: doc.version,
      clients: getClientsInDocument(documentId)
    })

    // Notify others
    socket.to(documentId).emit('user-joined', {
      userId,
      userName
    })
  })

  socket.on('operation', async (data) => {
    const { documentId, operation } = data
    const doc = documents.get(documentId)

    if (!doc) {
      socket.emit('error', { message: 'Document not found' })
      return
    }

    // Check version
    if (operation.version !== doc.version) {
      // Transform operation against missing operations
      let transformedOp = operation
      const missingOps = doc.history.slice(operation.version)

      for (const histOp of missingOps) {
        [transformedOp] = transform(transformedOp, histOp)
      }

      operation = transformedOp
    }

    // Apply operation
    doc.apply(operation)

    // Persist to database (async, don't wait)
    saveOperationToDB(documentId, operation).catch(console.error)

    // Broadcast to others in room
    socket.to(documentId).emit('operation', {
      operation,
      userId: clients.get(socket.id).userId
    })
  })

  socket.on('cursor', (data) => {
    const { documentId, cursor } = data
    const client = clients.get(socket.id)

    if (client) {
      client.cursor = cursor
      socket.to(documentId).emit('cursor', {
        userId: client.userId,
        cursor
      })
    }
  })

  socket.on('disconnect', () => {
    const client = clients.get(socket.id)

    if (client) {
      socket.to(client.documentId).emit('user-left', {
        userId: client.userId
      })
      clients.delete(socket.id)
    }
  })
})

function getClientsInDocument(documentId) {
  return Array.from(clients.values())
    .filter(c => c.documentId === documentId)
    .map(c => ({
      userId: c.userId,
      userName: c.userName,
      cursor: c.cursor
    }))
}

Database Persistence

const { Pool } = require('pg')

const pool = new Pool({
  host: process.env.DB_HOST,
  database: process.env.DB_NAME,
  user: process.env.DB_USER,
  password: process.env.DB_PASSWORD
})

async function loadDocumentFromDB(documentId) {
  const result = await pool.query(
    'SELECT content FROM documents WHERE id = $1',
    [documentId]
  )

  return result.rows[0]?.content || ''
}

async function saveOperationToDB(documentId, operation) {
  await pool.query(
    `INSERT INTO operations (document_id, type, position, data, version, created_at)
     VALUES ($1, $2, $3, $4, $5, NOW())`,
    [documentId, operation.type, operation.position,
     operation.data, operation.version]
  )

  // Update document content
  await pool.query(
    `UPDATE documents
     SET content = (
       SELECT string_agg(data, '' ORDER BY version)
       FROM operations
       WHERE document_id = $1
     ),
     version = version + 1,
     updated_at = NOW()
     WHERE id = $1`,
    [documentId]
  )
}

Client Implementation

Monaco Editor Integration

import * as monaco from 'monaco-editor'
import io from 'socket.io-client'

class CollaborativeEditor {
  constructor(container, documentId, userId, userName) {
    this.documentId = documentId
    this.userId = userId
    this.userName = userName

    // Create Monaco editor
    this.editor = monaco.editor.create(container, {
      language: 'javascript',
      theme: 'vs-dark',
      automaticLayout: true
    })

    // Connect to server
    this.socket = io('ws://localhost:3000')

    this.version = 0
    this.pendingOperations = []
    this.remoteUsers = new Map()

    this.setupListeners()
  }

  setupListeners() {
    // Join document
    this.socket.emit('join', {
      documentId: this.documentId,
      userId: this.userId,
      userName: this.userName
    })

    // Receive initial state
    this.socket.on('init', (data) => {
      this.editor.setValue(data.content)
      this.version = data.version

      // Show other users
      data.clients.forEach(client => {
        if (client.userId !== this.userId) {
          this.addRemoteUser(client)
        }
      })
    })

    // Local changes
    this.editor.onDidChangeModelContent((e) => {
      for (const change of e.changes) {
        const operation = this.createOperation(change)
        this.sendOperation(operation)
      }
    })

    // Remote operations
    this.socket.on('operation', (data) => {
      this.applyRemoteOperation(data.operation)
    })

    // Cursor tracking
    this.editor.onDidChangeCursorPosition((e) => {
      this.socket.emit('cursor', {
        documentId: this.documentId,
        cursor: {
          line: e.position.lineNumber,
          column: e.position.column
        }
      })
    })

    // Remote cursors
    this.socket.on('cursor', (data) => {
      this.updateRemoteCursor(data.userId, data.cursor)
    })

    // User joined
    this.socket.on('user-joined', (data) => {
      this.addRemoteUser(data)
    })

    // User left
    this.socket.on('user-left', (data) => {
      this.removeRemoteUser(data.userId)
    })
  }

  createOperation(change) {
    const model = this.editor.getModel()
    const offset = model.getOffsetAt({
      lineNumber: change.range.startLineNumber,
      column: change.range.startColumn
    })

    if (change.text) {
      return new InsertOperation(offset, change.text)
    } else {
      return new DeleteOperation(offset, change.rangeLength)
    }
  }

  sendOperation(operation) {
    operation.version = this.version
    this.pendingOperations.push(operation)

    this.socket.emit('operation', {
      documentId: this.documentId,
      operation
    })
  }

  applyRemoteOperation(operation) {
    const model = this.editor.getModel()

    // Transform against pending operations
    let transformedOp = operation
    for (const pendingOp of this.pendingOperations) {
      [transformedOp] = transform(transformedOp, pendingOp)
    }

    // Apply to editor
    const position = model.getPositionAt(transformedOp.position)

    if (transformedOp.type === 'insert') {
      model.applyEdits([{
        range: new monaco.Range(
          position.lineNumber,
          position.column,
          position.lineNumber,
          position.column
        ),
        text: transformedOp.data
      }])
    } else {
      const endPosition = model.getPositionAt(
        transformedOp.position + transformedOp.data
      )
      model.applyEdits([{
        range: new monaco.Range(
          position.lineNumber,
          position.column,
          endPosition.lineNumber,
          endPosition.column
        ),
        text: ''
      }])
    }

    this.version++
  }

  addRemoteUser(user) {
    this.remoteUsers.set(user.userId, {
      userName: user.userName,
      cursor: user.cursor,
      decoration: null
    })

    this.renderRemoteCursors()
  }

  removeRemoteUser(userId) {
    const user = this.remoteUsers.get(userId)
    if (user && user.decoration) {
      this.editor.deltaDecorations([user.decoration], [])
    }
    this.remoteUsers.delete(userId)
  }

  updateRemoteCursor(userId, cursor) {
    const user = this.remoteUsers.get(userId)
    if (user) {
      user.cursor = cursor
      this.renderRemoteCursors()
    }
  }

  renderRemoteCursors() {
    const decorations = []

    for (const [userId, user] of this.remoteUsers) {
      const decoration = {
        range: new monaco.Range(
          user.cursor.line,
          user.cursor.column,
          user.cursor.line,
          user.cursor.column + 1
        ),
        options: {
          className: 'remote-cursor',
          beforeContentClassName: 'remote-cursor-label',
          before: {
            content: user.userName,
            inlineClassName: 'remote-cursor-name'
          }
        }
      }
      decorations.push(decoration)
    }

    this.editor.deltaDecorations(
      Array.from(this.remoteUsers.values())
        .map(u => u.decoration)
        .filter(Boolean),
      decorations
    )
  }
}

// Usage
const editor = new CollaborativeEditor(
  document.getElementById('editor'),
  'doc-123',
  'user-456',
  'Alice'
)

CSS for Remote Cursors

.remote-cursor {
  background-color: rgba(0, 123, 255, 0.3);
  border-left: 2px solid #007bff;
}

.remote-cursor-label {
  position: absolute;
  top: -20px;
  left: -2px;
  background-color: #007bff;
  color: white;
  padding: 2px 6px;
  border-radius: 3px;
  font-size: 11px;
  font-weight: bold;
  white-space: nowrap;
}

Scaling Considerations

Multiple Server Instances

Use Redis for pub/sub across servers:

const Redis = require('ioredis')

const pub = new Redis()
const sub = new Redis()

// Subscribe to document updates
sub.subscribe('document-updates')

sub.on('message', (channel, message) => {
  const { documentId, operation, userId } = JSON.parse(message)

  // Broadcast to local clients
  io.to(documentId).emit('operation', { operation, userId })
})

// When receiving operation from client
socket.on('operation', (data) => {
  const { documentId, operation } = data

  // Apply locally
  const doc = documents.get(documentId)
  doc.apply(operation)

  // Publish to other servers
  pub.publish('document-updates', JSON.stringify({
    documentId,
    operation,
    userId: clients.get(socket.id).userId
  }))
})

Rate Limiting

Prevent abuse with rate limiting:

const rateLimit = new Map() // userId -> { count, resetTime }

function checkRateLimit(userId) {
  const now = Date.now()
  const limit = rateLimit.get(userId)

  if (!limit || now > limit.resetTime) {
    rateLimit.set(userId, {
      count: 1,
      resetTime: now + 60000 // 1 minute
    })
    return true
  }

  if (limit.count >= 1000) { // 1000 ops per minute
    return false
  }

  limit.count++
  return true
}

socket.on('operation', (data) => {
  const client = clients.get(socket.id)

  if (!checkRateLimit(client.userId)) {
    socket.emit('error', { message: 'Rate limit exceeded' })
    return
  }

  // Process operation...
})

Performance Optimizations

Operation Compression

Compress consecutive operations:

class OperationCompressor {
  constructor() {
    this.buffer = []
    this.timer = null
  }

  add(operation) {
    this.buffer.push(operation)

    if (!this.timer) {
      this.timer = setTimeout(() => {
        this.flush()
      }, 50) // 50ms delay
    }
  }

  flush() {
    if (this.buffer.length === 0) return

    const compressed = this.compress(this.buffer)
    this.send(compressed)

    this.buffer = []
    this.timer = null
  }

  compress(operations) {
    // Merge consecutive inserts at same position
    const result = []
    let current = operations[0]

    for (let i = 1; i < operations.length; i++) {
      const next = operations[i]

      if (current.type === 'insert' &&
          next.type === 'insert' &&
          current.position + current.data.length === next.position) {
        // Merge
        current = new InsertOperation(
          current.position,
          current.data + next.data
        )
      } else {
        result.push(current)
        current = next
      }
    }

    result.push(current)
    return result
  }
}

Testing

Unit Tests for Transform

describe('Operation Transform', () => {
  test('concurrent inserts at different positions', () => {
    const op1 = new InsertOperation(5, 'hello')
    const op2 = new InsertOperation(10, 'world')

    const [op1Prime, op2Prime] = transform(op1, op2)

    expect(op1Prime.position).toBe(5)
    expect(op2Prime.position).toBe(15) // 10 + 5
  })

  test('concurrent inserts at same position', () => {
    const op1 = new InsertOperation(5, 'a')
    const op2 = new InsertOperation(5, 'b')
    op1.replicaId = 'user1'
    op2.replicaId = 'user2'

    const [op1Prime, op2Prime] = transform(op1, op2)

    expect(op1Prime.position).toBe(5)
    expect(op2Prime.position).toBe(6)
  })

  test('insert vs delete', () => {
    const op1 = new InsertOperation(5, 'hello')
    const op2 = new DeleteOperation(3, 5)

    const [op1Prime, op2Prime] = transform(op1, op2)

    expect(op1Prime.position).toBe(3) // Moved back
    expect(op2Prime.position).toBe(3)
  })
})

Results

After 3 months of development:

  • Latency: < 100ms for operations
  • Concurrent users: Tested with 500+ simultaneous editors
  • Uptime: 99.9% over 6 months
  • Conflicts: Resolved automatically with 100% accuracy

Lessons Learned

  1. OT is complex - Use a library like ShareDB or Yjs
  2. Testing is critical - Concurrent operations have many edge cases
  3. Monaco is powerful - But has a learning curve
  4. Rate limiting is essential - Users can spam operations
  5. Redis helps scaling - Pub/sub across servers works great

Alternatives

Consider these alternatives:

  • CRDTs - Simpler than OT, but larger data size
  • ShareDB - Production-ready OT framework
  • Yjs - CRDT-based collaboration library
  • Automerge - JSON CRDT library

Resources