DEV Community: Ebendttl

Distributed Systems: Implementing the Raft Consensus Protocol from Scratch

Ebendttl — Tue, 26 May 2026 21:24:50 +0000

This is an excerpt. The full article includes a live interactive Raft consensus cluster simulator — control a 5-node distributed cluster, trigger leader elections, partition nodes to simulate network splits, commit client state updates, and watch the term-clock and replication logs resolve conflicts in real time. Read the full interactive version →

The Distributed State Problem

How do you get multiple independent computer nodes to agree on a single sequence of events, especially when individual nodes can crash, experience network delays, or drop packets?

This is the core challenge of Distributed Consensus. In a distributed database, all replicas must execute incoming commands in identical order to maintain a consistent state.

For years, the industry standard was Paxos — an algorithm famously powerful but incredibly complex to understand and implement without error.

Raft was designed as an alternative. It breaks down the consensus problem into three modular sub-problems: Leader Election, Log Replication, and Safety Invariants.

The Three Raft Node States

At any given moment, every node in a Raft cluster operates in one of three distinct roles:

        ┌───────────────────────────────────────┐
        │                FOLLOWER               │
        └───────────────────────────────────────┘
          │ (Times out, starts election)   ▲
          ▼                                │ (Discovers current leader)
        ┌───────────────────────────────────────┐
        │               CANDIDATE               │
        └───────────────────────────────────────┘
          │ (Receives majority votes)      
          ▼                                
        ┌───────────────────────────────────────┐
        │                 LEADER                │
        └───────────────────────────────────────┘

Follower: Completely passive. Responds to incoming RPC calls from Candidates and Leaders. If a follower receives no communication for a randomized timeout period, it assumes the leader has crashed and transitions to a Candidate.
Candidate: Increments the cluster "term", votes for itself, and broadcasts requests for votes to all other nodes.
Leader: Manages all client writes. Coordinates log replication and broadcasts periodic "heartbeat" RPCs to assert authority and reset follower timeout clocks.

Sub-Problem 1: Leader Election

To prevent split votes, followers wait for a randomized election timeout (typically between 150ms and 300ms) before initiating an election.

Once a node's timeout expires, it:

Increments its local currentTerm counter.
Transitions to the Candidate state.
Votes for itself.
Sends a RequestVote RPC to all other nodes.

If a candidate receives votes from a majority of nodes in the cluster (e.g., 3 out of 5), it immediately transitions to Leader and starts broadcasting heartbeats.

Sub-Problem 2: Log Replication

Once a Leader is elected, it acts as the single gateway for all client write requests.

Client ─── Write "X = 5" ───> Leader
                                │
          ┌─────────────────────┴─────────────────────┐
          │ (Append entry, broadcast AppendEntries)   │
          ▼                                           ▼
      Follower A                                  Follower B

The Replication Steps:

The client sends a command (e.g., set x=5) to the Leader.
The Leader appends the command to its local log.
The Leader broadcasts an AppendEntries RPC containing the new log entry to all followers.
Followers verify the entry and append it to their logs, sending a success confirmation back.
Once a majority of followers acknowledge the write, the Leader commits the entry to its state machine and returns a success response to the client.
In subsequent heartbeats, the Leader notifies followers of the newly committed entry, prompting them to commit it to their local state machines.

TypeScript Raft Node Implementation

Here is the baseline state container and interface schema for a Raft consensus node in TypeScript:

type NodeRole = "Follower" | "Candidate" | "Leader";

interface LogEntry {
  term: number;
  command: string;
}

interface RequestVoteArgs {
  term: number;
  candidateId: string;
  lastLogIndex: number;
  lastLogTerm: number;
}

interface RequestVoteReply {
  term: number;
  voteGranted: boolean;
}

class RaftNode {
  public id: string;
  public currentTerm = 0;
  public role: NodeRole = "Follower";
  public votedFor: string | null = null;
  public log: LogEntry[] = [];

  private commitIndex = 0;
  private electionTimeout: NodeJS.Timeout | null = null;
  private peers: string[] = [];

  constructor(id: string, peers: string[]) {
    this.id = id;
    this.peers = peers;
    this.resetElectionTimeout();
  }

  private resetElectionTimeout() {
    if (this.electionTimeout) clearTimeout(this.electionTimeout);

    // Randomized timeout between 150ms and 300ms prevents split votes
    const timeout = 150 + Math.floor(Math.random() * 150);
    this.electionTimeout = setTimeout(() => this.startElection(), timeout);
  }

