DEV Community: Yaseen Khatib

Real-Time Telemetry: Why Polling Lies, and WebSockets Don't

Yaseen Khatib — Wed, 23 Sep 2026 09:27:45 +0000

[ EXECUTIVE TEARDOWN // TL;DR ]

Polling can't be both fresh and cheap; a push model has the server speak only when state actually changes.
Broadcast events over a persistent socket and map them onto React state with a thin subscription.
Coalesce high-frequency sources on the server to a renderable frame rate, and isolate live state so only affected components repaint.
Single-source-of-truth sync — every client identical in the same instant — is what eliminates a whole class of stale-data errors.

After shipping enough "live" dashboards — including the real-time layer of the CMZ portal — one truth stuck: a polling dashboard is lying most of the time. Between ticks, operators act on stale numbers; shrink the window and you DoS your own APIs with empty work. For telemetry — CPU, chat velocity, scene state — stop interrogating the server and let it speak. WebSockets push changes the instant they occur, giving every client the same value in the same frame.

Why polling fails at scale

Polling forces a bad trade: either ship latency or ship waste. At 5s, your UI is up to 5s wrong and your fleet fires a wall of redundant reads. At 500ms, you approach freshness while torching CPU, caches, and rate limits with "nothing changed" responses. There isn't a magic interval; the question itself is expensive. Flip the model so the server only emits when state actually mutates.

The push architecture

The backend owns an event stream and broadcasts to subscribers over a persistent socket. No request fan-out, no timers — a value flips, the server emits, every dashboard updates in the same frame. In the pattern I call Trinity Architecture, the socket handler lives in the Reactive State / Orchestration layer, the Presentation layer just renders from state and dispatches intents, and a thin Data / Serialization Adapter shapes wire events into the in-memory model. No layer talks past its neighbor, which keeps both payloads and coupling under control.

telemetry.ts

// server: broadcast on change, not on request
metrics.on("tick", (m) => io.emit("telemetry", m));

// client: subscribe once, render on push
useEffect(() => {
  const s = socket(URL);
  s.on("telemetry", setMetrics);
  return () => s.close();
}</span>, []);

Throttle the wire, not the truth

A telemetry source can fire hundreds of events per second. Humans can't read that, and React can't reconcile that without jank. Shape the firehose at the edge — sample or debounce to a renderable cadence before broadcast — so the feed is truthful but frame-friendly. On streamerOS we had to respect 60fps while chat and system metrics spiked; coalescing server-side kept backpressure off the socket and the main thread, without lying about the latest value.

Consuming streams in React without thrashing

The foot-gun is wiring "telemetry" to setState and letting it reflow the whole tree each packet. Keep hot values in a small, focused store and subscribe only the components that care. I use a Trinity split: Presentation renders from selectors; the orchestrator (Zustand or an event bus) owns the source of truth and optimistic merges; the adapter translates over-the-wire shapes into minimal, denormalized state. A CPU tick should repaint one gauge, not your navbar, tables, and modals.

Why this kills manual errors

When every client observes the same state at the same moment, an entire class of "acted on stale data" mistakes disappears. No operator is reconciling conflicting numbers; no action races a 3s-old snapshot. The win isn't speed for its own sake — it's a single, timely source of truth that every operator shares, so decisions stop diverging.

Polling asks "has it changed?" a thousand times a minute. Push answers once, the moment it does. At scale, that's the line between "live" and "laggy."

This is the live-data backbone of streamerOS and the real-time sync layer in the CMZ portal — the same playbook I reach for when correctness, smoothness, and cost need to coexist. Deciding when a system should push instead of being asked is the kind of judgment I bring to a team.

~/keep-reading

Yaseen Khatib · MERN + AI Architect

Ships autonomous AI products solo — five in the last twelve months. More about Yaseen →

Need an engineer who can build this?

I'm Yaseen Khatib — a Senior Full-Stack AI Engineer (MERN + TypeScript) who ships production AI systems solo. Open to senior and lead roles, remote or on-site.

Get in touch →See what I've shipped

Originally published at yaseenkhatib.streamerosai.com/blog/real-time-telemetry-websockets-react/.

Zero-Account Auth: Device-Bound Identity + Capability Tokens

Yaseen Khatib — Wed, 23 Sep 2026 01:56:03 +0000

Why “zero-account” and what problem does it solve?

In a zero-account model, the device is the principal. It generates a key pair and the public key, or its thumbprint, is the identity you use everywhere. Authorization comes from signed capability tokens that spell out what the device is allowed to do.

You get rid of passwords and most PII. You also remove the central auth server from the hot path. The result still has strong, auditable security properties.

How do you authenticate devices without an auth server?

Use proof-of-possession. Each device creates a non-extractable key pair locally. Every request carries two artifacts: a DPoP proof (a signed JWT with the HTTP method, target URL, and a fresh jti) and a capability token tied to that key. Resource servers verify the DPoP and check that the capability’s confirmation claim matches the device key thumbprint. No central login step is required.

Core pieces

Device key pair (identity): P-256 or Ed25519, with the private key held in a platform keystore or as a non-extractable WebCrypto key.
DPoP proof per request: a signed JWT carrying htm/htu/iat/jti to stop replay and bind requests to the device key.
Capability token: a signed, scoped token (for example, PASETO v4.public) that encodes allowed actions and lifetime.
Stateless verification: services keep the signer’s public key and a small jti replay cache instead of a user database.

How do capability tokens replace user accounts?

Put permissions, resource scopes, rate or usage limits, and expiration into a signed token. Bind it to the device key with a confirmation (cnf) claim. Services only need the issuer’s public key to verify and authorize a request. No per-user record, session, or cookie jar.

Token shape (recommended)

Format: PASETO v4.public (Ed25519) or Macaroons for attenuation/delegation chains.
Claims:
- sub: device identifier (e.g., JWK thumbprint)
- cnf: { jkt: base64url(thumbprint) } to bind token to device key
- cap: list of capabilities [{ act, res, limit?, nbf?, exp? }]
- iat/exp/jti: temporal and anti-replay metadata

Example capability list:

act=read, res=/notes/*
act=write, res=/notes/{noteId}
limit=100 writes/24h (enforced server-side by metering on jti or sub)

Bootstrapping without accounts

You still need an initial trust handshake, but not a login.

Local-first: app generates a key pair on first run and displays a pairing code. A one-shot provisioning endpoint mints the first capability (for example, from a purchase receipt, license, or admin console) scoped to the device’s jkt.
Recurring: the device refreshes capabilities using a narrow “refresh” capability, still bound to the device. No username or password, no session cookies.

Client: device key generation and DPoP

Generate a non-extractable key and make DPoP-bound API calls. In a browser, use WebCrypto. In native apps, use Keychain/Keystore.

// browser-client.ts
import { exportJWK, calculateJwkThumbprint, SignJWT } from 'jose';

// 1) Generate a non-extractable ES256 keypair and persist via IndexedDB (omitted for brevity)
const { publicKey, privateKey } = await crypto.subtle.generateKey(
  { name: 'ECDSA', namedCurve: 'P-256' },
  false, // non-extractable private key
  ['sign', 'verify']
);

const pubJwk = await exportJWK(publicKey as CryptoKey);
const jkt = await calculateJwkThumbprint(pubJwk, 'sha256');

// 2) DPoP signer
async function dpopProof(method: string, url: string) {
  return await new SignJWT({ htm: method, htu: url, jti: crypto.randomUUID() })
    .setProtectedHeader({ typ: 'dpop+jwt', alg: 'ES256', jwk: pubJwk })
    .setIssuedAt()
    .sign(privateKey as CryptoKey);
}

// 3) Call API with capability token bound to this key
export async function callApi(capToken: string, method: string, url: string, body?: any) {
  const proof = await dpopProof(method, url);
  const res = await fetch(url, {
    method,
    headers: {
      'Authorization': `Bearer ${capToken}`,
      'DPoP': proof,
      'Content-Type': 'application/json'
    },
    body: body ? JSON.stringify(body) : undefined
  });
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return res.json();
}

Notes

The privateKey is non-extractable, so page malware can’t lift it.
DPoP carries htm/htu/jti/iat; a replay to a different URL or method fails.
capToken is issued out of band (provisioning or refresh) and must include cnf.jkt = jkt.

Server: verifying DPoP and PASETO capabilities

The resource server runs two separate checks: DPoP validity with replay protection, then capability verification and scope enforcement.

// server-auth.ts
import { decodeProtectedHeader, importJWK, jwtVerify, calculateJwkThumbprint } from 'jose';
import { V4 } from 'paseto';
import express from 'express';
import Redis from 'ioredis';

const app = express();
app.use(express.json());

// PASETO issuer keys (provisioned at deploy time)
// In production, load from HSM or env and rotate.
const { secretKey, publicKey } = await V4.generateKey('public');

const redis = new Redis(process.env.REDIS_URL!);

// Authorization middleware
app.use(async (req, res, next) => {
  try {
    const dpop = req.header('DPoP');
    const auth = req.header('Authorization');
    if (!dpop || !auth?.startsWith('Bearer ')) return res.status(401).end();
    const capToken = auth.slice('Bearer '.length);

    // 1) Verify DPoP proof
    const hdr = decodeProtectedHeader(dpop);
    if (hdr.typ !== 'dpop+jwt' || !hdr.jwk) return res.status(401).end();
    const dpopKey = await importJWK(hdr.jwk as any, hdr.alg as any);
    const { payload } = await jwtVerify(dpop, dpopKey, {
      typ: 'dpop+jwt',
      clockTolerance: '5s'
    });

    const method = (payload.htm as string || '').toUpperCase();
    const url = payload.htu as string;
    if (method !== req.method.toUpperCase()) return res.status(401).end();
    const expectedUrl = `${req.protocol}://${req.get('host')}${req.originalUrl}`;
    if (!url || !expectedUrl.startsWith(url)) return res.status(401).end();

    // Anti-replay: store jti with short TTL
    const jti = payload.jti as string;
    if (!jti) return res.status(401).end();
    const replay = await redis.setnx(`dpop:jti:${jti}`, '1');
    if (!replay) return res.status(401).send('replay');
    await redis.expire(`dpop:jti:${jti}`, 10); // seconds window

    const jkt = await calculateJwkThumbprint(hdr.jwk as any, 'sha256');

    // 2) Verify capability token (PASETO v4.public)
    const cap = await V4.verify(capToken, publicKey);

    // cnf binding check
    if (!cap.cnf || cap.cnf.jkt !== jkt) return res.status(401).send('key mismatch');

    // Temporal checks (paseto verifies exp/nbf if present, still validate policy)
    if (cap.exp && Date.now() / 1000 >= cap.exp) return res.status(401).send('expired');

    // Scope enforcement
    if (!allows(cap.cap, req.method, req.path)) return res.status(403).send('forbidden');

    // Optional: per-capability metering (rate/limit)
    // await enforceLimits(cap.sub, cap.jti, cap.cap)

    // Attach identity to request
    (req as any).device = { sub: cap.sub, jkt };
    next();
  } catch (e) {
    console.error(e);
    res.status(401).end();
  }
});

function allows(caps: any[], method: string, path: string) {
  // Minimal example: method+path prefix match
  return (caps || []).some(c =>
    (!c.act || c.act.toUpperCase() === method.toUpperCase()) &&
    pathMatch(c.res, path)
  );
}

function pathMatch(pattern: string, path: string) {
  // naive: '/notes/*' => prefix match
  if (!pattern) return false;
  if (pattern.endsWith('/*')) return path.startsWith(pattern.slice(0, -1));
  return pattern === path;
}

app.get('/notes/*', (req, res) => {
  res.json({ ok: true, device: (req as any).device });
});

app.listen(3000);

Key points

The DPoP header carries the public JWK; the server verifies it and computes the thumbprint.
Capability verification is stateless, only the publicKey is required.
cnf.jkt binds the token to the device, so a stolen token is useless without the private key.

Issuing capability tokens (no auth server required)

Any internal service holding the signing key can mint capabilities. Do it during provisioning, purchase validation, or admin workflows.

// issuer.ts
import { V4 } from 'paseto';
import { randomUUID } from 'crypto';

export async function issueCapability(secretKey: any, deviceJkt: string, caps: any[], ttlSec = 3600) {
  const now = Math.floor(Date.now() / 1000);
  const payload = {
    sub: `device:${deviceJkt}`,
    cnf: { jkt: deviceJkt },
    cap: caps,
    iat: now,
    exp: now + ttlSec,
    jti: randomUUID(),
    iss: 'cap-issuer:v1',
    aud: 'api'
  };
  return await V4.sign(payload, secretKey);
}

// Example cap set: read-only notes
await issueCapability(secretKey, 'kQ2…thumbprint…', [
  { act: 'GET', res: '/notes/*' }
], 900);

How do you revoke a leaked capability token without a DB?

Favor lifecycle controls over stateful revocation. Issue short-lived tokens, bind them to device keys with cnf.jkt plus DPoP, rotate signing keys on a schedule, and keep a small jti denylist only for emergencies. For long-lived tokens, include a refresh capability you can cut off by rotating a signer or revoking a cohort.

Practical revocation strategies

Short TTLs everywhere (5–15 minutes typical; seconds for high-value actions).
Rotate issuer keys regularly; invalidate cohorts by key ID (kid) rollover.
Maintain a Redis-backed jti denylist only for incident response; TTL entries to auto-expire.
Attenuate via nested capabilities or macaroons for delegations; revoke by refusing to mint downstream.

Macaroons vs PASETO

Aspect	PASETO v4.public	Macaroons
Simplicity	Single signature, flat claims	Attenuation via chained caveats
Delegation	Explicit via minting new token	Natural via third-party caveats
Verification	Public key verify	Shared root key + caveat verify
Fit here	Great for stateless caps	Great for delegation-heavy flows

For most zero-account APIs, PASETO v4.public with cnf binding and DPoP keeps things simple and robust. Use macaroons when you need on-chain attenuation and delegation proofs across services.

Threat model and mitigations

Token theft: mitigated by cnf.jkt plus DPoP; proofs are replay-protected by a jti cache and htm/htu binding.
Device compromise: out of scope; reduce blast radius with least-privilege capabilities and short TTLs.
Phishing: no passwords or sessions, which sharply reduces impact.
MITM: require HTTPS and HSTS; DPoP helps spot target URL tampering.
Key exfiltration (browser): make the private key non-extractable; prefer platform keystores in native apps.

Operational checklist

Rotate issuer keys and distribute their public half to all services.
Enforce DPoP on every protected endpoint and run a small jti replay cache.
Keep capability TTLs short; implement a refresh flow with a narrow-scoped refresh capability.
Log cap.jti, sub, and authorization decisions for audits.
Use deterministic resource matching and HTTP method checks in capability evaluation.

What about multi-device and recovery?

Use delegation. A primary device issues a short-lived delegation capability to the new device’s jkt via QR or pairing code. The server then grants that device first-party capabilities. For recovery, rely on out-of-band ownership proofs—such as a purchase receipt or an emailed link that mints a new device capability—instead of a persistent account.

MERN integration notes

React: hydrate app state from capabilities, no cookies. Use SWR/React Query and attach DPoP to each request.
Node/Express: middleware as shown; add route-level capability specs so they can be checked statically.
MongoDB: index audit logs by cap.jti and sub for incident triage. Avoid PII storage.
Next.js/SSR: don’t embed private keys; sign on the client or via server actions tied to device-bound refresh flows.

Closing thoughts

Zero-account means the device carries its identity and its rights. Pair capability tokens with DPoP, keep TTLs short, and bind everything to the device key. You get stateless, least-privilege authorization with less operational load than a traditional auth server, and a clear path to delegation and rotation as you grow.

Serialization Adapters: How I Cut Payloads by 94%

Yaseen Khatib — Tue, 22 Sep 2026 09:27:24 +0000

[ EXECUTIVE TEARDOWN // TL;DR ]

Separate the render model (UI) from the transport model (DB) with an adapter that owns the only conversion.
Anything derivable — dimensions, selection, handle geometry — is recomputed on load, never stored.
The 94% reduction is the sum of removing framework metadata and rounding coordinates, not a codec trick.
Most payload-size problems are boundary problems: you're shipping the cache because no line was drawn.

Rich UI objects are great for rendering and lousy as records. In IntegrateX — a node-graph automation tool — the node you drag around the canvas is packed with measured geometry, hover/selection flags, handle maps, and framework internals. Persist that verbatim and every save ships kilobytes of cached view state, sync gets chatty, and real-time edits run into backpressure. I put a Serialization Adapter at the boundary, kept only the domain fields, and dropped the UI scaffolding. Net: 94% smaller payloads and predictable sync.

Two models, one boundary

The naive approach fuses two things that must stay separate: the render model (what the UI needs to draw) and the transport model (what the wire and database require). The adapter translates both ways, and nothing crosses without it. This is the Data / Serialization Adapter in the pattern I call Trinity Architecture: Presentation renders and dispatches only, a Reactive State / Orchestration layer owns the runtime truth and optimistic updates, and the Adapter shapes lean records for the wire. No layer talks past its neighbor — the UI never formats DB schemas, and the adapter never pokes UI state directly.

adapter.ts

// render model → lean transport record (and back)
export const toRecord = (node: FlowNode): NodeRecord => ({
  id: node.id,
  type: node.type,
  x: Math.round(node.position.x),
  y: Math.round(node.position.y),
  config: node.data.config,   // the only domain data that matters
});

export const fromRecord = (r: NodeRecord): FlowNode =>
  hydrate(r, defaults(r.type));   // recompute view state, don't store it

Derived, never stored

The lever behind the compression is simple: anything that can be derived must not be stored. Dimensions come from layout. Selection is ephemeral. Handle geometry is a function of node type. Persisting them is persisting a cache. In IntegrateX, the orchestrator (Zustand in the middle of my Trinity split) recomputes those bits on load and on change, so the transport stays lean while the UI stays reactive.

The 94%, decomposed

This wasn't a clever codec; it was subtraction. Drop measured geometry, per-node flags, duplicated handles, and framework metadata. Round coordinates to integers. A node that used to serialize to roughly a kilobyte collapses to a few dozen bytes. Multiply by a hundred-node graph, and you reclaim the budget for save, load, and real-time sync — fewer bytes on the wire, fewer renders, less state-synchronization lag.

Most payload-size problems aren't compression problems — they're boundary problems. You're shipping the cache because nobody enforced the line between the view and the record.

For the state-management side of the same project — optimistic updates, sync ordering, and throttled broadcasts — see Compressing the Wire; the system is IntegrateX. I reach for this boundary discipline by default now — the engineer who draws the line between view and record early is the one whose sync layer still behaves at a hundred nodes.

~/keep-reading

Yaseen Khatib · MERN + AI Architect

Ships autonomous AI products solo — five in the last twelve months. More about Yaseen →

Need an engineer who can build this?

I'm Yaseen Khatib — a Senior Full-Stack AI Engineer (MERN + TypeScript) who ships production AI systems solo. Open to senior and lead roles, remote or on-site.

Get in touch →See what I've shipped

Originally published at yaseenkhatib.streamerosai.com/blog/custom-serialization-adapters/.

The 10x Reality: How AI Replaced the Traditional MERN Squad

Yaseen Khatib — Tue, 22 Sep 2026 09:27:22 +0000

[ EXECUTIVE TEARDOWN // TL;DR ]

AI has moved the developer's role from writing syntax to directing architectural flow.
A single architect with Claude can design, build, and ship a full Database → Backend → Frontend pipeline in the time a 10-person team once needed.
The only remaining bottleneck is deep comprehension of the system's data flow.
Velocity now scales with architectural clarity, not headcount.

For most of my career, throughput was something you bought with headcount. More endpoints, add backend engineers; more screens, add frontend engineers. That model just snapped. The limiter was never hands on keyboards — it was the latency between clear architectural intent and working code spread across three layers. AI has crushed that translation latency to near zero.

The bottleneck was never typing

Walk the timeline of a standard MERN feature. A lead sketches the data model. Backend builds the Mongoose schema, controller, validation, routes. Another engineer wires the service layer. Frontend ships the form, the fetch hook, the optimistic update, the error states. Someone else writes tests. Strip the meetings and merge conflicts and you see the uncomfortable truth: roughly 80% of that work was mechanical translation, not decisions. We already knew what to build; we were slowly re-encoding a known architecture into code.

That 80% is what AI now absorbs. Not the thinking — the scaffolding, wiring, and the thousand tiny consistency choices that quietly turn a week into a sprint.

From writing code to directing flow

The discipline that replaces manual coding is AI Orchestration: declare a single contract — the canonical data shape and its boundaries — and direct an agent to materialize it through every layer. Stop writing the database record, the endpoint, and the React hook as three separate artifacts. Declare the contract; generate the layers to satisfy it. I keep this inside the pattern I call Trinity Architecture: Presentation renders and dispatches only; Reactive State / Orchestration holds the runtime truth and coordinates events; the Data / Serialization Adapter shapes rich in-memory state into lean, durable payloads. No layer talks past its neighbor.

orchestrate.ts

// the architect declares intent; the orchestrator fills the layers
const system = await orchestrate({
  contract: caseRecordSchema, // single source of truth (zod)
  layers: ["db", "api", "ui"],
  guardrails: { types: "strict", review: "human" },
});

This is not autocomplete. Autocomplete predicts the next token in a file you're already writing. Orchestration operates a layer up: the contract is the spec and the codebase is the build target. Your leverage stops being WPM and starts being how precisely you specify.

The orchestration loop

Every productive AI build runs the same loop: declare the contract, generate a layer, verify it against the contract, integrate, repeat. The engineer's attention sits entirely on the seams — where one layer hands data to the next. Get the seams right and the interiors are commodity. Miss a seam and you get schema drift, broken optimistic updates, cache churn, and render thrash no amount of generated code can hide.

The only bottleneck left: data-flow comprehension

There is exactly one thing AI cannot do for you, and it has always mattered most: decide how data should move through your system. The shape of the records, the boundaries between services, the contracts that cross them, the indexes that make the queries cheap — these are architectural decisions, and they remain stubbornly, permanently human. Whoever holds the clearest mental model of the data's journey from Database → Backend → Frontend is now the entire critical path. On IntegrateX — a React Flow workflow canvas with real-time node execution and Zustand state — the hard problems were all flow and serialization. A Serialization Adapter stripped canvas-only UI metadata before persistence and cut payload sizes 94%, which in turn fixed state-sync lag during bursts. The adapter never touched UI state; it only spoke through the orchestrator. That boundary discipline is what kept real-time stable.

The era of bloated engineering teams is over. An AI-specialized architect can execute the output of a 10-person squad because the work that remains is comprehension, and comprehension does not parallelize without heavy coordination cost.

What the 10x architect actually does

Owns the data contract — one authoritative schema that every layer is generated to satisfy, eliminating drift between DB, API, and UI, and enforcing my Trinity split so the UI never formats DB shapes and the adapter never reaches into state.
Designs the boundaries — service and module cuts, where validation lives, which seams are stable versus allowed to change, and how events move across them.
Reviews AI output adversarially — not for style, but for the failure modes models won't surface: auth and tenancy, idempotency, pagination limits, streaming and backpressure, edge-case correctness and silent data loss.
Treats prompts as architecture specs — versioned, precise, and scoped; an ambiguous prompt is just an ambiguous requirement with faster failure.

The economic reality

A ten-person squad does not deliver ten units of work. It delivers maybe five after the tax: standups, handoffs, context rebuilds, merge conflicts, and the mismatch between the schema one person imagined and the one another implemented. A single architect directing AI pays none of that tax. There are no handoffs because there is one context. There is no schema drift because there is one contract. The output isn't incrementally faster — it's structurally different.

This is why the staffing question for greenfield product work is changing from how many engineers to how clear is the architecture. Velocity now scales with architectural clarity, not headcount — and that is far cheaper to buy.

If you want to see what this looks like shipped, the project breakdowns walk through production systems — agentic RAG pipelines, real-time admin portals, a real-time telemetry cockpit — each built and taken to production this way.

~/keep-reading

Yaseen Khatib · MERN + AI Architect

Ships autonomous AI products solo — five in the last twelve months. More about Yaseen →

Need an engineer who can build this?

I'm Yaseen Khatib — a Senior Full-Stack AI Engineer (MERN + TypeScript) who ships production AI systems solo. Open to senior and lead roles, remote or on-site.

Get in touch →See what I've shipped

Originally published at yaseenkhatib.streamerosai.com/blog/the-10x-reality-ai-replaced-the-mern-squad/.

The Day ChatGPT Changed Full-Stack Engineering

Yaseen Khatib — Mon, 21 Sep 2026 10:09:39 +0000

[ EXECUTIVE TEARDOWN // TL;DR ]

Late 2022 made writing code cheap for everyone at once, invalidating every estimate of how long features take.
The bottleneck moved from typing to judgment — the model amplifies architectural clarity and confusion alike.
MERN's typed, structured surface is exactly what models navigate well, positioning full-stack engineers to win.
Treat AI as a multiplier on sound architecture, not a substitute for understanding the system.

Late 2022 flipped the table: code went from scarce to cheap almost overnight. Not gradual, not gated by early adopters — everyone got the same accelerant at once. A general-purpose model could read intent and emit working code, turning the slowest part of the job — translating a design into syntax — into a conversation. Timelines based on keystrokes and boilerplate instantly stopped mapping to reality.

From Stack Overflow to a collaborator

The old loop: hit a snag, trawl threads, stitch together an answer, adapt, repeat. The new loop: describe the target — a React prop contract, a clean RTK Query slice, a Mongoose schema with indexes — and get a runnable draft that already speaks the local idioms. The grind that used to tax most days — glue code, adapter shims, the same five edge cases — mostly evaporated. What was left was the actual work: shaping behavior, owning the seams, and deciding where state lives.

The bottleneck moved to judgment

When typing is cheap, correctness of intent is the constraint. The people who got faster weren't “better prompters”; they carried a crisp architecture and steered the model to it. The pattern I call Trinity Architecture did the heavy lifting for me: a strict split between Presentation (React components that only render and dispatch), Reactive State / Orchestration (Zustand, RTK Query, or an event bus as the runtime source of truth with optimistic updates), and a Data / Serialization Adapter (the bridge that converts rich in-memory state to lean wire payloads). Keep those boundaries and the model locks into the grain; blur them and it produces fast spaghetti — state-synchronization lag, render thrash, and vague code that compiles but won't survive real-time pressure.

What it meant for MERN engineers

Full‑stack folks were sitting on the right surface area. MERN with TypeScript — contracts from Mongo through Express to React — is exactly the structured domain models navigate well. On IntegrateX, a React Flow workflow canvas with real-time node execution on a Zustand store, the model could draft nodes, hooks, and endpoints quickly. But the leap came from honoring the Trinity split and inserting a Serialization Adapter at the data boundary: it stripped non-essential React Flow UI metadata before persistence and cut payloads 94%. The model wrote the first pass; judgment decided what was wire-worthy, what stayed in orchestrated client state, and how to keep optimistic updates from outrunning the backend.

The day code became cheap to write was the day architecture became the job. Everything else is an implementation detail moving at 10x speed.

The next arc — RAG, orchestration, type‑safe outputs — sits downstream of that shift. It's why the work on IntegrateX, streamerOS, Path Saathi, and SANKALP reads like systems design under new physics: same constraints, but now the time goes to boundaries, contracts, and flow control instead of scaffolding.

~/keep-reading

Yaseen Khatib · MERN + AI Architect

Ships autonomous AI products solo — five in the last twelve months. More about Yaseen →

Need an engineer who can build this?

I'm Yaseen Khatib — a Senior Full-Stack AI Engineer (MERN + TypeScript) who ships production AI systems solo. Open to senior and lead roles, remote or on-site.

Get in touch →See what I've shipped

Originally published at yaseenkhatib.streamerosai.com/blog/chatgpt-changed-full-stack-engineering/.

I Shipped 5 Products in 12 Months — Solo, Unfunded, and Faster Than Most Teams Ship One

Yaseen Khatib — Mon, 21 Sep 2026 10:09:38 +0000

[ EXECUTIVE TEARDOWN // TL;DR ]

Five production products shipped in twelve months by one engineer: streamerOS, IntegrateX, Sable, a zero-cost content engine, and a LinkedIn automation pipeline.
Solo means every architecture, trust-boundary, and economics decision was made by one head — AI supplied throughput, not vision.
Each product was built to remove a recurring job from my life; that automation mindset transfers directly to company work.
One engineer who has shipped alone has verifiably done the work of PM, backend, frontend, DevOps, and QA.

In the last twelve months I designed, built, and shipped five production products — a realtime telemetry cockpit, a node-based workflow engine, a local-first AI finance agent, an autonomous content pipeline, and a LinkedIn outreach machine. No team. No funding. No standups. Every architecture decision, every line of infrastructure, every product call came from one place: my own head.

This post is not a humble-brag. It is a thesis about how software gets built now — and what a company actually buys when it hires an engineer who has done this.

The portfolio, in one table

streamerOS — a realtime telemetry cockpit for streamers: live system telemetry, multi-platform chat velocity, and automated OBS scene control, rendering at 60fps on a fraction of Electron's memory.
IntegrateX — a React Flow workflow-automation canvas whose custom serialization adapter cut graph payloads by 94%, making save/load feel instant.
Sable — a local-first AI financial agent. All data lives on-device in SQLite; the model proposes, a human confirms, and nothing financial ever leaves the phone.
The Zero-Cost AI Blog Writer — a pipeline that drafts, commits, and deploys technical articles on a cron schedule for exactly $0 of infrastructure.
The LinkedIn Pipeline — an autonomous system that turns my shipped work into scheduled LinkedIn content and grew my professional network while I slept.

What does "solo" mean when AI writes the code?

Solo does not mean I typed every character by hand like it's 2015. It means every decision was mine: the data model, the trust boundaries, the failure modes, the economics. I use Claude as a workforce and MCP as the wiring between it and my systems — but AI is leverage, not vision. A model can generate a component; it cannot decide that a finance app should never let the model touch the money, or that a streaming cockpit should hold its own state in process because streamers run OBS, a game, and an encoder on the same machine. Those calls are the product. The rest is throughput.

The scarce skill in 2026 is not writing code. It is holding an entire product in your head — data flow, trust boundaries, unit economics — clearly enough that the code becomes an output, not a struggle.

The compounding trick: products that work for you

The pattern across all five products is that each one removed a job from my life. The blog writer removed content production. The LinkedIn pipeline removed outreach. Sable removed money anxiety. streamerOS removed the four-apps-and-a-prayer streaming setup. I did not build demos — I built employees, and they have been on shift ever since. That is the mindset I bring to a company: look at the recurring work, ask which of it deserves a human, and ship a system for the rest.

What this proves to an employer

A candidate who has shipped five products alone has, by construction, done the job of a product manager, a backend engineer, a frontend engineer, a DevOps engineer, and a QA function — and paid the price for every mistake personally. There is no diffusion of responsibility in a team of one. When I say I understand systems end-to-end, the evidence is deployed, running, and documented across this site — every product has a full architecture breakdown in the products section.

The next nine posts in this series each take one of these systems — or one of the operating principles behind them — and show exactly how it was built, why it was built that way, and what the same thinking would do inside your company.

~/keep-reading

Yaseen Khatib · MERN + AI Architect

Ships autonomous AI products solo — five in the last twelve months. More about Yaseen →

Need an engineer who can build this?

I'm Yaseen Khatib — a Senior Full-Stack AI Engineer (MERN + TypeScript) who ships production AI systems solo. Open to senior and lead roles, remote or on-site.

Get in touch →See what I've shipped

Originally published at yaseenkhatib.streamerosai.com/blog/shipped-5-products-solo-12-months/.

Stop mixing render and domain state in React dashboards

Yaseen Khatib — Mon, 21 Sep 2026 01:49:26 +0000

What’s the difference between render state and domain state?

Render state drives pixels: selection, panel open/close, column order, scroll offsets, hover, active tab, in-flight drag positions. Domain state is the business data from the server, normalized and cached, with mutations and invalidation. When these are mixed, you get re-render storms, bloated payloads, and painful debugging.

I keep them apart. Domain state lives in a server-state cache (TanStack Query v5.47 or RTK Query 2.2.4). Render state lives in a tiny client store (Zustand 4.5.x) or local component state. Components read from both through selectors. Nothing else.

How do you separate render state from domain state in React?

Keep domain data in a server cache (TanStack Query/RTK Query) keyed by query params; keep UI state (sort, filters, selection, layout) in a co-located client store (Zustand). Components subscribe to minimal slices with shallow equality. Domain and UI layers talk only via dispatched events and props, not direct imports across layers.

Here’s a concrete cut on React 18.3, TypeScript 5.5.

// ui/store.ts
import { create } from 'zustand'
import { subscribeWithSelector } from 'zustand/middleware'

export type Sort = { column: string; dir: 'asc' | 'desc' } | null

interface TableUIState {
  sort: Sort
  filters: Record<string, unknown>
  selection: Set<string> // transient, not persisted
  columnOrder: string[]
  columnWidths: Record<string, number>
  scrollTop: number
  expandedRowIds: Set<string>
}

interface DashboardUIState {
  table: TableUIState
  modals: { inspectorOpen: boolean }
  // actions
  setSort: (sort: Sort) => void
  toggleSelect: (id: string) => void
  setColumnWidth: (col: string, px: number) => void
  setScrollTop: (y: number) => void
}

export const useUI = create<DashboardUIState>()(
  subscribeWithSelector((set, get) => ({
    table: {
      sort: null,
      filters: {},
      selection: new Set(),
      columnOrder: [],
      columnWidths: {},
      scrollTop: 0,
      expandedRowIds: new Set(),
    },
    modals: { inspectorOpen: false },
    setSort: (sort) => set((s) => ({ table: { ...s.table, sort } })),
    toggleSelect: (id) => set((s) => {
      const next = new Set(s.table.selection)
      next.has(id) ? next.delete(id) : next.add(id)
      return { table: { ...s.table, selection: next } }
    }),
    setColumnWidth: (col, px) => set((s) => ({
      table: { ...s.table, columnWidths: { ...s.table.columnWidths, [col]: px } }
    })),
    setScrollTop: (y) => set((s) => ({ table: { ...s.table, scrollTop: y } })),
  }))
)

// data/orders.ts (TanStack Query v5)
import { useQuery, QueryClient } from '@tanstack/react-query'

export const queryClient = new QueryClient({
  defaultOptions: {
    queries: { staleTime: 30_000, gcTime: 5 * 60_000, refetchOnWindowFocus: false },
  },
})

type Order = { id: string; status: string; total: number; createdAt: string }

type OrdersResponse = { items: Order[]; total: number }

function normalize(resp: OrdersResponse) {
  const byId: Record<string, Order> = {}
  for (const o of resp.items) byId[o.id] = o
  return { ids: resp.items.map((o) => o.id), byId, total: resp.total }
}

export function useOrders(params: { status?: string; q?: string; page: number; pageSize: number }) {
  const key = ['orders', params]
  return useQuery({
    queryKey: key,
    queryFn: async () => {
      const qs = new URLSearchParams(params as any).toString()
      const res = await fetch(`/api/orders?${qs}`)
      if (!res.ok) throw new Error(`HTTP ${res.status}`)
      return (await res.json()) as OrdersResponse
    },
    select: normalize,
    keepPreviousData: true,
  })
}

// components/OrdersTable.tsx
import { useOrders } from '../data/orders'
import { useUI } from '../ui/store'
import { useVirtualizer } from '@tanstack/react-virtual'

export function OrdersTable() {
  const sort = useUI((s) => s.table.sort)
  const selection = useUI((s) => s.table.selection)
  const setScrollTop = useUI((s) => s.setScrollTop)

  const { data, isFetching } = useOrders({ page: 1, pageSize: 500, status: undefined })
  const rows = data ? data.ids.map((id) => data.byId[id]) : []

  const parentRef = React.useRef<HTMLDivElement>(null)
  const rowVirtualizer = useVirtualizer({
    count: rows.length,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 36,
    overscan: 10,
  })

  return (
    <div ref={parentRef} style={{ height: 600, overflow: 'auto' }} onScroll={(e) => setScrollTop((e.target as HTMLDivElement).scrollTop)}>
      <div style={{ height: rowVirtualizer.getTotalSize(), width: '100%', position: 'relative' }}>
        {rowVirtualizer.getVirtualItems().map((vi) => {
          const row = rows[vi.index]
          const checked = selection.has(row.id)
          return (
            <div key={row.id} style={{ position: 'absolute', top: 0, left: 0, width: '100%', transform: `translateY(${vi.start}px)` }}>
              <Row row={row} checked={checked} />
            </div>
          )
        })}
      </div>
      {isFetching ? <div className="dim">Loading…</div> : null}
    </div>
  )
}

Important details that keep this fast:

The UI store holds only render concerns. No domain objects.
The server cache owns data fetching, normalization, and memoized selection.
Components subscribe via small selectors (e.g., s.table.sort), not the whole store.
Virtualization avoids mounting 50k DOM nodes.

This is the three-layer split I call Trinity Architecture: presentation components render from state and dispatch events; a reactive client state holds UI and orchestrates; and a data/serialization adapter bridges persistence. Layers never talk past neighbors.

Common symptom when you don’t split

setState in render or mixing stores often triggers: “Warning: Cannot update a component (X) while rendering a different component (Y).” Lift transient UI updates into the render store and update in events/effects.
Changing a large Redux slice that holds both UI and data causes 100+ dependent components to rerender. Selecting fine-grained slices in a small UI store reduces this.

How do you persist large dashboard state without bloating payloads?

Persist only stable layout and configuration, never raw data or transient UI noise. Introduce a small serialization adapter that strips ephemeral fields and converts non-serializable structures (Sets) to arrays. Store this layout JSON separately from data queries, versioned and small.

Example adapter for saving a dashboard layout to the server. This cut has kept payloads under 3–8 KB for complex boards; typical “save everything” payloads on real dashboards end up 200–800 KB due to selections and widths.

// ui/serialize.ts
import { useUI } from './store'

type PersistedLayoutV1 = {
  v: 1
  table: {
    sort: { column: string; dir: 'asc' | 'desc' } | null
    filters: Record<string, unknown>
    columnOrder: string[]
    columnWidths: Record<string, number>
    // intentionally no selection, no scrollTop
  }
  modals: { inspectorOpen: boolean }
}

export function buildPersistedLayout(state: ReturnType<typeof useUI.getState>): PersistedLayoutV1 {
  return {
    v: 1,
    table: {
      sort: state.table.sort,
      filters: state.table.filters,
      columnOrder: state.table.columnOrder,
      columnWidths: state.table.columnWidths,
    },
    modals: state.modals,
  }
}

export async function saveLayout(userId: string) {
  const layout = buildPersistedLayout(useUI.getState())
  await fetch(`/api/users/${userId}/layout`, {
    method: 'PUT',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify(layout),
  })
}

export function hydrateLayout(layout: PersistedLayoutV1) {
  // cautiously merge only known keys to avoid clobbering live transient state
  useUI.setState((s) => ({
    table: {
      ...s.table,
      sort: layout.table.sort,
      filters: layout.table.filters,
      columnOrder: layout.table.columnOrder,
      columnWidths: layout.table.columnWidths,
    },
    modals: layout.modals,
  }))
}

This “serialization adapter” is purposefully boring. It’s a whitelist. It strips non-essential UI metadata, which also future-proofs the layout format. On one production workflow tool (IntegrateX), a similar adapter cut saved graph payloads by about 94% by excluding React Flow render geometry.

If you must persist heavy mappings such as selection of thousands of rows, cap it. For instance, keep at most 500 IDs, and coerce it to an array of stable strings. Anything more should be re-derived on load from a saved filter.

How do you avoid re-render storms with large datasets?

Normalize server data and expose cheap selectors. - Keep UI state small and use fine-grained selectors with shallow compare. - Virtualize long lists and avoid inline object/array props. - Batch mutations and use startTransition when flipping large UI flags.

Concrete knobs that matter:

TanStack Query select normalization keeps referential stability. Derived “row” objects change only when their id actually changes.
Zustand selectors: use (s) => s.table.sort not (s) => s.table. If you must select multiple keys, memoize or use shallow.

import { shallow } from 'zustand/shallow'
const [sort, columnOrder] = useUI((s) => [s.table.sort, s.table.columnOrder], shallow)

Avoid creating new objects in JSX props on hot paths. Move them out or use useMemo.

const columns = React.useMemo(() => buildColumns(columnOrder), [columnOrder])
<Table columns={columns} />

For bulk UI updates that trigger lots of child work, wrap in a transition.

const [pending, startTransition] = React.useTransition()
const onToggleAll = () => startTransition(() => useUI.getState().toggleAllVisible())

Typical figures to keep in mind (illustrative only): 50–100k rows of JSON over a 4G link is 8–20 MB and costs 1.5–4 s network + 100–250 ms parse/GC on an M1. Don’t fetch that. Paginate server-side and virtualize client-side.

What’s the SSR/Next.js 14 story without hydration bugs?

Prefetch domain data on the server and dehydrate it; create UI state only on the client after mount. Don’t embed UI state in the HTML. If you must seed it, keep it minimal and idempotent, and merge during a client effect, not during initial render.

Sketch for Next.js 14.2 with TanStack Query dehydrate:

// app/orders/page.tsx
import { dehydrate, Hydrate } from '@tanstack/react-query'
import { queryClient } from '@/data/orders'

export default async function Page() {
  await queryClient.prefetchQuery({ queryKey: ['orders', { page: 1, pageSize: 50 }], queryFn: fetchOrders })
  const state = dehydrate(queryClient)
  return (
    <Hydrate state={state}>
      <OrdersPageClient />
    </Hydrate>
  )
}

// app/orders/OrdersPageClient.tsx
'use client'
import { useEffect } from 'react'
import { hydrateLayout } from '@/ui/serialize'

export function OrdersPageClient() {
  useEffect(() => {
    // fetch persisted layout and hydrate into UI store after mount
    fetch('/api/me/layout').then((r) => r.json()).then(hydrateLayout).catch(() => {})
  }, [])
  return <OrdersTable />
}

Two rules that prevent hydration mismatches:

Never render from a UI store value that differs between server and client during the initial paint.
If a UI default must depend on window or layout, compute it in useEffect and update the store there.

Real-time and AI panels: keep tokens out of domain state

For streaming telemetry or AI summaries, treat partial tokens/lines as render state. Domain state should track the final artifact and its metadata.

// ai/summarize.ts - SSE streaming client
export function streamSummary(taskId: string, onToken: (t: string) => void) {
  const es = new EventSource(`/api/tasks/${taskId}/summary/stream`)
  es.addEventListener('token', (e) => onToken((e as MessageEvent).data))
  es.addEventListener('done', () => es.close())
  return () => es.close()
}

// components/SummaryPanel.tsx
import { useUI } from '@/ui/store'
import { useEffect, useState } from 'react'

export function SummaryPanel({ taskId }: { taskId: string }) {
  const [text, setText] = useState('') // render state only
  useEffect(() => streamSummary(taskId, (t) => setText((prev) => prev + t)), [taskId])
  return <pre className="summary">{text}</pre>
}

Persist only the final text (domain) as part of task metadata through a normal mutation. Do not shove partial token streams into your global stores.

When not to do this

Small CRUD with <10 screens and <2k rows/page: local component state + a single query cache is fine. Splitting stores adds cognitive overhead and boilerplate.
Teams without discipline on selectors and memoization can end up with two anti-patterns instead of one. Keep the rules enforced in code review.
Heavy cross-slice coupling: if a mutation in domain must atomically update multiple UI concerns, put a thin orchestrator function next to the UI store; don’t call the data cache directly from view code.

Failure modes to watch

Over-persisting UI: saving selection sets, hover rows, scroll positions balloons payloads and creates janky restores.
Non-serializable UI state in devtools: Sets/Maps are fine in-memory but convert at persistence boundaries.
Thundering updates: writing to the UI store from tight mousemove handlers without requestAnimationFrame batching will stutter.
WebSocket or RTU messages that include render-only fields will hurt mobile users; keep wire payloads to business data.

Tooling and versions that work

React 18.3, Next.js 14.2
Zustand 4.5.x with subscribeWithSelector
TanStack Query 5.47 (or RTK Query 2.2.4 if you’re already on Redux Toolkit 2.2.x)
@tanstack/react-virtual 3.x or AG Grid 31.x for big tables
TypeScript 5.5, Node 20.16 LTS

A quick install baseline:

pnpm add zustand @tanstack/react-query @tanstack/react-virtual

A minimal checklist

Domain state: queries/mutations, normalized, cached, invalidated by keys.
Render state: sort, filters, column order, selection, scroll, modals.
Serialization adapter: whitelist-only persisted layout, versioned.
Components: subscribe to minimal slices; virtualize long lists; memoize heavy props.
SSR: dehydrate domain data; hydrate UI after mount.

One blunt question to keep taped to the monitor: will this value cross a process boundary (persist, sync, or query)? If yes, it belongs to domain state; if not, keep it in render state. Keeping that line bright is most of the battle.

When useMemo actually helps in React 19, and how to measure it

Yaseen Khatib — Sun, 20 Sep 2026 09:25:34 +0000

[ EXECUTIVE TEARDOWN // TL;DR ]

useMemo helps when you stabilize expensive derived data or prop identities that gate large subtrees; it’s pointless for trivial work.
Measure first with React DevTools Profiler, performance marks, and why-did-you-render before adding memo layers.
React 19 doesn’t change useMemo semantics—don’t treat it as a cache or side-effect boundary, and expect extra invocations in dev Strict Mode.
Avoid holding large arrays/objects in useMemo without bounds; it can increase memory retention and mask poor data flow.

What (didn’t) change in React 19

React 19 (as of 19.0.0-rc) brings Actions, asset loading, and use on the client, but useMemo semantics are the same as React 18. It’s a render-time memoization of a pure computation. It is not a cache across unmounts, not a signal to skip work outside React, and not a guarantee against recomputation in interrupted renders.

In development Strict Mode, initial render paths may run twice to surface unsafe patterns. That includes the function you pass to useMemo. Don’t bake side effects into it.

When should I use useMemo in React 19?

Use useMemo when you have: (1) a pure, CPU-expensive computation whose inputs rarely change (sorting, grouping, schema building), or (2) a prop identity that gates a large memoized subtree (arrays/objects passed to React.memo children or virtualization libraries). If you’re memoizing a 20-element map or a two-field object, don’t bother.

Typical wins (illustrative, not your benchmarks):

Sorting/filtering 10k items on each keystroke: ~8–25 ms per render in desktop Chrome. Memoizing by items and sortKey can cut that to ~0–1 ms on unchanged keys.
Stabilizing a columns array for a memo-ized DataGrid avoids re-rendering thousands of cells when only a search box changes.

Smells:

{foo, bar} objects recreated to pass into a leaf that doesn’t care about identity.
Memoizing a map over <100 items that’s cheap next to layout/paint or network latency.
Hiding state design issues (derivations that belong in a selector/store).

How do you measure React render cost before adding useMemo?

Profile with React DevTools Profiler to see commit times and why components rendered. Add performance.mark around known hotspots to get millisecond timings in Chrome’s Performance panel. Finally, wire up why-did-you-render to spot useless re-renders from unstable prop identities. Change one thing at a time.

Baseline with React DevTools Profiler

Install React DevTools (>= 5.x) and open the Profiler tab.
Hit “Start profiling,” reproduce the interaction (typing, toggling filters), stop.
Look at the flame chart for components over ~4–10 ms per commit or called very frequently.
Click a hot component and check “Why did this render?” If props are !== but logically the same, you have an identity problem.

Add performance marks where CPU actually burns

// expensive-derivation.ts
export function buildIndex(rows: Row[], key: keyof Row) {
  performance.mark('buildIndex:start');
  const map = new Map<any, Row[]>();
  for (const r of rows) {
    const k = r[key];
    const arr = map.get(k);
    if (arr) arr.push(r); else map.set(k, [r]);
  }
  performance.mark('buildIndex:end');
  performance.measure('buildIndex', 'buildIndex:start', 'buildIndex:end');
  return map;
}

Open Chrome DevTools → Performance, record, and filter for “buildIndex” measures. You’ll get concrete ms per call, not vibes.

Catch identity churn with why-did-you-render

npm i -D @welldone-software/why-did-you-render

// index.tsx
import React from 'react';
if (process.env.NODE_ENV === 'development') {
  // @ts-ignore
  const wdyr = require('@welldone-software/why-did-you-render');
  wdyr(React, { trackAllPureComponents: true });
}

Now memoized children will log when they re-render due to deep-equal props that changed by reference.

Example: expensive derived data (wins)

You have 20k rows with filtering and sorting. Users type in a search box; unrelated toggles shouldn’t re-run the sort.

import { useMemo, useState } from 'react';
import { buildIndex } from './expensive-derivation';

function useCatalog(rows: Row[]) {
  const [sortKey, setSortKey] = useState<keyof Row>('name');
  const [query, setQuery] = useState('');

  // Derive once per (rows, sortKey). Query filter is cheap, do it later.
  const sorted = useMemo(() => {
    // Pure and CPU-heavy
    const arr = [...rows].sort((a, b) => String(a[sortKey]).localeCompare(String(b[sortKey])));
    return arr;
  }, [rows, sortKey]);

  const filtered = useMemo(() => {
    if (!query) return sorted;
    const q = query.toLowerCase();
    return sorted.filter(r => r.name.toLowerCase().includes(q));
  }, [sorted, query]);

  // Example of very heavy grouping on rows only
  const indexByCategory = useMemo(() => buildIndex(sorted, 'category'), [sorted]);

  return { filtered, indexByCategory, setSortKey, setQuery };
}

Measure before/after. If the Profiler shows the parent re-renders a lot but sorted doesn’t change, filtered will recompute only when query does—good. If rows is a new array identity on every fetch even when contents are the same, fix your fetch layer or state manager; useMemo won’t help if the dependency changes every time.

Example: prop identity that controls a large subtree (wins)

Libraries like virtualized grids often React.memo row/cell renderers based on shallow prop equality. If you hand them a new columns array every render, they’ll repaint the world.

type Column = { key: string; title: string; width: number };

function ProductsGrid({ products, dense }: { products: Row[]; dense: boolean }) {
  // BAD: new array on every render → virtualizer re-renders
  // const columns = [
  //   { key: 'name', title: 'Name', width: dense ? 180 : 240 },
  //   { key: 'price', title: 'Price', width: 120 },
  // ];

  // GOOD: stable identity unless deps change
  const columns = useMemo<Column[]>(() => [
    { key: 'name', title: 'Name', width: dense ? 180 : 240 },
    { key: 'price', title: 'Price', width: 120 },
  ], [dense]);

  return <VirtualGrid data={products} columns={columns} />;
}

With why-did-you-render you’ll see the grid stop re-rendering on state unrelated to dense. In Profiler, commit time drops and row components disappear from the hot path when toggling UI chrome.

Example: fake optimization (loss)

Developers frequently memoize trivial work and then complain nothing improved. Here’s why.

function TinyList({ items }: { items: number[] }) {
  // Pointless: mapping 20 items is <0.1 ms; memo bookkeeping can exceed it.
  const doubled = useMemo(() => items.map(x => x * 2), [items]);
  return (
    <ul>{doubled.map(x => <li key={x}>{x}</li>)}</ul>
  );
}

If items changes almost every render (typing, streaming updates), useMemo still recomputes. You paid abstraction cost for nothing. Measure: you’ll see the same commit time with or without it; sometimes marginally worse.

What about transitions, Actions, and RSC boundaries?

Transitions (React 18/19) increase concurrent work. useMemo still runs in render. If you start a transition that doesn’t affect a memo’s deps, it will reuse the existing value—useful for keeping big derivations out of the transition path.
Actions and use don’t change client useMemo. Server Components have their own cache mechanisms; useMemo does not persist across the server/client boundary.

When NOT to use useMemo (real failure modes)

You’re fighting your data flow. If rows gets replaced each fetch because you setState([...data]) every poll, fix the source (stable references, normalized stores, selectors). useMemo is a band-aid.
Side effects inside useMemo. It may run multiple times in dev, and any effect belongs in useEffect or outside React.
Large object retention. If you memoize a 50 MB array (yes, it happens) and keep the component mounted, you’re pinning that memory. Memoization increases lifetime. If you only need a small projection, memoize the projection, not the blob (or don’t memoize and compute lazily per page).
Overfitting to micro-benchmarks. Modern browsers spend a lot of time on layout/paint. Shaving 0.2 ms in JS while triggering 16 ms of layout is misdirected effort.

How do you choose dependencies, safely?

Pick the minimal stable inputs that fully determine the result. For derived arrays:

Prefer stable upstream references (state managers with referential equality guarantees, e.g., Zustand selectors with shallow).
Avoid passing freshly created objects as deps. Hoist them into their own useMemo or state if they’re logically inputs.

// Bad: anonymous object in deps → always changes
const costs = useMemo(() => computeCosts(items, { tax, discount }), [items, { tax, discount }]);

// Good: stabilize the options first
const priceOpts = useMemo(() => ({ tax, discount }), [tax, discount]);
const costs = useMemo(() => computeCosts(items, priceOpts), [items, priceOpts]);

If the linter nags, it’s usually right. Either add the missing dep or restructure so the function is pure with the listed deps.

A quick checklist before reaching for useMemo

Can I point to a component in Profiler spending >4–5 ms on render repeatedly? If not, skip.
Do I see re-renders because of !== props that are logically equal (via why-did-you-render)? Stabilize identity or stop passing that prop.
Is the work pure and CPU-heavy (O(n log n) sort on thousands of items, complex schema generation)? Memoize.
Will this memoize large data for a long time? Consider bounding or memoizing a projection instead.
Would moving the derivation to a selector/store (e.g., Reselect/Zustand) be cleaner? Often yes.

A note on selectors vs useMemo

For cross-component derived state, don’t scatter useMemo across the tree. Centralize it:

// Reselect-style memoized selector
import { createSelector } from '@reduxjs/toolkit';

const selectRows = (s: RootState) => s.rows;
const selectSortKey = (s: RootState) => s.sortKey;

export const selectSorted = createSelector([selectRows, selectSortKey], (rows, key) => {
  return [...rows].sort((a, b) => String(a[key]).localeCompare(String(b[key])));
});

This gives you global referential stability and avoids recomputing per component. Use useMemo at the leaf only if you’re composing expensive UI-only transforms.

Concrete measurement recipe

Turn on Profiler and capture the slow interaction.
Identify a hot component and confirm why it renders.
Drop performance.mark around actual heavy functions. Re-record with Chrome Performance.
If identity churn is the issue, stabilize with useMemo/useCallback around the exact prop(s) the child keys on.
If heavy compute is the issue, memoize the derivation with the minimal dependency set.
Re-profile. If you didn’t move the needle by at least a couple milliseconds per commit or reduce commit count, revert.

Final sanity checks

useMemo is not a silver bullet. In React 19 it’s the same sharp knife it’s been since 16.8.
Favor clarity. A well-placed useMemo around a big sort or a columns config is boring and effective. Blanket memoization is busywork.
Keep the measurements near the code. If you can’t show a before/after profile graph or a performance.measure delta, you probably don’t need it.

~/keep-reading

Yaseen Khatib · MERN + AI Architect

Ships autonomous AI products solo — five in the last twelve months. More about Yaseen →

Need an engineer who can build this?

I'm Yaseen Khatib — a Senior Full-Stack AI Engineer (MERN + TypeScript) who ships production AI systems solo. Open to senior and lead roles, remote or on-site.

Get in touch →See what I've shipped

Originally published at yaseenkhatib.streamerosai.com/blog/when-usememo-actually-helps-in-react-19-and-how-to-measure-it/.

Semantic Caching That Actually Hits: Matching Meaning at the Edge

Yaseen Khatib — Sun, 20 Sep 2026 09:25:32 +0000

[ EXECUTIVE TEARDOWN // TL;DR ]

String-keyed caches miss because no two users phrase a question the same way; semantic caching matches on meaning.
Reuse the query embedding you already compute to look up previously answered questions in a small vector index.
The similarity threshold is a risk decision, not a constant — keep it conservative for grounded agents.
Tag cache entries with the corpus version and invalidate on re-index to avoid serving stale answers.

Running the streamerOS support agent taught me that support traffic is gloriously repetitive. "How do I connect my OBS?", "how do I link OBS", "OBS setup help" — three phrasings of one question, and a naive RAG pipeline runs the full retrieve-and-generate gauntlet for every single one. Each is a model call I paid for and a second of latency the user waited through, to produce an answer already produced a hundred times. Semantic caching fixes this by recognising the question, not the string.

Why a normal cache misses

A key-value cache keyed on the raw query string is useless here, because no two users phrase a question identically. The cache hit rate hovers near zero. What you actually want to match on is meaning — and you already have the machinery to measure meaning, because your RAG pipeline embeds the query anyway. A semantic cache reuses that embedding to ask a different question: have I already answered something that means this?

The cheapest model call is the one you never make. Above the threshold, the answer is already on the shelf.

The mechanism

Embed the incoming query — you were going to anyway. Before doing any retrieval or generation, search a small vector index of previously answered queries. If the nearest neighbour sits above a similarity threshold, return its stored answer and stop. If not, run the full pipeline, then write the new query embedding and its answer back to the cache. The cache learns the shape of your traffic over time, and the hot questions go nearly free.

semantic-cache.ts

// check meaning, not string equality
const qVec = await embed(query);
const [near] = await cache.query({ vector: qVec, topK: 1 });

if (near && near.score >= 0.95) {
  return near.metadata.answer;        // HIT — no retrieval, no LLM
}

const answer = await runRagPipeline(query, qVec);
await cache.upsert({ vector: qVec, metadata: { answer } });  // learn it
return answer;

The threshold is a product decision

The similarity floor is the one dial that matters, and it is not an engineering constant — it is a risk choice. Set it high (0.97+) and you only ever reuse answers to near-identical questions; safe, lower hit rate. Set it lower and you catch more paraphrases but risk serving a confidently adjacent answer to a subtly different question. For a grounded support agent I keep it conservative, because a wrong cache hit undoes the entire zero-hallucination guarantee.

Invalidation is the catch

A cached answer is a snapshot of the documentation at the moment it was generated. When the knowledge base changes, stale entries become a liability — they will happily serve last month's instructions. The clean fix is to tag every cache entry with the corpus version it was derived from and drop the whole cache on re-index. The cache is cheap to rebuild; serving a confidently outdated answer is not.

Semantic caching is the rare optimisation that improves cost and latency at once — you are not making the model faster, you are skipping it entirely for questions you have already answered.

This sits in front of the edge-native pipeline and respects the grounding contract — a cache hit is only valid if the original answer was grounded. It is the kind of trade-off I weigh on every system I ship: the cheapest, safest win is usually the work you can avoid doing at all, and knowing where that line sits is most of the job.

~/keep-reading

Yaseen Khatib · AI Architect

Ships autonomous AI products solo — five in the last twelve months. More about Yaseen →

Need an engineer who can build this?

I'm Yaseen Khatib — a Senior Full-Stack AI Engineer (MERN + TypeScript) who ships production AI systems solo. Open to senior and lead roles, remote or on-site.

Get in touch →See what I've shipped

Originally published at yaseenkhatib.streamerosai.com/blog/semantic-caching-edge-rag/.

One Architect + Claude + MCP = A Full Engineering Squad: The Operating Model I'd Install at Your Company

Yaseen Khatib — Sat, 19 Sep 2026 08:56:19 +0000

[ EXECUTIVE TEARDOWN // TL;DR ]

The operating model has three layers: an architect owning contracts and review, Claude Code running against the real repo, and MCP servers giving the model governed access to Postgres, the browser, and Git.
It replaces the mechanical middle of feature work — scaffolding, wiring, consistency — which is most of a product team's payroll.
Judgment is not replaced; it becomes the hire that matters: schema, trust boundaries, and adversarial review of generated work.
A 30-day installation plan: write CLAUDE.md constitutions, wire MCP read-only first, automate the worst chore, then measure cycle time publicly.

Here is the uncomfortable math most engineering leaders haven't run yet: a large share of a product team's payroll goes to translation work — turning decided architecture into typed code, writing the CRUD nobody argues about, keeping three layers consistent with each other. That work is now automatable to a degree that changes staffing math. This post is the exact operating model I use — one architect directing Claude through MCP — and what installing it inside a company looks like.

How does one architect replace a full engineering squad?

My setup has three layers. At the top, me: owning the data contracts, the trust boundaries, and the review. In the middle, Claude — not as a chat window, but as Claude Code running against the real repository with a maintained CLAUDE.md covering the conventions, the architecture, and the things it must never do. At the bottom, MCP servers that give the model governed hands: Postgres for real schema and data, Playwright for driving and verifying the actual UI, filesystem and Git for the codebase itself.

The result is that a single instruction — "add cursor-based pagination to the orders API and update every consumer" — executes across database, backend, frontend, and tests in one coordinated pass, with the model reading real schema over MCP instead of hallucinating it, and verifying its own work in a real browser before I review.

What this replaces — and what it doesn't

Replaced: the mechanical middle of feature work — scaffolding, wiring, consistency maintenance, test boilerplate, migration chores. This was most of the payroll.
Amplified: the architect. Decisions land in production the same day they are made, because there is no handoff chain to traverse.
Not replaced: judgment. Someone still decides what the schema is, where the trust boundary sits, and whether the generated diff is actually correct. That someone is the hire that matters now.

Installing this at a company: the 30-day version

This is what I would do in my first month inside a team that hasn't operationalized AI yet:

Week 1 — write the constitution. A CLAUDE.md per repo: architecture, conventions, forbidden patterns, verify commands. This single file is the difference between an AI that helps and an AI that vandalizes.
Week 2 — wire MCP to the real systems. Read-only Postgres first, then the design system, then the browser. Governed access beats copy-pasted context by an order of magnitude.
Week 3 — pick the worst recurring chore (migrations, test backfill, dependency upgrades) and automate it end-to-end as a proof.
Week 4 — measure. Cycle time on the automated lane versus the manual lane, in front of the team. Adoption follows evidence, not mandates.

Companies do not have an AI-model problem — every vendor sells the same models. They have an operating model problem. The winners are the ones with an architect who has already run this system in production, on their own products, with their own money on the line.

I have. Every product on this site was built under exactly this model.

~/keep-reading

Yaseen Khatib · MERN + AI Architect

Ships autonomous AI products solo — five in the last twelve months. More about Yaseen →

Need an engineer who can build this?

I'm Yaseen Khatib — a Senior Full-Stack AI Engineer (MERN + TypeScript) who ships production AI systems solo. Open to senior and lead roles, remote or on-site.

Get in touch →See what I've shipped

Originally published at yaseenkhatib.streamerosai.com/blog/one-architect-claude-mcp-full-squad/.

A WebSocket reconnect state machine for React and Node

Yaseen Khatib — Sat, 19 Sep 2026 08:56:17 +0000

[ EXECUTIVE TEARDOWN // TL;DR ]

Model reconnection as four explicit states; ad-hoc booleans end with two sockets open at once.
Add full jitter to exponential backoff, otherwise every client reconnects in unison after a restart.
An open socket can still be dead; heartbeat both ends and use terminate rather than close for an unresponsive peer.
Reconnecting restores the pipe, not the missed data; send a last-seen event id and let the server replay.

Every real-time feature starts the same way: open a socket, handle messages, ship it. Then a laptop lid closes, a server deploys, a train goes into a tunnel, and you discover that reconnection is most of the work.

Reconnect logic written as a handful of booleans — isConnecting, hasReconnected, shouldRetry — always ends up with a state nobody planned for, usually two sockets open at once. It is worth writing as an explicit state machine on the first day.

Four states, and only four

        connect()          open
IDLE ─────────────▶ CONNECTING ─────▶ OPEN
 ▲                      │              │
 │                      │ error        │ close
 │                      ▼              ▼
 └────────────────  WAITING ◀──────────┘
      give up / stop     (backoff timer)

IDLE — nothing open, nothing scheduled.
CONNECTING — a socket exists but has not opened.
OPEN — usable.
WAITING — closed, with a timer scheduled to try again.

The rule that prevents nearly every bug: a transition may only happen from the state that owns it. A close event arriving while in WAITING is ignored, because that close belongs to a socket already abandoned. Without that check, a slow close event schedules a second reconnect and you get two sockets, then four.

Backoff, and why jitter is not optional

Retrying immediately in a loop is how a client turns a brief server hiccup into an outage. Exponential backoff spaces attempts out:

const BASE_MS = 500;
const MAX_MS = 30_000;

function delayFor(attempt: number) {
  const exponential = Math.min(MAX_MS, BASE_MS * 2 ** attempt);
  // Full jitter: pick anywhere in [0, exponential].
  return Math.random() * exponential;
}

The jitter matters more than the exponent. When a server restarts, every connected client is disconnected at the same instant. Without jitter they all back off by the same amount and reconnect in unison, hammering the server the moment it comes back — the thundering herd. Randomising the delay spreads them out, and it costs one line.

Heartbeats, because "open" lies

A socket in the OPEN state is not necessarily alive. If the network drops without a clean close — a dead router, a sleeping phone — the socket stays open until the OS eventually gives up, which can take minutes. The user sees a UI that looks connected and never updates.

Both ends need a heartbeat. Server side, ws gives you the primitives:

const HEARTBEAT_MS = 30_000;

wss.on("connection", (socket) => {
  socket.isAlive = true;
  socket.on("pong", () => { socket.isAlive = true; });
});

setInterval(() => {
  for (const socket of wss.clients) {
    if (!socket.isAlive) {
      socket.terminate();   // not close(): the peer is already gone
      continue;
    }
    socket.isAlive = false;
    socket.ping();
  }
}, HEARTBEAT_MS);

terminate() rather than close() is deliberate. close() starts a closing handshake with a peer that is not answering, so the socket lingers.

Browsers cannot send pings from JavaScript, so the client side is an application-level timer: if no message of any kind has arrived in HEARTBEAT_MS * 2, assume the connection is dead and close it yourself, which drops you into WAITING and triggers the normal reconnect path.

The React side

The socket belongs in a ref, not in state. Its status belongs in state, because the UI genuinely needs to re-render when it changes.

type Status = "idle" | "connecting" | "open" | "waiting";

function useSocket(url: string) {
  const [status, setStatus] = useState<Status>("idle");
  const socketRef = useRef<WebSocket | null>(null);
  const attemptRef = useRef(0);

  useEffect(() => {
    let disposed = false;
    let timer: number | undefined;

    const connect = () => {
      setStatus("connecting");
      const socket = new WebSocket(url);
      socketRef.current = socket;

      socket.onopen = () => {
        attemptRef.current = 0;   // reset backoff only on a real open
        setStatus("open");
      };

      socket.onclose = () => {
        if (disposed || socketRef.current !== socket) return; // stale event
        setStatus("waiting");
        timer = window.setTimeout(connect, delayFor(attemptRef.current++));
      };
    };

    connect();
    return () => {
      disposed = true;
      window.clearTimeout(timer);
      socketRef.current?.close();
    };
  }, [url]);

  return { status, send: (data: unknown) => socketRef.current?.send(JSON.stringify(data)) };
}

Two details carry most of the correctness. socketRef.current !== socket discards events from sockets you have already replaced. And the attempt counter resets on open, not on connecting — otherwise a connection that opens and immediately fails resets the backoff every time and you are back to hammering.

Resuming, not just reconnecting

Reconnecting gets the pipe back. It does not get the missed data back, and for anything stateful that gap is visible to the user.

The cheap version: have the client remember the last event id it processed and send it on reconnect, so the server can replay from there.

socket.onopen = () => socket.send(JSON.stringify({ resumeFrom: lastEventId }));

The server keeps a bounded buffer of recent events per channel — a few hundred is usually plenty — and replays anything newer. If the requested id has fallen out of the buffer, say so explicitly and let the client fetch a fresh snapshot over HTTP instead of pretending it is up to date.

That last part is the one people skip, and it is the one that produces long-lived, silently stale UIs.

What to show the user

Status deserves to be visible, but not loudly. connecting and waiting in the first few seconds are normal and showing a red banner for them trains people to ignore banners. Wait until you have been out of open for five seconds or so before saying anything, then be specific: "Reconnecting…" while in WAITING, and an explicit "Disconnected — retry" once you have given up.

A state machine makes that trivially expressible, which is the last argument for writing one: the UI copy maps one-to-one onto states you already have.

~/keep-reading

Yaseen Khatib · MERN + AI Architect

Ships autonomous AI products solo — five in the last twelve months. More about Yaseen →

Need an engineer who can build this?

I'm Yaseen Khatib — a Senior Full-Stack AI Engineer (MERN + TypeScript) who ships production AI systems solo. Open to senior and lead roles, remote or on-site.

Get in touch →See what I've shipped

Originally published at yaseenkhatib.streamerosai.com/blog/websocket-reconnect-state-machine-react-node/.

Serverless local-first settings sync over LAN with Automerge + mDNS

Yaseen Khatib — Sat, 19 Sep 2026 01:45:50 +0000

Why local-first LAN sync for settings?

Local-first keeps data on the user’s machines, works without the internet, and removes the need for cloud services. For settings, the data is small but impacts UX everywhere. Restricting sync to the LAN uses free transports and gives immediate convergence when devices are on the same network. CRDTs (Automerge) take the sting out of concurrent edits, and mDNS covers discovery without a bootstrap service.

How do you replicate app settings over LAN without a server?

Advertise a service with mDNS (DNS-SD) so peers on the LAN can find each other. Each peer listens on a small TCP port. When a peer shows up, connect and exchange Automerge sync messages, then persist the document locally. Because Automerge guarantees convergence, devices can drop off or power down at any time without risking consistency.

High level:

Each device holds the full CRDT document (settings).
Advertise/browse a service: _app-settings._tcp with a docId and deviceId.
Connect peers over TCP; run Automerge’s sync protocol until there’s no more to send.
Persist the doc snapshot locally and rehydrate on boot.

How does Automerge sync work over arbitrary transports?

Automerge emits compact binary sync messages you can send over any byte stream (TCP, WebRTC, BLE). Keep a SyncState per peer. On receive, pass the message to Automerge; it updates both the document and that peer’s SyncState. Keep generating messages for that peer until Automerge returns null.

Key API shape (Automerge 2.x):

init(), change(), save(), load()
initSyncState(), generateSyncMessage(doc, syncState), receiveSyncMessage(doc, syncState, msg)

Code example: Node + TypeScript mDNS + TCP sync service

The example below is a LAN-sync sidecar you can run alongside a desktop shell or embed in a Node service. It uses bonjour-service for mDNS/DNS-SD and net for TCP. The service is advertised with a shared docId, and peers initiate connections deterministically to prevent connection storms.

// src/lan-sync.ts
import fs from 'node:fs'
import net from 'node:net'
import crypto from 'node:crypto'
import Bonjour from 'bonjour-service'
import * as Automerge from '@automerge/automerge'

// ---- Types ----
type Settings = {
  version: number
  prefs: {
    theme: 'light' | 'dark'
    accent: string
    shortcuts: Record<string, string>
  }
}

// ---- Config ----
const SERVICE_TYPE = 'app-settings' // becomes _app-settings._tcp local
const DOC_FILE = 'settings.amrg'
const DOC_ID = process.env.DOC_ID ?? 'settings-v1' // all devices for this user share this
const DEVICE_ID = loadOrCreateId('.device-id')
const PORT = 0; // ephemeral

// Optional pre-shared secret for LAN encryption/auth
const PRESHARED = process.env.LAN_SECRET // undefined -> plaintext
const KEY = PRESHARED ? crypto.createHash('sha256').update(PRESHARED).digest() : undefined

// ---- Automerge state ----
let doc: Automerge.Doc<Settings> = loadDoc(DOC_FILE) ?? Automerge.from<Settings>({
  version: 1,
  prefs: { theme: 'light', accent: '#4f46e5', shortcuts: {} },
})

// Per-socket SyncState
const peerStates = new Map<net.Socket, Automerge.SyncState>()

// ---- TCP server ----
const server = net.createServer((socket) => {
  setupSocket(socket)
})
server.listen(PORT, () => {
  const address = server.address()
  if (address && typeof address !== 'string') {
    advertise(address.port)
    browse(address.port)
    console.log(`LAN sync listening on ${address.port}`)
  }
})

function setupSocket(socket: net.Socket) {
  socket.setNoDelay(true)
  peerStates.set(socket, Automerge.initSyncState())

  // Immediately drive sync for this peer
  drainSync(socket)

  let buf = Buffer.alloc(0)
  socket.on('data', (chunk) => {
    buf = Buffer.concat([buf, chunk])
    while (buf.length >= 4) {
      const len = buf.readUInt32BE(0)
      if (buf.length < 4 + len) break
      const frame = buf.subarray(4, 4 + len)
      buf = buf.subarray(4 + len)
      const payload = KEY ? openBox(frame, KEY) : new Uint8Array(frame)
      if (!payload) return socket.destroy() // auth fail

      const state = peerStates.get(socket)!
      const { doc: newDoc, syncState: newState } = Automerge.receiveSyncMessage(doc, state, payload)
      doc = newDoc
      peerStates.set(socket, newState)
      persist()

      // Respond with any messages Automerge wants to send now
      drainSync(socket)
    }
  })

  socket.on('close', () => peerStates.delete(socket))
  socket.on('error', (e) => console.warn('peer error', e.message))
}

function drainSync(socket: net.Socket) {
  let state = peerStates.get(socket)!
  while (true) {
    const msg = Automerge.generateSyncMessage(doc, state)
    if (!msg) break
    state = Automerge.initSyncStateFrom(state) // keep type, though generate returns updated via receive
    peerStates.set(socket, state)

    const payload = KEY ? sealBox(msg, KEY) : Buffer.from(msg)
    const frame = Buffer.alloc(4 + payload.length)
    frame.writeUInt32BE(payload.length, 0)
    Buffer.from(payload).copy(frame, 4)
    socket.write(frame)
  }
}

// Broadcast local change entrypoint you can call from your app
export function applyLocalChange(mutator: (d: Settings) => void) {
  const next = Automerge.change(doc, mutator)
  if (next !== doc) {
    doc = next
    persist()
    // Nudge all peers
    for (const s of peerStates.keys()) drainSync(s)
  }
}

// ---- mDNS advertise/browse ----
let bonjour: Bonjour | null = null
function advertise(port: number) {
  bonjour = new Bonjour()
  bonjour.publish({
    name: `settings-${DEVICE_ID}`,
    type: SERVICE_TYPE,
    port,
    txt: { deviceId: DEVICE_ID, docId: DOC_ID, v: '1' },
  })
}

function browse(port: number) {
  const browser = bonjour!.find({ type: SERVICE_TYPE })
  browser.on('up', (service) => {
    const txt = service.txt as any
    if (!txt || txt.docId !== DOC_ID || txt.deviceId === DEVICE_ID) return

    // Deterministic initiator: larger deviceId dials
    if (DEVICE_ID < txt.deviceId) {
      const host = (service.addresses.find(a => a.includes('.')) || service.host || service.fqdn)
      const peerPort = service.port
      const socket = net.connect(peerPort, host, () => setupSocket(socket))
    }
  })
}

// ---- Persistence ----
function persist() {
  const bin = Automerge.save(doc)
  fs.writeFileSync(DOC_FILE, Buffer.from(bin))
}

function loadDoc(path: string) {
  if (!fs.existsSync(path)) return undefined
  const buf = fs.readFileSync(path)
  return Automerge.load<Settings>(new Uint8Array(buf))
}

function loadOrCreateId(path: string) {
  if (fs.existsSync(path)) return fs.readFileSync(path, 'utf8').trim()
  const id = crypto.randomUUID()
  fs.writeFileSync(path, id)
  return id
}

// ---- Minimal secretbox using tweetnacl ----
import nacl from 'tweetnacl'
function sealBox(msg: Uint8Array, key: Buffer) {
  const nonce = crypto.randomBytes(24)
  const box = nacl.secretbox(new Uint8Array(msg), nonce, new Uint8Array(key))
  return Buffer.concat([nonce, Buffer.from(box)])
}
function openBox(frame: Buffer, key: Buffer): Uint8Array | null {
  const nonce = frame.subarray(0, 24)
  const box = frame.subarray(24)
  const m = nacl.secretbox.open(new Uint8Array(box), new Uint8Array(nonce), new Uint8Array(key))
  return m ?? null
}

Notes:

TCP framing is a simple length prefix.
Deterministic dialing prevents duplicate connections.
Keep a stable DOC_ID per user or silo; one document can host multiple logical namespaces (prefs, feature flags, etc.).
For production, add backoff, timeouts, and SIGINT cleanup for Bonjour.

How do you secure peer-to-peer LAN sync without a server?

Use a pre-shared secret to derive a symmetric key and encrypt Automerge messages with XChaCha20-Poly1305 (secretbox). Gate peers using TXT records (docId/version) and drop any frame that fails decryption. Rotate secrets per user or org. If you need stronger guarantees, derive keys via QR-paired ECDH and pin device IDs.

Minimal hardening steps:

Require LAN_SECRET on both peers; forbid plaintext in production builds.
Include docId and a protocol version v in the TXT record; ignore mismatches.
If necessary, reject connections across subnets; mDNS is link-local by default.

React/Electron: using the LAN-sync sidecar from UI

Most apps will forward local mutations to the sidecar and let Automerge take care of replication. A thin hook is enough:

// src/useSettings.ts (renderer)
import { useEffect, useState, useCallback } from 'react'
import type { Settings } from './types'
import { ipcRenderer } from 'electron'

export function useSettings() {
  const [settings, setSettings] = useState<Settings | null>(null)

  useEffect(() => {
    ipcRenderer.invoke('settings:get').then(setSettings)
    const sub = (_: any, next: Settings) => setSettings(next)
    ipcRenderer.on('settings:updated', sub)
    return () => ipcRenderer.off('settings:updated', sub)
  }, [])

  const update = useCallback((patch: Partial<Settings['prefs']>) => {
    ipcRenderer.invoke('settings:update', patch)
  }, [])

  return { settings, update }
}

Main process wires that to the Automerge sidecar’s applyLocalChange:

// src/main-ipc.ts
import { ipcMain } from 'electron'
import { applyLocalChange, getDoc } from './lan-sync-adapter' // thin wrapper exporting doc snapshot

ipcMain.handle('settings:get', () => getDoc())
ipcMain.handle('settings:update', (_evt, patch) => {
  applyLocalChange(d => {
    Object.assign(d.prefs, patch)
  })
})

Operational caveats and testing

mDNS is link-local; cross-VLAN paths need relays or unicast DNS-SD. Some consumer Wi‑Fi gear filters multicast.
Windows firewalls often default-block inbound; ship a clear prompt.
Sleep/wake churn: re-browse on network changes and re-advertise on IP changes.
Use a monotonic clock for logs only; Automerge does not depend on clocks.

Smoke test:

Start the sidecar on two machines on the same SSID.
Flip theme on A; observe near-instant update on B.
Kill A; update on B; restart A; they should converge immediately on reconnect.

What about conflicts, migrations, and schema?

Automerge treats conflicts as normal: concurrent writes to prefs.shortcuts merge as a map. For lists or counters, use the CRDT types provided (lists, counters). For migrations, include a version field; when you bump it, run a deterministic transformation inside a change. It’s just another change, so each peer applies it exactly once and they converge.

Example migration:

version 1 -> 2: split "theme" into {mode, accent}
Gate with if (doc.version === 1) inside a change block.

Tradeoffs

Concern	mDNS + TCP + Automerge
Infra cost	Zero (no server)
Discovery	Automatic on LAN; brittle across VLANs
Security	PSK acceptable on LAN; can evolve to ECDH pairing
Consistency	Strong eventual via CRDTs
Complexity	Low-medium; you own the transport

Production checklist

Backpressure and partial writes on TCP sockets
Rate-limit advertise/browse; debounce re-connections
Persist snapshots plus periodic incremental saves
Metrics: peer count, message sizes, convergence latency
Feature-flag to disable LAN sync for regulated environments

With these pieces in place, you get a solid, serverless, local-first settings sync that works when devices share a network and disappears when they don’t, without waking anyone up.