  // Handle incoming vote request from Candidate node
  public handleRequestVote(args: RequestVoteArgs): RequestVoteReply {
    this.resetElectionTimeout();

    // 1. Term check: reject candidates with stale terms
    if (args.term < this.currentTerm) {
      return { term: this.currentTerm, voteGranted: false };
    }

    if (args.term > this.currentTerm) {
      this.currentTerm = args.term;
      this.role = "Follower";
      this.votedFor = null;
    }

    // 2. Log completeness check: candidate log must be at least as up-to-date as ours
    const lastIndex = this.log.length - 1;
    const lastTerm = lastIndex >= 0 ? this.log[lastIndex].term : 0;
    const logIsUpToDate =
      args.lastLogTerm > lastTerm ||
      (args.lastLogTerm === lastTerm && args.lastLogIndex >= lastIndex);

    // 3. Vote check
    const canVote = this.votedFor === null || this.votedFor === args.candidateId;

    if (canVote && logIsUpToDate) {
      this.votedFor = args.candidateId;
      return { term: this.currentTerm, voteGranted: true };
    }

    return { term: this.currentTerm, voteGranted: false };
  }

  private startElection() {
    this.role = "Candidate";
    this.currentTerm++;
    this.votedFor = this.id;
    this.resetElectionTimeout();

    console.log(`Node ${this.id} starting election for Term ${this.currentTerm}`);

    let votesReceived = 1; // Vote for self
    const lastLogIndex = this.log.length - 1;
    const lastLogTerm = lastLogIndex >= 0 ? this.log[lastLogIndex].term : 0;

    for (const peerId of this.peers) {
      // Simulate dispatching network RPC calls to peer cluster
      this.sendRequestVoteRPC(peerId, {
        term: this.currentTerm,
        candidateId: this.id,
        lastLogIndex,
        lastLogTerm
      }).then((reply) => {
        if (this.role !== "Candidate") return;

        if (reply.voteGranted) {
          votesReceived++;
          if (votesReceived > (this.peers.length + 1) / 2) {
            this.becomeLeader();
          }
        }
      });
    }
  }

  private becomeLeader() {
    this.role = "Leader";
    if (this.electionTimeout) clearTimeout(this.electionTimeout);
    console.log(`Node ${this.id} elected Leader for Term ${this.currentTerm}!`);
    this.startHeartbeats();
  }

  private startHeartbeats() {
    // Send AppendEntries heartbeats at 50ms intervals to maintain authority
    setInterval(() => {
      if (this.role !== "Leader") return;
      for (const peerId of this.peers) {
        this.sendAppendEntriesRPC(peerId);
      }
    }, 50);
  }

  // Mock network transporters for simulation environment
  private async sendRequestVoteRPC(peerId: string, args: RequestVoteArgs): Promise<RequestVoteReply> {
    return { term: this.currentTerm, voteGranted: Math.random() > 0.3 };
  }

  private async sendAppendEntriesRPC(peerId: string) {
    // Heartbeat logic
  }
}

Split-Brain and Minority Partitions

What happens when a network partition cuts a 5-node cluster into two segments: a majority partition (3 nodes) and a minority partition (2 nodes)?

  MAJORITY PARTITION (Can commit)         MINORITY PARTITION (Cannot commit)
   [Node A] ─── [Node B (Leader 1)]         [Node D] ─── [Node E (Leader 2)]
      │                                        │
   [Node C]                                    X (Network Partition cut)

The minority partition might elect a new leader because they can no longer hear from the original leader. However, this minority leader cannot commit any new client writes because they can never achieve the required cluster majority (3 nodes).

Once the partition heals:

The minority leader receives a heartbeat containing a higher term clock from the majority leader.
The minority leader immediately steps down back to a Follower.
The minority nodes discard their uncommitted local log differences and synchronize their states with the majority leader's canonical log.

Raft guarantees that the cluster always converges safely back to a single source of truth.

Engineering Takeaways

Raft guarantees Safety and Liveness in distributed environments with randomized timeouts.
Commitment requires absolute majority consensus — protecting clusters from split-brain state divergence.
Term clocks act as global logical time — higher term numbers override all stale cluster leaders.

The full article features a live 5-node Raft consensus cluster simulator — trigger network cuts to form minority and majority partitions, watch node roles transition, commit client writes, and view live log conflict resolution directly in your browser.

Read the full interactive article →

Written by Ebenezer Akinseinde — Software Developer & AI Automations Engineer.

Portfolio · GitHub

Reconciling P2P Collaborative States via WebRTC Data Channels

Ebendttl — Tue, 26 May 2026 21:18:53 +0000

This is an excerpt. The full article includes a live client-to-client WebRTC simulator — walk step-by-step through a simulated P2P handshake (Offer, STUN check, Signaling relay, Answer, Connection) and watch direct message sync bypass the central server entirely. Read the full interactive version →

The Peer-to-Peer Paradigm

Modern web architectures almost universally rely on client-server protocols (HTTP, WebSockets). While this simplifies state coordination, it introduces overhead: latency, server infrastructure costs, and single-point-of-failure bottlenecks.

WebRTC (Web Real-Time Communication) allows browsers to establish direct peer-to-peer (P2P) channels. Once connected, data flows directly between user devices with sub-10ms latencies, completely bypassing intermediate servers.

While WebRTC is widely known for audio/video streaming, its most powerful asset for application engineering is the RTCDataChannel API — allowing arbitrary, high-throughput, low-latency binary or text transfer directly between browsers.

The P2P Paradox: NATs and Signaling

Two browsers cannot simply talk directly to each other out of the box. Security boundaries and network topologies get in the way. Specifically, browsers face two barriers:

1. The NAT / Firewall Barrier

Almost all consumer devices sit behind Network Address Translators (NATs) and firewalls. A device knows its internal private IP (e.g. 192.168.1.45), but has no idea what its public-facing IP is, nor can it accept unsolicited incoming connections from the open web.

To cross this barrier, WebRTC utilizes ICE (Interactive Connectivity Establishment) alongside two types of auxiliary servers:

STUN (Session Traversal Utilities for NAT): A lightweight server that simply tells a requesting client: "Here is your public-facing IP address and port." This is cheap, fast, and succeeds in ~85% of standard residential network setups.
TURN (Traversal Using Relays around NAT): If symmetric NATs or strict corporate firewalls block direct connection, a TURN server acts as a fallback relay. All traffic is routed through it. This guarantees connection but incurs bandwidth costs.

2. The Signaling Bottleneck

To negotiate a direct connection, peers must exchange configuration details — specifically Session Description Protocol (SDP) objects (containing codecs, encryption keys, and connection profiles) and ICE Candidates (discovered IP/port routing paths).

Since they don't have a direct connection yet, they must use an out-of-band Signaling Server (typically running WebSockets or SSE) to exchange these initial handshakes.

Peer A                     Signaling Server                     Peer B
  │                                │                                │
  │ ─── 1. Send SDP Offer ───────> │ ─────────────────────────────> │
  │                                │                                │
  │ <── 2. Send SDP Answer ─────── │ <───────────────────────────── │
  │                                │                                │
  │ ─── 3. Exchange ICE Candidates │ ─────────────────────────────> │
  │                                │                                │
  │ <── [DIRECT P2P DATA CHANNEL ESTABLISHED (BYPASSES SERVER)] ──> │

Implementing WebRTC Data Channels in TypeScript

Here is a clean, dependency-free implementation of a WebRTC initiator client:

class P2PPeer {
  private pc: RTCPeerConnection;
  private dataChannel: RTCDataChannel | null = null;
  private signalingSocket: WebSocket;

  constructor(signalingUrl: string) {
    this.signalingSocket = new WebSocket(signalingUrl);

    // Configure standard public STUN servers
    this.pc = new RTCPeerConnection({
      iceServers: [
        { urls: "stun:stun.l.google.com:19302" },
        { urls: "stun:stun1.l.google.com:19302" }
      ]
    });

    this.setupIceGathering();
  }

  // Initiator: Create Offer and send to Peer
  async initiateConnection(targetPeerId: string) {
    // 1. Create the data channel on the local connection
    this.dataChannel = this.pc.createDataChannel("p2p-sync-channel", {
      ordered: true // Guarantees in-order delivery of packets
    });
    this.bindChannelEvents(this.dataChannel);

    // 2. Generate SDP Offer
    const offer = await this.pc.createOffer();
    await this.pc.setLocalDescription(offer);

    // 3. Dispatch to signaling server
    this.signalingSocket.send(JSON.stringify({
      type: "offer",
      target: targetPeerId,
      sdp: offer
    }));
  }

  // Receiver: Accept Offer, create Answer
  async handleOffer(offerSdp: RTCSessionDescriptionInit, senderId: string) {
    // 1. Set remote description
    await this.pc.setRemoteDescription(new RTCSessionDescription(offerSdp));

    // 2. Listen for the channel incoming event
    this.pc.ondatachannel = (event) => {
      this.dataChannel = event.channel;
      this.bindChannelEvents(this.dataChannel);
    };

    // 3. Generate SDP Answer
    const answer = await this.pc.createAnswer();
    await this.pc.setLocalDescription(answer);

    // 4. Send back via signaling
    this.signalingSocket.send(JSON.stringify({
      type: "answer",
      target: senderId,
      sdp: answer
    }));
  }

  private setupIceGathering() {
    // Broadcast discovered local ICE routes to remote peer
    this.pc.onicecandidate = (event) => {
      if (event.candidate) {
        this.signalingSocket.send(JSON.stringify({
          type: "ice-candidate",
          candidate: event.candidate
        }));
      }
    };
  }

  private bindChannelEvents(channel: RTCDataChannel) {
    channel.onopen = () => console.log("Direct P2P Data Channel Opened!");
    channel.onmessage = (event) => {
      const data = JSON.parse(event.data);
      console.log("Received P2P Message:", data);
    };
    channel.onclose = () => console.log("Data Channel Closed.");
  }

  send(message: any) {
    if (this.dataChannel && this.dataChannel.readyState === "open") {
      this.dataChannel.send(JSON.stringify(message));
    }
  }
}

State Reconciliations over P2P

Direct connections introduce concurrency challenges. If both clients edit a shared local state concurrently, how do they sync without a server?

The standard solution is pairing RTCDataChannel with a CRDT (Conflict-free Replicated Data Type) engine (like Y.js or Automerge). The data channel acts as a raw transport layer, while the CRDT handles deterministic state updates.

Because the data channel supports binary buffers (arraybuffer), you can transmit highly compact, compressed state updates directly:

channel.send(Y.encodeStateAsUpdate(ydoc));

Engineering Takeaways

WebRTC enables direct P2P connection, dropping transport latency to the raw physical limits of the network.
Signaling servers are only required for connection setup (SDP/ICE exchange) — once connected, the signaling server can crash and the P2P connection remains active.
STUN servers are free and easy to host, but always configure TURN servers as relays for symmetric or enterprise networks.
RTCDataChannel handles ordered or unordered data transmission, making it highly customizable for games, file sharing, or collaborative documents.

The full article features a step-by-step WebRTC handshake visualizer — walk through the signaling architecture with a live interactive simulation of Offer generation, STUN query routing, and P2P connection establishment.

Read the full interactive article →

Written by Ebenezer Akinseinde — Software Developer & AI Automations Engineer.

Portfolio · GitHub

Building a Vector Search Engine from Scratch: The Math and Mechanics of HNSW

Ebendttl — Tue, 26 May 2026 21:09:07 +0000

This is an excerpt. The full article includes a live 2D vector space sandbox — drag a query vector across a semantic coordinate field and watch cosine similarity scores update in real time across 9 framework nodes, with a toggle between Brute Force KNN and HNSW skip-graph traversal modes. Read the full interactive version →

The Geometry of Semantics

In the era of large language models, unstructured text is treated not as raw characters, but as a vector coordinate in a high-dimensional mathematical space.

When you pass text into an embedding model (like Google's text-embedding-004), it maps the semantic meaning into an array of floating-point numbers:

"Redis In-Memory Cache" → [ 0.01249, -0.04581, 0.08914, ..., -0.00312 ]  // 3072 dimensions
"PostgreSQL Database"   → [ 0.01183, -0.04491, 0.08877, ..., -0.00298 ]  // 3072 dimensions
"PyTorch Model"         → [-0.09214,  0.07321, -0.03812, ...,  0.06441 ]  // 3072 dimensions

Within this latent space, conceptually similar texts are geometrically close. "Redis" and "PostgreSQL" cluster near each other (both databases). "PyTorch" is far away (AI/ML domain).

Semantic search = finding the K-nearest neighbor coordinates to a query vector.

The Mathematical Distance Metrics

Three metrics dominate vector similarity calculations:

1. Cosine Similarity (most common for NLP)

cos(θ) = (A · B) / (|A| × |B|)

Measures the angular projection between two vectors. Range: -1 to 1. Completely ignores magnitude — two vectors pointing in the same direction score 1.0 even if one is 100× longer. This is ideal for text embeddings where magnitude carries no semantic information.

2. Dot Product (fastest for normalized vectors)

A · B = Σ(Aᵢ × Bᵢ)

When vectors are L2-normalized (unit length = 1), dot product yields identical rankings to cosine similarity with significantly less computation. Normalize your embeddings on ingestion, then use dot product at query time.

3. L2 Euclidean Distance (for spatial data)

d(A, B) = √(Σ(Aᵢ - Bᵢ)²)

Measures raw physical distance between vector tips. Highly sensitive to magnitude variations. Preferred for coordinate-based spatial systems, not raw text embeddings.

The Scaling Bottleneck: Why Brute Force Fails

In naive Brute Force KNN, you compare the query vector against every document in your database:

Complexity: O(D × N)  — where D = dimensions, N = document count

At scale, brute force saturates CPU and destroys real-time response requirements. You need Approximate Nearest Neighbor (ANN) indexing.

HNSW: Hierarchical Navigable Small World

HNSW translates the Skip List data structure into a multi-layered graph:

LAYER 2 (Sparse Highway) ─── node_A ──────────────────── node_B ───
LAYER 1 (Intermediate)   ─── node_A ─── node_C ─── node_B ─── node_D
LAYER 0 (Dense Ground)   ─ ALL nodes fully connected to neighbors ──

This reduces search complexity from:

Brute Force: O(N)         → Linear — fails at scale
HNSW:        O(log N)     → Logarithmic — sub-5ms at 10M+ docs

TypeScript HNSW Implementation

class HNSWIndex {
  private layers: Map<string, string[]>[] = [];
  private vectors: Map<string, number[]> = new Map();
  private readonly maxLayers: number;
  private readonly maxConnections: number;

  constructor(maxLayers = 4, maxConnections = 16) {
    this.maxLayers = maxLayers;
    this.maxConnections = maxConnections;
    this.layers = Array.from({ length: maxLayers }, () => new Map());
  }

  private cosineSimilarity(a: number[], b: number[]): number {
    const dot = a.reduce((sum, ai, i) => sum + ai * b[i], 0);
    const magA = Math.sqrt(a.reduce((sum, ai) => sum + ai * ai, 0));
    const magB = Math.sqrt(b.reduce((sum, bi) => sum + bi * bi, 0));
    return magA === 0 || magB === 0 ? 0 : dot / (magA * magB);
  }

  private getRandomLayer(): number {
    let layer = 0;
    while (layer < this.maxLayers - 1 && Math.random() < 0.5) {
      layer++;
    }
    return layer;
  }

  insert(id: string, vector: number[]): void {
    this.vectors.set(id, vector);
    const assignedLayer = this.getRandomLayer();

    for (let level = 0; level <= assignedLayer; level++) {
      if (!this.layers[level].has(id)) {
        const candidates = this.searchLayer(vector, level, this.maxConnections);
        this.layers[level].set(id, candidates.map(c => c.id));
      }
    }
  }

  search(queryVector: number[], k: number): { id: string; score: number }[] {
    let candidates = this.getEntryPoints(queryVector);

    for (let level = this.maxLayers - 1; level >= 0; level--) {
      candidates = this.searchLayer(queryVector, level, k, candidates);
    }

    return candidates
      .sort((a, b) => b.score - a.score)
      .slice(0, k);
  }

  private searchLayer(
    query: number[],
    level: number,
    k: number,
    entryPoints: { id: string; score: number }[] = []
  ): { id: string; score: number }[] {
    const visited = new Set<string>();
    const results: { id: string; score: number }[] = [...entryPoints];
    const queue = [...entryPoints];

    while (queue.length > 0) {
      const current = queue.shift()!;
      if (visited.has(current.id)) continue;
      visited.add(current.id);

      const neighbors = this.layers[level].get(current.id) ?? [];
      for (const neighborId of neighbors) {
        if (!visited.has(neighborId)) {
          const vec = this.vectors.get(neighborId)!;
          const score = this.cosineSimilarity(query, vec);
          queue.push({ id: neighborId, score });
          results.push({ id: neighborId, score });
        }
      }
    }

    return results
      .sort((a, b) => b.score - a.score)
      .slice(0, k);
  }

  private getEntryPoints(query: number[]): { id: string; score: number }[] {
    const entries: { id: string; score: number }[] = [];
    for (const [id, vec] of this.vectors) {
      entries.push({ id, score: this.cosineSimilarity(query, vec) });
      if (entries.length >= 3) break;
    }
    return entries;
  }
}

Production Scaling

Memory-Mapped Files (mmap): Keeping large indices in RAM causes OOM crashes. Bind binary index files directly to virtual address space — the OS swaps vector blocks in/out of disk cache automatically based on query patterns.

Product Quantization (PQ): Divide each high-dimensional vector into sub-vectors and map them to centroids. This reduces memory footprint by up to 95% with minimal recall degradation.

Engineering Takeaways

Always L2-normalize embeddings on ingestion to enable fast dot product scoring instead of full cosine calculation.
HNSW reduces O(N) to O(log N) — the single most impactful optimization for vector search at scale.
Use mmap + Product Quantization in production to handle tens of millions of vectors without OOM.

The full article includes a drag-and-drop 2D semantic space sandbox — 9 framework nodes plotted across a latent coordinate field, real-time cosine similarity leaderboard, toggle between Brute Force and HNSW skip-graph modes, and live layer traversal visualization.

Read the full interactive article →

Written by Ebenezer Akinseinde — Software Developer & AI Automations Engineer.

Portfolio · GitHub

Deep Dive into Y.js CRDTs for Real-Time Multiplayer Editors

Ebendttl — Tue, 26 May 2026 21:02:29 +0000

This is an excerpt. The full article includes a live YATA double-linked list simulator — type into two peer editors, toggle network partitions to simulate offline-first edits, and watch Y.js automatically resolve merge conflicts in real time. Read the full interactive version →

The Local-First Wave: Why OT Is Not Enough

Building real-time collaborative software used to require a centralized server orchestrator. For decades, the industry standard was Operational Transformation (OT) — the architecture powering Google Docs.

In OT, every local edit is wrapped into an operation and sent to a central server. The server acts as the single source of truth, recalculating operation coordinates to resolve conflicts and broadcasting adjusted commands back.

The OT Bottleneck: The server must be active 100% of the time, maintaining a complex sequence history buffer. The moment a client drops offline, peer-to-peer sync becomes nearly impossible to reconcile, leading to silent document divergence.

CRDTs (Conflict-free Replicated Data Types) rethink this entirely. Instead of relying on a server to decide conflict priority, CRDT structures are mathematically designed to merge operations in any order without coordination, guaranteeing all clients converge to identical state.

The Mathematical Foundation: Join-Semilattices

To achieve absolute convergence across decentralized peers, a data structure must form a join-semilattice. In practice, your merge functions must conform to three algebraic invariants:

Property	Formula	Meaning
Commutativity	`A ⊕ B = B ⊕ A`	Operations merge in any sequence order
Associativity	`(A ⊕ B) ⊕ C = A ⊕ (B ⊕ C)`	Grouping doesn't affect the result
Idempotency	`A ⊕ A = A`	Receiving the same operation twice doesn't mutate state

These three properties together mean: you can merge any subset of operations, in any order, any number of times, and always reach the same final document. No coordination server required.

The YATA Engine Under the Hood

Y.js implements YATA (Yet Another Transformation Algorithm) — a highly optimized CRDT designed specifically for text editing.

Under the hood, Y.js represents a document not as a raw string array, but as a double-linked list of Item blocks. Each item contains:

id: A unique tuple of (clientId, lamportClock) — globally unique across all peers
content: The character or string chunk
originLeft: The ID of the item to the immediate left at creation time
originRight: The ID of the item to the immediate right at creation time
deleted: Boolean tombstone flag

These origin pointers act as a permanent spatial anchor. Even if other users concurrently insert characters between the original boundaries, YATA can deterministically sort concurrent insertions using client ID priority — ensuring all replicas converge to identical ordering.

Conflict Resolution Example

Suppose two users type simultaneously at position 5:

Peer A inserts "X" with originLeft = "SYS:4"
Peer B inserts "Y" with originLeft = "SYS:4"

Both have the same originLeft. YATA resolves this by comparing client IDs alphanumerically. If "A" < "B", Peer A's item is sorted before Peer B's — identically on both replicas, regardless of which update arrived first.

Connecting Monaco Editor

Binding Y.js to Monaco Editor is done via the y-monaco package:

import * as Y from "yjs";
import { WebsocketProvider } from "y-websocket";
import { MonacoBinding } from "y-monaco";
import * as monaco from "monaco-editor";

// 1. Initialize Y.js document
const ydoc = new Y.Doc();

// 2. Connect to WebSocket relay server
const provider = new WebsocketProvider(
  "wss://your-relay-server.com",
  "document-room-id",
  ydoc
);

// 3. Create shared Y.Text type
const ytext = ydoc.getText("monaco-content");

// 4. Bind to Monaco Editor instance
const editor = monaco.editor.create(document.getElementById("editor")!, {
  value: "",
  language: "typescript"
});

// MonacoBinding syncs ytext ↔ Monaco model bidirectionally
// It also handles cursor decorations and multi-user awareness
const binding = new MonacoBinding(
  ytext,
  editor.getModel()!,
  new Set([editor]),
  provider.awareness
);

The MonacoBinding synchronizes Y.js document state with Monaco's internal text model bidirectionally — handling cursor decorations, selection highlights, and presence indicators automatically.

Production Relay Infrastructure

A single Y.js WebSocket server can't scale horizontally — each instance maintains its own in-memory document state. To scale, use Redis Pub/Sub as a shared synchronization backbone:

import { createServer } from "http";
import { WebSocketServer } from "ws";
import { setupWSConnection } from "y-websocket/bin/utils";
import { createClient } from "redis";

const redisPublisher = createClient({ url: process.env.REDIS_URL });
const redisSubscriber = redisPublisher.duplicate();

await redisPublisher.connect();
await redisSubscriber.connect();

const wss = new WebSocketServer({ server: createServer() });

wss.on("connection", (ws, req) => {
  // y-websocket handles CRDT sync protocol
  setupWSConnection(ws, req, {
    // Persistence callback — hook into Redis or PostgreSQL here
    persistence: {
      bindState: async (docName, ydoc) => {
        // Load existing document state from Redis
        const state = await redisPublisher.get(`ydoc:${docName}`);
        if (state) Y.applyUpdate(ydoc, Buffer.from(state, "base64"));
      },
      writeState: async (docName, ydoc) => {
        // Persist document state on every update
        const state = Y.encodeStateAsUpdate(ydoc);
        await redisPublisher.set(`ydoc:${docName}`, Buffer.from(state).toString("base64"));
      }
    }
  });
});

With Redis Pub/Sub, any number of WebSocket server instances can participate in the same document room. An update arriving at Server A propagates to Redis, which fans it out to Servers B and C, ensuring all connected peers — regardless of which server they're on — stay synchronized.

Key Optimizations for Production

Awareness Protocol: Y.js includes a built-in awareness system for sharing ephemeral state (cursor positions, user names, colors) without persisting to the CRDT document. Use this for presence, not your main Y.Doc.
State Vector Sync: On reconnect, clients exchange state vectors (Y.encodeStateVector) to efficiently compute only the missing updates — avoiding full document retransmission.
Subdocument Architecture: For large applications, split content across multiple Y.Doc instances (one per section/page). Load subdocuments lazily when accessed.

Engineering Takeaways

OT requires centralized servers; CRDTs enable true local-first. Offline edits automatically merge on reconnect.
YATA's origin pointers guarantee deterministic ordering without server coordination.
y-websocket + y-monaco is the fastest path to production collaborative editing.
Redis Pub/Sub enables horizontal scaling of Y.js WebSocket relay servers.
State vectors make reconnection efficient — only delta updates are exchanged.

The full article includes a live YATA double-linked list simulator. You can type into both peer editors simultaneously, toggle each peer's network state to create a partition, make offline edits, then click "Resolve & Sync Partition" to watch the CRDT merge algorithm reconcile divergent histories in real time — with the underlying Item linked-list visualized beneath.

Read the full interactive article →

Written by Ebenezer Akinseinde — Software Developer & AI Automations Engineer.

Portfolio · GitHub

Mastering Structured JSON Outputs with Gemini API

Ebendttl — Tue, 26 May 2026 19:47:23 +0000

This is an excerpt. The full article includes a live interactive schema sandbox where you can switch between 3 real constraint schemas and watch the Gemini inference engine stream constrained tokens in real time. Read the full interactive version →

The Problem: LLMs Are Eloquent, Not Predictable

Language models are optimized to be helpful communicators. This is precisely what makes them powerful interfaces for humans — and extraordinarily fragile integrations for software architectures.

Consider a simple extraction request:

"Extract the product name, price, and availability from the following text and return it as JSON."

Under testing, the model returns a clean JSON block. But in high-throughput production environments, you'll inevitably hit the model's alignment behaviors:

Conversational Padding: "Here is the data you requested: ..."
Varying Key Names: One response returns "product_name", another "product", a third "name"
Brittle Typings: A numeric price 279.99 becomes the raw string "$279.99"

Your downstream TypeScript classes throw unhandled KeyError exceptions. The execution fails.

Why Regex and Prompt Engineering Will Betray You

The classic fix is prompt escalation:

"Return ONLY a raw JSON object. Do NOT wrap in markdown. NEVER write conversational text."

This reduces failures under small loads — but instruction-following is entirely probabilistic. Under unexpected long-context inputs, the model drifts back to its conversational baseline. In a system handling 50,000 calls/day, a 1% failure rate represents 500 critical errors.

Custom regex parsing is worse. The moment the provider updates their model parameters, your regex silently corrupts production data.

Constrained Decoding: Enforcing Structure at the Inference Layer

Gemini's structured output system works via vocabulary masking during the inference step itself — not post-processing.

When generating a response, the model predicts the probability of every token in its ~32,000+ word vocabulary. Without constraints, it samples freely. When you enforce a JSON Schema contract, Gemini compiles it into a state machine. At every generation step, illegal tokens are masked to exactly zero probability.

If a field expects a number, every text token ("twenty", "$", any alphabet character) is mathematically eliminated. This is not retrying or filtering — it's structural constraint at the neural network's decoding loop.

Standard Decoding	Constrained Decoding (Gemini)
`"$279.99"` → 45% probability	`"$279.99"` → 0% probability
`"279.99"` → 40% probability	`"279.99"` → 100% probability
`"in stock"` → 15% probability	`"in stock"` → 0% probability

The Two API Pillars

Activate structured execution with two native parameters:

import { GoogleGenerativeAI, SchemaType } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY!);

const model = genAI.getGenerativeModel({
  model: "gemini-2.0-flash",
  generationConfig: {
    responseMimeType: "application/json",  // Pillar 1
    responseSchema: {                       // Pillar 2
      type: SchemaType.OBJECT,
      properties: {
        sentiment: {
          type: SchemaType.STRING,
          enum: ["VERY_POSITIVE", "POSITIVE", "NEUTRAL", "NEGATIVE", "VERY_NEGATIVE"]
        },
        csat_risk_score: {
          type: SchemaType.NUMBER,
          description: "0=no risk, 10=certain churn"
        },
        requires_human: { type: SchemaType.BOOLEAN }
      },
      required: ["sentiment", "csat_risk_score", "requires_human"]
    }
  }
});

responseMimeType: "application/json" switches the model from raw string processing to structured mode. responseSchema defines the structural contract the response must satisfy — keys, types, enums, required fields, all of it.

JSON Schema Deep Dive

Enums — The Most Powerful Constraint

Enums force Gemini to select from a hardcoded array of values. This is the single most impactful constraint for classification systems:

{
  "type": "string",
  "enum": ["IN_STOCK", "OUT_OF_STOCK", "BACKORDER"]
}

No hallucinated variants. No "in stock" vs "In Stock" inconsistencies. The schema enforces it at the token level.

Nullable Attributes

{ "type": "string", "nullable": true }

This prevents hallucinated values. If the input text contains no reference to that field, Gemini outputs null rather than inventing data.

The Multi-Stage Orchestration Pattern

For complex documents, never attempt a single massive extraction call. Instead, decompose into modular pipelines:

Raw Document
    ↓
Stage 1: Classification (Schema: DocType)
    ↓
Stage 2A: Invoice Parser  |  Stage 2B: Legal Contract  |  Stage 2C: Receipt Parser
    ↓                              ↓                              ↓
                     Unified Structured Database

Each stage uses a narrow, optimized schema. This reduces cost, increases accuracy, and makes debugging trivial.

Production Validation Layer

Schema enforcement guarantees structural correctness — not logical correctness. Always include downstream validation:

import { z } from "zod";

const SentimentSchema = z.object({
  sentiment: z.enum(["VERY_POSITIVE", "POSITIVE", "NEUTRAL", "NEGATIVE", "VERY_NEGATIVE"]),
  csat_risk_score: z.number().min(0).max(10),
  requires_human: z.boolean()
});

const raw = await model.generateContent(prompt);
const parsed = JSON.parse(raw.response.text());
const validated = SentimentSchema.safeParse(parsed);

if (!validated.success) {
  // Handle structural edge cases gracefully
  console.error("Validation failed:", validated.error);
}

Gemini guarantees output keys exist and types match. It cannot know if a discount value is negative or if invoice line items don't sum to the stated total. Always validate semantic parameters downstream.

Engineering Takeaways

Never rely on instruction-following alone. Probabilistic models will drift. Use structural constraints at the API level.
responseMimeType + responseSchema is the only production-safe pattern for JSON extraction pipelines.
Enums are your most powerful tool — they eliminate entire classes of inconsistency bugs.
Constrained decoding ≠ logical validation. Layer Zod or Pydantic downstream.
Multi-stage pipelines outperform single massive calls for complex document structures.

🔬 The full article includes an interactive Gemini Constraint Engine sandbox — select from 3 real schema contracts (Sentiment Tracker, Invoice Parser, Code Auditor) and watch constrained token streaming in real time. It also covers complex nested schemas, entity extraction patterns, cost/latency optimization, and the future of agentic orchestration.

Read the full interactive article →

Written by Ebenezer Akinseinde — Software Developer & AI Automations Engineer. Building fast, production-grade AI pipelines and distributed frontend systems.

Portfolio · GitHub