Forem: ackermannQ

I built a Load Balancer from Scratch - Every Request Is a Lie

ackermannQ — Wed, 04 Mar 2026 19:24:34 +0000

Why a Load Balancer Looks Simple (Until It Breaks)

This is a Layer 7 (application layer) load balancer. It operates at the HTTP level — it understands requests, URLs, headers, and status codes. A Layer 4 load balancer works at the TCP level: it forwards raw bytes without knowing what protocol is inside. L7 is slower (it has to parse HTTP) but smarter (it can route based on path, retry on 5xx, health check via GET /health). Everything in this project — routing decisions, health checks, retry logic — depends on understanding HTTP.

A load balancer does one thing: receive a request, pick a backend, forward it. In the happy path, it's ~20 lines of code. The complexity comes when things fail — and things always fail.

This is not a tutorial. It's what I learned building one from scratch with Node.js and zero dependencies.

Step 1: The Reverse Proxy

A reverse proxy sits between the client and the backend. The client talks to the proxy, the proxy talks to the backend. The client never knows the backend exists.

Client  -->  Load Balancer (:8080)  -->  Backend (:3001)
Client  <--  Load Balancer (:8080)  <--  Backend (:3001)

The naive way to build this: receive the full request body, forward it to the backend, receive the full response, send it back. That means buffering everything in memory.

But Node gives you streams. req is a Readable, res is a Writable. With pipe(), data flows through the proxy chunk by chunk — the load balancer never holds the full body in memory. Two pipes make a proxy:

req.pipe(proxyReq) — client body flows to the backend
proxyRes.pipe(res) — backend response flows to the client

That's it. That's the whole proxy.

I used http.request() instead of fetch() because it exposes raw streams. fetch() buffers the body in memory. For a proxy handling large payloads, that's the difference between constant memory and a memory leak.

A couple things caught me off guard. http.request() returns a Writable (the outbound request), but the response comes through a callback, not a return value. You have to think in two separate channels: the pipe going out, and the callback coming back.

And if you forget to handle the error event on proxyReq? Node throws. Your load balancer dies on the first backend failure lmao.

Step 2: Round Robin

Instead of hitting the same backend every time, rotate through all of them.

Request 1 --> Backend 3001
Request 2 --> Backend 3002
Request 3 --> Backend 3003
Request 4 --> Backend 3001  (wraps around)

An index, a modulo, done:

index = 0

getNextBackend():
  backend = backends[index]
  index = (index + 1) % backends.length
  return backend

Why not random? Random is probabilistic — over 6 requests you might get 4 on one backend and 0 on another. Round-robin guarantees uniform spread. It's also debuggable: you can trace which backend got which request just by counting.

Where it falls apart

Round-robin assumes all backends are identical. Same CPU, same memory, same response time. That's often not true.

If backend 3001 takes 500ms per request and 3002 takes 10ms, round-robin still sends them equal traffic. Requests pile up on the slow one, latency spikes, and you're only as fast as your slowest node. Weighted round-robin or least-connections would handle this — but that's a different project.

There's also no session affinity. If a user's session state lives on backend 3001, the next request might go to 3002. Stateless backends solve this. Sticky sessions (hash the client IP to always route to the same backend) would too.

And no awareness of load. A backend at 95% CPU still gets its regular turn. Least-connections would naturally shift traffic away.

For this project, the backends are identical and stateless, so none of this matters yet. But in production, round-robin is usually the starting point, not the answer.

One thing worth noting about concurrency

Node is single-threaded. The event loop processes one callback at a time. So currentIndex can never be read and written concurrently — no race condition.

But it's still mutable shared state. In Go or Java, the same code would need a mutex. This works by accident in Node and breaks silently when you port it.

Step 3: Retry on Failure

With the basic proxy + round-robin, killing one backend kills 1 out of 3 requests. The client gets nothing — just a hang or a connection reset.

I tested it. Kill backend 3001, send a request that round-robins to it. The client hangs forever. No error, no fallback, nothing.

So the retry logic needs to be inside the request flow, not before it. You can't pre-filter dead backends — you only discover failure when you try.

I went recursive:

tryNextBackend(backendsToTry, req, res):
    if backendsToTry is empty → 502 Bad Gateway

    backend = backendsToTry.shift()
    proxyReq = http.request(backend, ...)

    proxyReq.on('error') → tryNextBackend(rest, req, res)

    req.pipe(proxyReq)

Each incoming request gets a fresh copy of the backend list, ordered by round-robin starting index. On failure, the function calls itself with one fewer backend. When the list is empty → 502.

Why recursive and not a for loop? http.request() is callback-based. The error handler triggers the next attempt. The call stack mirrors the retry chain. It just maps naturally.

I messed up the state

My first attempt used a Set<Backend> on the class to track which backends had been tried. Problem: it's shared across all concurrent requests. Two clients hitting the load balancer at the same time would corrupt each other's retry state.

The fix: pass backendsToTry as a parameter. Each request gets its own copy via [...this._backends]. No shared mutable state, no bug.

How round-robin and retry work together

The backend list isn't just a copy — it's rotated to start at the current round-robin index:

backends = [3001, 3002, 3003], currentIndex = 1

backendsToTry = [3002, 3003, 3001]  // starts at index 1, wraps around

First attempt follows round-robin distribution. Retries go through the remaining backends in order.

What works now: backend down → instant retry, client sees nothing. All backends down → clean 502. Round-robin still distributes evenly.

What's missing: a backend that accepts the connection but never responds will still hang forever. ECONNREFUSED is fast failure. A slow backend is silent failure. That's next.

Architecture Decision Log

Decision	Why
Recursive retry over iterative	Natural fit with callback-based `http.request()`
Backend list as parameter, not class state	Avoids shared mutable state between concurrent requests
Max retries = number of backends	Try each backend exactly once, no more
502 when all retries exhausted	Standard HTTP status for "gateway got no valid response"

Step 4: Timeout

ECONNREFUSED is the easy case. Backend is dead, error is instant, retry kicks in. But what about a backend that accepts the connection and just... sits there?

Without a timeout, the load balancer hangs forever. The client waits. The proxy waits. Nobody times out. This is worse than a crash — it's silent.

The fix is simple: setTimeout → proxyReq.destroy() after 2 seconds. destroy() triggers the error event, so the existing retry handler picks it up. One retry path, not two.

I fell into a trap here though. My first attempt called _tryNextBackend() both in the setTimeout and in the error handler. But destroy() triggers error. So the retry ran twice — skipping a backend entirely. Same class of bug as Step 3: I also stored the timer as this._timeout (class property), which meant concurrent requests overwrote each other's timers. Both fixes are the same — keep it local, keep it per-request.

In practice, with a 5s-slow backend and a 2s timeout:

Request 3 → hits 3001 (slow) → 2.0s timeout → retry → 3002 → 0.1s
            Total: ~2.1s  (would have been 5s+ without timeout)

The client never waits more than timeout + one normal response.

Step 5: Health Checks

Retry works. But it's reactive. Every time a backend is down, the first request that hits it pays the cost: a timeout (2s) or a connection error before retrying. With 3 backends and 1 down, a third of all requests eat a 2-second penalty before getting a real response.

The obvious fix: stop routing traffic to backends we already know are broken.

But "health checking" isn't one thing. It's two, and they solve different problems.

Type	When it runs	What it does
Passive	During the request flow	Marks a backend unhealthy immediately on failure
Active	Background timer (`setInterval`)	Probes backends with `GET /health` to detect recovery

The passive check is the fast path. A backend times out or returns ECONNREFUSED → mark it unhealthy right there in the error handler. No delay, no interval to wait for. The next request skips it immediately.

The active check is the recovery path. A HealthChecker class sends GET /health to every backend every 5 seconds. Backend responds 200 → marked healthy again, back in rotation.

The active health check is the only way back. A backend marked unhealthy by the passive check stays unhealthy until the active checker confirms it's alive. No automatic forgiveness. You have to prove you're back.

Filtering unhealthy backends

The request handler builds a rotated backend list (for round-robin), then filters:

backendsToTry = [...backends.slice(idx), ...backends.slice(0, idx)]
                .filter(b => b.healthy)

If the filtered list is empty → 503 Service Unavailable. Not 502. The distinction matters:

502 Bad Gateway: I tried a backend and it gave me garbage
503 Service Unavailable: I have no backend to try at all

Three traps I fell into

Killing the health checker on error. My first version called this._stop() inside the http.get error handler. One backend down → the entire health checker stops. No more probes, no recovery detection. Every unhealthy backend stays unhealthy forever. The health checker must keep running especially when backends are failing. That's literally its job.

Losing the timer reference. setInterval() returns a reference you need for clearInterval() later. I stored it in a local variable inside start() — invisible to stop(). Fix: class property (private _timeout). This is the inverse of the Step 4 trap. There, the timer had to be local (one per request). Here, it has to be a class property (one per health checker instance). Same primitive, opposite scoping. Context decides.

No error handler on http.get. http.get() to a dead backend emits an error event. No listener → Node throws → process crashes. The health checker, whose job is to detect dead backends, was killing the entire load balancer when it found one. Fix: .on('error', ...). Mark unhealthy, log it, move on.

Architecture Decision Log

Decision	Why
Passive + active over active-only	Passive reacts in real-time; active handles recovery. Different failure timescales need different mechanisms
Active check = only recovery path	Prevents flapping — a backend must prove it's healthy, not just stop failing
503 over 502 for empty backend list	Semantically correct: no backend available vs. bad backend response
Health check interval = 5s	Frequent enough to detect recovery quickly, infrequent enough to not flood failing backends

Step 6: Graceful Shutdown

process.exit() kills everything. In-flight requests get dropped mid-response. The client sees a connection reset. If this happens during a deploy — where you stop the old process and start a new one — users get errors on every release.

What you actually want: stop accepting new work, finish what's in progress, then exit.

SIGTERM/SIGINT received
  1. server.close()         → stop accepting new connections
  2. healthChecker.stop()   → stop polling backends
  3. wait for active connections to drain (res.on('finish'))
  4. process.exit(0)        → clean exit

server.close() is the key. It tells Node to stop accepting new TCP connections, but existing connections stay alive. The callback fires when the last one closes.

Tracking active connections

server.close() knows when all TCP connections are done, but HTTP keep-alive means a TCP connection can outlive a request. So you need to track requests, not connections:

createServer callback → activeConnections++
res.on('finish')      → activeConnections--

The finish event fires when the last byte has been flushed to the OS. Not when the client receives it — when the server is done writing. That's the right boundary.

I decremented too early

My first version put the activeConnections-- right after calling _tryNextBackend():

_tryNextBackend(backendsToTry, req, res)
this._activeConnections--    // WRONG: runs immediately

But _tryNextBackend is async — it starts an http.request and returns. The decrement runs before the backend even responds. The counter hits 0 while requests are still in-flight.

The fix: res.on('finish', ...). The event fires at the right time no matter how many retries or timeouts happen along the way.

The safety net

What if a request never finishes? Stuck backend, a client that never reads the response, a keep-alive connection that hangs open. server.close() would wait forever.

setTimeout(() => {
    process.exit(1)
}, 10000)

10 seconds, then force exit with code 1. Should never trigger in normal operation, but it guarantees the process eventually dies. Exit code 1 tells the process manager this wasn't clean.

Per-request logging

Replaced all console.log / console.error with a log(level, message) function. Format: [ISO timestamp] [LEVEL] message. Not a library, just a function. Consistent formatting, descriptive call sites, greppable by level.

Every request gets logged with method, path, backend, status code, and duration:

[2025-01-15T14:32:01.123Z] [INFO] GET /api/users → localhost:3002 200 12ms
[2025-01-15T14:32:01.456Z] [WARN] GET /api/users → 503 (no backends) 0ms

The tricky part: duration has to survive retries. If a request times out on backend 3001 (2s), then succeeds on 3002 (10ms), the logged duration should be ~2010ms — the total time the client waited, not just the last hop.

The fix: capture startTime = Date.now() once at request arrival, pass it through _tryNextBackend() as a parameter. Same pattern as the backendsToTry list — per-request state that travels with the retry chain, not shared on the class.

Request arrives               → startTime = Date.now()
  → try 3001 (timeout 2s)    → startTime unchanged
  → try 3002 (success 10ms)  → log: "GET /api → 3002 200 2012ms"

Two log levels: INFO for successful proxied requests, WARN for 503s (no backends). Errors during proxy (timeouts, connection failures) get ERROR but don't produce a request log — they trigger a retry, and the final outcome (success or 503) is what gets logged.

Both SIGTERM (process managers, Docker, Kubernetes) and SIGINT (Ctrl+C) trigger the same shutdown() function. The function lives in index.ts, not in the class — process lifecycle is the entry point's responsibility, not the server's. This matters more than it sounds. It's what made the whole thing testable later.

Step 7: Testing — Making It Not Suck to Refactor

All the test scenarios from Steps 1-6 were manual. Start backends, start the load balancer, curl, kill a process, curl again. That works. Until you refactor something and need to re-verify everything by hand. You can't run curl-based tests in CI. You can't catch regressions.

So I wanted to automate all of it. But there was a problem.

The constructor did too much

The original LoadBalancer constructor did everything at once: created the HTTP server, called .listen(), started the health checker, registered process.on('SIGTERM'). You couldn't even instantiate a LoadBalancer without it grabbing a port and installing signal handlers.

Same with HealthChecker — the constructor called this.start(), so setInterval was ticking the moment you created the object.

Think about what that means for tests. You can't create a load balancer without a free port. You can't control when the health checker starts polling. Calling stop() would process.exit() — killing the test runner. And you definitely can't run 5 test suites in the same process when each one fights over ports and signal handlers.

Constructor configures. Methods activate.

That's the whole fix.

Before (untestable):
  constructor() → creates server + listen() + start health checker + signal handlers

After (testable):
  constructor() → creates server (not listening), stores config
  start()       → listen() + health checker start, returns Promise
  stop()        → server.close() + health checker stop, returns Promise (no process.exit)

HealthChecker: constructor stores _backends and _interval. start() is public, reads from them. No auto-start.

LoadBalancer: constructor creates the server but doesn't .listen(). start() returns a Promise<void> that resolves when ready. stop() returns a Promise<void> — no process.exit().

index.ts: signal handlers move here. await lb.stop() then process.exit(0). The class manages the server. The entry point manages the process.

Why Promises?

.listen() and .close() take callbacks. Wrapping them in Promises lets tests await lb.start() and know the server is actually ready before sending requests. Without this, you're racing against the OS binding the port.

The test suites

node:test (built-in) + tsx for TypeScript. Zero dependencies.

Each suite gets its own port range so nothing collides:

Suite	LB Port	Backend Ports	What it verifies
Round-robin	9100	9101-9103	Uniform distribution across 6 requests
Failover	9200	9201-9203	Traffic redirected when one backend dies
Health recovery	9300	9301-9302	Backend returns to rotation after restart
All down → 503	9400	9401-9402	503 when nothing is listening
Graceful shutdown	9500	9501	ECONNREFUSED/ECONNRESET after `stop()`

Each suite has its own before / after. Start everything, run the test, tear everything down. Full isolation.

The health recovery test is the interesting one

It tests the interaction between passive and active health checks across time:

Kill a backend → send a request (passive check marks it unhealthy)
Wait 500ms (health checker confirms it's down)
Restart the backend on the same port
Wait 500ms (health checker detects recovery via GET /health)
Send requests → the recovered backend is back in rotation

Health check interval is 200ms in this test (vs 5s in prod). Fast enough that the whole thing runs in about a second. Slow enough to not be flaky.

Step 8: Load Testing — The Numbers

Integration tests prove correctness. Load tests prove you didn't break performance in the process. I used autocannon — same idea as ab or wrk, but it's Node-native so I could script it programmatically.

The setup

5 scenarios, 10 seconds each, 10 concurrent connections (unless noted). Backends return a tiny JSON response with no processing delay. Everything runs on localhost — so network latency is zero. This isolates the proxy overhead.

The results

Scenario	Req/sec	p50	p99
Direct backend (baseline)	~28,000	0ms	1ms
Through LB (3 healthy backends)	~10,600	0ms	2ms
1 backend killed mid-test	~11,000	0ms	1ms
1 slow backend (500ms delay)	~59	0ms	503ms
100 concurrent connections	~590	1ms	528ms

What the numbers say

The proxy costs ~62% throughput. Direct to backend: 28k req/s. Through the LB: 10.6k. That's the cost of an extra HTTP hop — http.request() + pipe() + headers copy + timeout setup. For a learning project with zero optimization, that's expected. NGINX does this with kernel-level socket tricks and connection pooling. We're doing it in userland JS.

Failover is invisible to the client. Killed a backend mid-test. Zero errors, zero non-2xx. The passive health check marks it dead instantly, retry kicks in, next request skips it. Throughput didn't even drop — if anything it went slightly up because 2 fast backends is still plenty for 10 connections.

One slow backend poisons everything. This is the round-robin problem from Step 2 in practice. With one backend taking 500ms per request, throughput drops from 10,600 to 59 req/s. A 180x degradation. Round-robin keeps sending it a third of the traffic, and those requests block for 500ms each. The 2s timeout doesn't help because 500ms is within the limit — the backend isn't failing, it's just slow. Least-connections would naturally shift traffic away from the slow one.

100 connections still works, but p99 suffers. At 100 concurrent connections (10x the normal test), throughput scales to 590 req/s but p99 jumps to 528ms. That's the slow backend again — with more connections, more requests are queued behind the slow one. The event loop stays healthy (Node handles concurrency fine), but the slow backend becomes a bottleneck that affects the entire tail latency.

Zero errors across all scenarios. No timeouts, no non-2xx, no connection resets. The retry logic, health checks, and graceful shutdown all work under load. That's the real validation — not that the happy path works, but that the failure handling holds up when you're actually pushing traffic through.

Obviously this doesn't cover real network latency (everything is localhost), large payloads (tiny JSON), or CPU-bound backends (ours do zero work). NGINX and Envoy handle all of that and more. But for understanding the fundamentals — proxy overhead, failover behavior, how a slow backend poisons round-robin — the numbers tell the story.

Shadow Execution: The Refactor Miracle That Doesn’t Touch Production

ackermannQ — Mon, 02 Feb 2026 15:42:02 +0000

I Ran the New Logic as a Ghost and Measured Exactly When It Lied

TL;DR: I deleted 400 lines of legacy code in production without touching a single user. The secret? Running the new logic as a "shadow" that computes decisions but never executes them — then comparing what it would have done vs what actually happened.

The Problem Nobody Talks About

You've been there. Legacy code that works. Kinda. You understand it. Mostly. And your PM wants you to "just refactor it real quick."

// The code that haunts my dreams
export const processFile = async (file) => {
  const existing = await getExistingFile(file.id)  // Side effect #1

  if (shouldUpload(file, existing)) {              // Decision buried in here
    await deleteFile(existing)                      // Side effect #2
    await uploadFile(file)                          // Side effect #3
    await updateMetadata(file)                      // Side effect #4
  }

  return file
}

Four side effects. Decision logic mixed with execution. And if you get it wrong?

Wrong upload: Duplicate files, corrupted knowledge base
Wrong skip: Missing data, users screaming "where's my file?"
Wrong delete: Gone. Forever. Have a nice day.

So you write tests. Great.

But here's the thing: tests cover cases you imagine. Production has cases that exist.

The Idea That Changed Everything

What if you could run your new code on real production traffic — but never actually do anything?

Real request ──┬──▶ [Old Code] ──▶ Actually does things ──▶ User happy
               │        │
               │        ▼
               └──▶ [New Code] ──▶ Computes result ──▶ Compare ──▶ Log
                         │
                    (no side effects!)

This is shadow execution. Not traffic mirroring (that's an infra thing). This is behavior comparison at the code level.

The new code runs as a ghost. It thinks. It decides. But it never acts.

Step 1: The Decision Contract

Here's the mindset shift that makes this work.

Before: Your function returns void or some mutated object. Good luck comparing that.

After: Your function returns a decision — a serializable description of what should happen.

// This is the magic: a typed contract of "what I would do"
type SyncDecision = {
  version: 1                          // For schema evolution
  action: 'skip' | 'upload' | 'replace'
  reason: 'file-not-found' | 'file-already-synced' | 'file-content-changed'
  expectedStatus: 'newly-synced' | 'already-synced'
  fileKey?: string                    // Where to store it
  fileToDelete?: string               // What to delete first
  tagsToApply?: Record<string, string>
}

Why is this powerful?

It's serializable — You can log it, replay it, diff it
It's deterministic — Same input = same output
It's comparable — Two decisions can be meaningfully compared
It's executable — A separate "applier" can turn it into reality

The decision doesn't do anything. It just describes the intention.

Step 2: Separate Decide from Execute

This is where the refactor actually happens.

Before (tangled):

export const processFile = async (file) => {
  const existing = await getExistingFile(file.id)

  // Decision and execution mixed together
  if (!existing) {
    await uploadFile(file)        // <-- side effect!
    await updateMetadata(file)    // <-- side effect!
    return { ...file, status: 'newly-synced' }
  }

  return { ...file, status: 'already-synced' }
}

After (separated):

// Step 1: Pure decision function (no side effects)
export const computeDecision = (ctx: DecisionContext): SyncDecision => {
  if (!ctx.existingFile) {
    return {
      version: 1,
      action: 'upload',
      reason: 'file-not-found',
      expectedStatus: 'newly-synced',
      fileKey: `${ctx.integration.alias}:${ctx.file.path}`,
      tagsToApply: {
        externalId: ctx.file.id,
        integrationName: ctx.integration.name,
      },
    }
  }

  return {
    version: 1,
    action: 'skip',
    reason: 'file-already-synced',
    expectedStatus: 'already-synced',
  }
}

// Step 2: Applier (all side effects here)
export const applyDecision = async (decision: SyncDecision, ctx: ApplyContext) => {
  if (decision.action === 'skip') {
    return { ...ctx.file, status: 'already-synced' }
  }

  if (decision.action === 'replace' && decision.fileToDelete) {
    await ctx.fileRepository.delete(decision.fileToDelete)
  }

  await ctx.transferApi.upload(ctx.file, decision.fileKey!)
  await ctx.fileRepository.updateTags(decision.tagsToApply!)

  return { ...ctx.file, status: 'newly-synced' }
}

Now the interesting part: shadow only calls computeDecision. Never applyDecision.

Step 3: The Shadow Executor

Here's where the comparison happens:

const executeShadow = async (ctx: DecisionContext) => {
  // LIVE: The real decision (will be applied)
  const liveDecision = computeDecisionV1(ctx)

  // Actually do the thing
  await applyDecision(liveDecision, ctx)

  // SHADOW: The new decision (fire-and-forget, non-blocking)
  setImmediate(async () => {
    try {
      const shadowDecision = computeDecisionV2(ctx)

      // Compare them
      const result = compare(
        normalize(liveDecision),
        normalize(shadowDecision)
      )

      if (!result.match) {
        logDivergence(result)
      }
    } catch (err) {
      // Shadow NEVER blocks live — fail silently
      console.warn('Shadow failed:', err.message)
    }
  })

  return liveDecision
}

Key rules:

Live runs first. Always.
Shadow is async. Fire-and-forget.
Shadow errors are swallowed. Live must never be affected.

Step 4: Normalization (This Is Where It Gets Real)

Naive comparison doesn't work:

// This will fail even for identical decisions
JSON.stringify(live) === JSON.stringify(shadow)  // false!
// Why? Tag ordering, timestamps, property order...

You need to normalize before comparing:

const normalize = (decision: SyncDecision): NormalizedDecision => {
  const normalized = {
    action: decision.action,
    reason: decision.reason,
    expectedStatus: decision.expectedStatus,
    fileKey: decision.fileKey,
    fileToDelete: decision.fileToDelete,
  }

  // Sort tags alphabetically, exclude timestamps
  if (decision.tagsToApply) {
    const sortedTags: Record<string, string> = {}
    const keys = Object.keys(decision.tagsToApply).sort()

    for (const key of keys) {
      // Skip volatile fields
      if (['syncedAt', 'updatedAt', 'createdAt'].includes(key)) continue
      sortedTags[key] = decision.tagsToApply[key]
    }

    normalized.tagsToApply = sortedTags
  }

  return normalized
}

We compare intentions, not implementations. Tag order doesn't matter. Timestamp values don't matter. What matters: would the user see the same result?

Step 5: Severity Model (The Part That Makes It Actionable)

Not all divergences are equal:

const classifyDivergence = (field: string, live: any, shadow: any): Divergence => {
  // CRITICAL: Different user-visible behavior
  if (field === 'action') {
    return {
      field,
      severity: 'critical',
      impact: describeActionImpact(live, shadow),
      liveValue: live,
      shadowValue: shadow,
    }
  }

  // WARNING: Different data, but not catastrophic
  if (field === 'fileKey') {
    return { field, severity: 'warning', impact: 'File stored with different key' }
  }

  // INFO: Debug signal, no user impact
  if (field === 'reason') {
    return { field, severity: 'info', impact: 'Different reasoning, same outcome' }
  }

  // WARNING: Unknown field — be conservative!
  return { field, severity: 'warning', impact: `Unknown field "${field}" — needs classification` }
}

const describeActionImpact = (live: string, shadow: string): string => {
  if (live === 'skip' && shadow === 'upload') {
    return 'Shadow would UPLOAD a file that live SKIPs — potential missing file bug'
  }
  if (live === 'upload' && shadow === 'skip') {
    return 'Shadow would SKIP a file that live UPLOADs — potential duplicate prevention'
  }
  if (live === 'skip' && shadow === 'replace') {
    return 'Shadow would DELETE and re-upload a file that live SKIPs — data loss risk!'
  }
  return `Action changed from ${live} to ${shadow}`
}

Now your logs tell a story:

{
  "event": "shadow_divergence",
  "traceId": "shadow-abc123",
  "fileId": "gdrive-xyz",
  "overallSeverity": "critical",
  "divergences": [{
    "field": "action",
    "liveValue": "skip",
    "shadowValue": "replace",
    "severity": "critical",
    "impact": "Shadow would DELETE and re-upload a file that live SKIPs — data loss risk!"
  }]
}

The Moment of Truth (Real Story)

First day of shadow execution at 1% sampling. I'm checking logs during coffee.

┌────────────────────────────────────────────────────────────────┐
│ FILE: /Finance/Q4-Budget-Final.xlsx                            │
│                                                                │
│ LIVE decision:   skip   (file already synced)                  │
│ SHADOW decision: replace (delete existing, re-upload)          │
│                                                                │
│ IMPACT: Shadow would have DELETED a production file            │
│         then re-uploaded — data loss if upload fails           │
└────────────────────────────────────────────────────────────────┘

Coffee comes out my nose.

What happened: The new implementation had stricter checksum logic. It detected a hash mismatch that the old code ignored.

The twist: Shadow was technically correct. But we didn't want to fix that legacy bug during migration. Different concern, different PR.

What we did: Added a tolerance rule in the normalizer for this specific case. Documented it. Created a backlog item for the actual fix.

What would have happened without shadow: The new code would have deleted production files on day one. Users would have lost data. I would have lost my job.

The Rollout Playbook

Shadow execution isn't one-and-done. It's a progression:

Phase 1: Capture (Before You Have New Code)

updateShadowConfig({ mode: 'capture', samplingRate: 0.1 })

Just log inputs. No comparison. Build a corpus of real production data for offline testing.

Phase 2: Compare at 1%

updateShadowConfig({
  mode: 'compare',
  samplingRate: 0.01,
  circuitBreaker: { enabled: true, failureThreshold: 5 }
})

Run for 1-2 weeks. Target: <5% divergence rate, 0 critical issues.

Phase 3: Progressive Rollout

Sampling	Duration	Target
10%	1 week	<2% divergence
25%	1 week	<1% divergence
50%	1 week	<0.5% divergence
100%	1 week	<0.1% divergence

Phase 4: The Swap

updateShadowConfig({ mode: 'shadow-live' })

Invert the roles. New code becomes live. Old code becomes shadow (safety net). If something goes wrong: disableShadowExecution() — instant rollback.

Phase 5: Cleanup

Delete old code. You've earned it.

The Gotchas That Will Bite You

Gotcha 1: The Clock

// BAD: Non-deterministic
if (file.expiresAt < new Date()) { ... }

// GOOD: Inject the clock
const decide = (ctx: { file: File, now: Date }) => {
  if (ctx.file.expiresAt < ctx.now) { ... }
}

Gotcha 2: Object Key Ordering

// These are "different" in JSON.stringify
{ a: 1, b: 2 }
{ b: 2, a: 1 }

// Solution: Sort keys in normalizer
Object.keys(tags).sort()

Gotcha 3: Cache State

Live and shadow might see different cache states. Solution: pre-fetch everything in the orchestrator and pass it as input to both.

Gotcha 4: Rate Limiting at 100%

At 100% sampling, you'll see thousands of the same divergence. Add deduplication:

const seenSignatures = new Map<string, number>()

const shouldLog = (signature: string): boolean => {
  const now = Date.now()
  const lastSeen = seenSignatures.get(signature)

  if (lastSeen && now - lastSeen < 3600_000) return false  // 1 hour

  seenSignatures.set(signature, now)
  return true
}

Gotcha 5: Shadow Must Never Escalate Privileges

Shadow should use read-only clients. If it accidentally calls a write API, it should throw.

const shadowClients = {
  fileRepository: createReadOnlyProxy(fileRepository),
  transferApi: createNoOpProxy(transferApi),  // throws on write
}

Why Not Just Tests?

I get this a lot.

Tests	Shadow
Fast feedback	Slow feedback
Controlled inputs	Real inputs
Validates intent	Validates equivalence
Cases you imagine	Cases that exist

They're complementary:

Unit Tests → Integration Tests → Shadow Execution → Canary → GA
     ↑                                    ↑
   "Does it work?"              "Does it behave the same?"

Tests tell you "this code does X." Shadow tells you "this code does the same X as the old code."

The Mindset Shift

Before shadow execution, I thought refactoring production code required:

Perfect tests (impossible)
Staging environment that matches prod (never)
Courage (bad strategy)

Now I think:

"We validate behavioral equivalence, not correctness."

We're not asking "is the new code right?" We're asking "does it behave the same?"

That's a much easier question to answer. And once you know it behaves the same, you can deploy with confidence.

Key Takeaways

Decision Contract is everything — A serializable, comparable, versionable type that describes "what would happen"
Separate Decide from Execute — Decision function has zero side effects. Applier does all the work. Shadow only calls the decision function.
Normalize before comparing — Sort arrays, exclude timestamps, compare intentions not implementations
Severity makes metrics actionable — "action differs" is critical. "reason differs" is info.
Fire-and-forget is non-negotiable — Shadow must never block, never fail, never slow down live
Progressive rollout — 1% → 10% → 50% → 100% → swap
Divergences are bugs — Treat them seriously. Fix before swap.

The Code

Full implementation available as a reference:

sync-queue/
├── file-decision.ts       # Pure decision function
├── file-applier.ts        # Side effects execution
├── shadow/
│   ├── shadow-executor.ts # Core orchestration
│   ├── shadow-normalizer.ts # Comparison logic
│   ├── shadow-config.ts   # Sampling, circuit breaker
│   └── shadow-reporter.ts # Logging & metrics
└── __tests__/
    └── file-decision.test.ts

Final Thought

The best refactors are the ones where nothing changes for users.

Shadow execution lets you prove that "nothing changed" — with data, not hope.

Go delete some code. Safely.

Have questions? Found a bug in my approach? Let me know in the comments.

LLMs Did Not Replace You. They Replaced Your Excuses

ackermannQ — Thu, 15 Jan 2026 13:35:33 +0000

Your organization treats code output as progress.
Your organization rewards speed and calls it seniority.

That belief used to feel safe.
LLMs turned it into a liability.

This is not about juniors losing jobs.
This is about seniors losing cover.

The belief competent teams are proud of

"We ship fast because we are good."

That sentence used to signal excellence.
Today, it hides risk.

Before LLMs, effort was visible.
Typing speed created friction.
Friction forced thinking.

Now output is cheap.
Suspiciously cheap.

A prompt becomes a diff.
A diff becomes a merge.
A merge becomes production.

Everyone feels productive.
Almost no one feels responsible.

What LLMs actually removed

LLMs did not remove engineering jobs.
They removed the last requirement to understand what you ship.

You no longer need to know why something works.
You only need to recognize that it looks right.

That is not correctness.
That is plausibility.

Plausible code compiles.
Plausible code passes tests.
Plausible code fails users quietly.

Most teams already tolerated this.
LLMs just multiplied the volume.

Code review became theater

Every team says they have standards.
Most teams mean templates.

Templates do not encode judgment.
They encode repetition.

When repetition becomes the quality bar, review collapses.

"LGTM" stops meaning I understand this.
It starts meaning I do not want to slow things down.

Silence becomes approval.
Approval becomes liability.

This is not a tooling problem.
It is a system design problem.

The hidden dependency no one names

Your delivery process depends on ownership.
Your organization optimized it away.

Responsibility is spread until it disappears.
No single person must fully understand a change for it to ship.

That worked when code was expensive.
It fails when code is free.

After the incident, everyone asks the same question.

How did this get approved.

The answer is always the same.
Quiet. Distributed. Nobody.

Do not blame the wrong thing

Do not blame the junior who pasted the output.
They followed the incentives.

Do not blame the model.
It did exactly what you asked.

Look at what actually changed.

The bottleneck is no longer writing code.
It is reading code.

If you cannot read unfamiliar code deeply, you cannot evaluate AI output.
If you cannot evaluate it, you cannot approve it responsibly.

Approving without understanding is not leadership.
It is negligence at scale.

What matters more now, not less

System design matters more because implementation is cheap.
Communication matters more because diffs are larger.
Domain knowledge matters more because outputs are generic.
Problem decomposition matters more because prompts are vague.

None of this is new.
What is new is that you can no longer hide from it.

LLMs reward teams with discipline.
They punish teams that outsourced thinking to process.

The uncomfortable career truth

Staying relevant is not about learning the next model.
It is about being the person who prevents bad decisions from shipping.

That person does not compete on output.
They compete on responsibility.

They can explain tradeoffs without rereading the diff.
They can name failure modes before users do.
They can say no when something works but is wrong.

If your career plan is "use AI better", you are late.

The real question is whether you are still practicing engineering.

Which parts of your delivery process allow unknown decisions to reach production, and who decided that was acceptable?

I Generated Code 10x Faster and Got Worse at My Job

ackermannQ — Wed, 14 Jan 2026 16:46:56 +0000

TL;DR

I used to measure my productivity by how fast I could generate code. Then I realized I was optimizing for the wrong metric.

The trap: LLMs make code generation nearly free. But faster code generation ≠ better problem-solving. The bottleneck isn't typing-it's reasoning.

The reality: I was shipping more features but accumulating technical debt faster. The code looked perfect, but I didn't always understand what I was building.

The shift: Value comes from understanding what to build, why to build it that way, and what will break when you do. LLMs can't do that reasoning for you.

I've been using LLMs in my daily workflow for over two years. At first, I was amazed. I could scaffold a new API endpoint in minutes instead of hours. I could generate test cases, refactor modules, and write boilerplate at speeds that felt superhuman.

My productivity metrics looked incredible. I was shipping more features, closing more tickets, and generating more code than ever before.

But something felt off.

I was moving fast, but I wasn't sure I was moving in the right direction. I was generating code quickly, but I wasn't always confident I understood what I was building. I was shipping features, but I was also accumulating technical debt faster than I could pay it down.

The Wake-Up Call

The moment I realized I had a problem was during a code review. A teammate asked me why I'd chosen a particular approach for handling pagination. I stared at the code—code I'd generated with ChatGPT just two days earlier—and realized I couldn't explain the decision.

The code worked. It passed tests. It looked professional. But I had no idea why I'd made certain choices. I'd just accepted whatever the LLM suggested because it looked right.

That's when I understood: I was mistaking speed for skill, generation for understanding, and output for impact.

A Real Example: The Pagination Incident

Last month, I was asked to "add pagination to the user list endpoint." I opened ChatGPT, pasted the request, and got 50 lines of clean, working code in 30 seconds. I tested it locally—it worked! I opened a PR in 20 minutes.

By naive metrics, I was incredibly productive. But here's what I didn't consider:

The endpoint was used by three different clients (web dashboard, mobile app, admin tool). Adding pagination meant all three needed updates.
The current endpoint was cached at the CDN. With pagination, cache effectiveness would drop because each page is a separate cache entry.
I didn't investigate why pagination was needed. Was the list slow to load? Was the client having trouble rendering? Different problems, different solutions.

A week later, I spent three hours fixing issues I'd created. The mobile app broke because it wasn't expecting pagination metadata. The caching strategy became ineffective. And I still hadn't solved the actual performance problem.

If I'd spent 30 minutes understanding the problem first, I would have written less code, but it would have been the right code.

What Actually Changed

LLMs compressed feedback loops, not cognitive work.

Before LLMs:

Finding information: 30-45 minutes
Typing boilerplate: 15-20 minutes

After LLMs:

Finding information: 2-5 minutes
Typing boilerplate: 1-2 minutes

The loops are faster. But faster loops don't mean no loops. They don't mean you can skip understanding, judgment, verification, or responsibility.

Before LLMs: The bottleneck was often access to information.
After LLMs: The bottleneck is knowing what information to trust and how to apply it.

The skill that matters now isn't finding answers—it's evaluating answers, asking the right questions, and understanding context deeply enough to know when the AI is wrong.

The Illusion of Understanding

Here's the most dangerous trap: LLMs generate code that looks like it was written by someone who understands the problem. The code is well-structured, follows conventions, includes error handling, has comments. It looks professional.

This creates an illusion of understanding. If the code looks right, it's easy to assume it is right. You skim the PR, run the tests, merge it. Only later do you discover that it doesn't handle the edge case, or violates an implicit invariant, or makes assumptions that don't hold in production.

I've been there. I've merged code that looked perfect, only to debug it at 2 AM when it broke in production. The problem wasn't the code—it was that I didn't understand what the code was actually doing.

The Thinking That Matters

Effective developers operate in a cycle: understand → hypothesize → implement → verify → reflect.

LLMs short-circuit this cycle by jumping straight to implementation.

Understanding: What is the actual problem? Not the stated problem, the actual problem. When someone says "the dashboard is slow," is it slow queries? Inefficient rendering? Too much data? This requires investigation—profiling, tracing, reading code. An LLM can help, but it can't do the investigation itself.

Hypothesizing: Based on your understanding, what might fix it? This is where experience matters. An LLM can suggest solutions, but it can't prioritize them based on your specific context. It doesn't know that your database is already IO-bound, or that your team struggles with cache invalidation.

Implementing: This is where LLMs excel. Once you know what to build, they can help you build it quickly. But "quickly implementing the right thing" is very different from "quickly implementing something."

Verifying: Does it actually work? Not "does it compile," but "does it solve the problem?" An LLM can generate tests, but it can't tell you if the tests are meaningful. It can't catch the subtle bug that only appears in production with 10,000 concurrent users.

Reflecting: What did you learn? Why did this solution work (or not work)? An LLM has no memory of this iteration. Every conversation starts fresh. It can't learn from your mistakes. You can.

This cycle is where reasoning lives. LLMs can accelerate the implementation step, but they can't replace the rest of the cycle. And the rest of the cycle is where the value is created.

What This Means for Your Career

If your value as a developer came primarily from knowing syntax, remembering API signatures, or typing fast, then yes, your value has decreased.

But if your value comes from understanding systems, making trade-offs, debugging complex issues, designing solutions, and knowing your domain, then your value is higher than ever. You can now move faster through the mechanical parts and spend more time on the parts that actually matter.

The gap between mediocre and excellent work might be widening. If you use LLMs as a crutch, you'll ship faster but learn slower. If you use them as an accelerator, you'll both ship faster and deepen your expertise.

My Framework Now

Before generating code, I ask myself:

Do I understand the problem? Not just the stated problem, but the actual problem. What's the root cause? What are the constraints?
Do I know what I want to build? Can I explain it clearly to a colleague? If not, I need to think more, not generate more.
Am I using the LLM for mechanical work or thinking? Boilerplate, syntax, repetitive patterns—good. Problem-solving, architecture, critical business logic—risky.
Can I explain why this code works? If I can't explain it, I don't understand it. And if I don't understand it, I can't maintain it.
What happens when this breaks? Will I be able to debug it at 2 AM? Will I understand the failure modes?

The rule: If I can't confidently answer these questions, I slow down. I think more. I generate less.

The Bottom Line

LLMs are powerful tools. They can generate syntactically correct code in seconds. But they can't understand your infrastructure, your constraints, or your operational requirements.

Use AI to accelerate implementation, but maintain ownership of the reasoning.

The code that looks perfect might have subtle bugs that only become obvious when you understand systems deeply. And most importantly: if you can't explain why the code works, don't ship it.

Speed is not the same as skill. Faster code generation doesn't make you a better developer—better reasoning does.

What's your experience with the productivity illusion? Have you caught yourself optimizing for speed over understanding? Share your thoughts in the comments below!

If you found this useful, I've documented this and other frameworks for working with LLMs strategically in my book, "Being a Software Developer After LLMs". It covers how to use LLMs as accelerators without losing your engineering edge.

AI generated correct garbage

ackermannQ — Tue, 13 Jan 2026 15:14:59 +0000

TL;DR

I asked ChatGPT to generate rate limiting code. It gave me 50 lines that looked perfect.

Three weeks later, it cost us 14 engineering hours and nearly took down production.

The AI-generated code had 5 critical flaws:

Memory leak (infinite growth)
Lost state on restart
Multi-server failure (12x limit bypass)
Wrong client identification (load balancer IP)
No observability

Lesson: Review AI code with production context in mind, not just syntax. Use the framework at the end of this post.

I've been working with LLMs in production for the past few years, and I've seen both the power and the pitfalls of AI-assisted development. Last month, we had a production incident that perfectly illustrates why you can't just copy-paste AI-generated code—even when it looks perfect.

Here's what happened, what we learned, and how you can avoid the same mistakes.

The Problem

Our API was getting hammered. What looked like a DDoS attack was actually legitimate traffic, but we needed rate limiting fast. I asked ChatGPT to generate a rate limiter, and it gave me code that looked perfect:

from flask import Flask, request
from functools import wraps
from time import time

app = Flask(__name__)

# Simple rate limiter
rate_limit_store = {}

def rate_limit(max_requests=100, window=60):
    def decorator(f):
        @wraps(f)
        def decorated_function(*args, **kwargs):
            client_ip = request.remote_addr
            current_time = time()

            if client_ip not in rate_limit_store:
                rate_limit_store[client_ip] = []

            # Clean old requests
            rate_limit_store[client_ip] = [
                req_time for req_time in rate_limit_store[client_ip]
                if current_time - req_time < window
            ]

            if len(rate_limit_store[client_ip]) >= max_requests:
                return {"error": "Rate limit exceeded"}, 429

            rate_limit_store[client_ip].append(current_time)
            return f(*args, **kwargs)
        return decorated_function
    return decorator

@app.route('/api/chat')
@rate_limit(max_requests=100, window=60)
def chat_endpoint():
    # Handle chat request
    pass

The code was clean, well-structured, and followed best practices. It had error handling, clear logic, and would pass code review in many organizations. I reviewed it quickly and merged it.

The code worked fine for the first few days—we had low traffic, and the rate limiter seemed to be functioning. But as traffic increased and we scaled to more servers, we started seeing issues. Three weeks after deployment, we had production incidents that required 14 hours of debugging to resolve.

What Went Wrong

After 14 hours of debugging, we discovered the AI-generated code had 5 critical flaws that weren't obvious from reading it:

1. Memory Leak

The rate_limit_store dictionary grows infinitely. Every unique IP address creates a new entry that never gets cleaned up. After a week of production traffic, we'd have millions of entries consuming gigabytes of RAM.

# This grows forever - no cleanup mechanism
rate_limit_store = {}

2. Lost State on Restart

The in-memory store means rate limits reset every time we deploy. An attacker could simply wait for our daily deployment window and bypass all limits.

3. Multi-Server Failure

We run 12 API servers behind a load balancer. Each server has its own rate_limit_store, so a client can make 1,200 requests per minute (100 × 12 servers) instead of 100.

4. Wrong Client Identification

request.remote_addr gives you the load balancer's IP, not the client's IP. Every request looked like it came from the same source, making the rate limiter completely ineffective.

# This gets the load balancer IP, not the real client
client_ip = request.remote_addr

5. No Observability

Zero logging, zero metrics. We had no way to know if legitimate users were hitting limits or if the rate limiter was even working.

The Fix

After identifying the actual constraints, here's what we built. Here are the key changes:

1. Shared State with Redis

Before: In-memory dictionary (lost on restart, separate per server)

rate_limit_store = {}  # Problem: separate per server, lost on restart

After: Redis with TTL (shared across servers, persists through deploys)

import redis
redis_client = redis.Redis(host='redis', decode_responses=True)

key = f"rate_limit:{identifier}:{limits['tier']}"
pipe = redis_client.pipeline()
pipe.incr(key)
pipe.expire(key, limits['window'])  # Auto-cleanup via TTL
current_requests, _ = pipe.execute()

2. Correct Client Identification

Before: Gets load balancer IP

client_ip = request.remote_addr  # Wrong: gets load balancer IP

After: Extracts real client IP from header

def get_client_identifier():
    """Extract true client IP from X-Forwarded-For header"""
    if request.headers.get('X-Forwarded-For'):
        return request.headers.get('X-Forwarded-For').split(',')[0].strip()
    return request.remote_addr

3. Tiered Rate Limiting

Before: Same limit for everyone

max_requests=100  # Same for all users

After: Different limits based on customer tier

def get_rate_limit_tier(api_key):
    if not api_key:
        return {'requests': 100, 'window': 60, 'tier': 'anonymous'}
    tier_info = get_customer_tier(api_key)
    return {
        'requests': tier_info.get('rate_limit', 1000),  # Paid customers get more
        'window': 60,
        'tier': tier_info.get('plan', 'paid')
    }

4. Observability

Before: No logging or metrics

# Silent failure - no way to know what's happening

After: Structured logging for monitoring

logger.warning(
    f"Rate limit exceeded",
    extra={
        'identifier': identifier,
        'tier': limits['tier'],
        'requests': current_requests,
        'limit': limits['requests'],
        'endpoint': request.path
    }
)

Summary of changes:

Redis for state: Shared state across all servers, persists through deploys, automatic cleanup via TTL
Tiered rate limiting: Different limits for anonymous users, paid customers, enterprise clients
Correct client identification: X-Forwarded-For header with fallback
Atomic operations: Redis pipeline ensures race conditions can't bypass limits
Observability: Structured logging for monitoring and alerting
Better error messages: Include retry_after so clients know when to retry

💡 Key Takeaway: AI generates code that works in isolation but fails in production because it doesn't understand your infrastructure, constraints, or operational requirements.

What We Learned

This experience taught us three critical lessons:

1. AI Generates Code That Looks Correct But Misses Production Realities

The AI-generated code followed patterns, had error handling, and looked professional. But it didn't understand:

Our infrastructure (12 servers behind a load balancer)
Our operational requirements (persistence, observability)
Our business constraints (different limits for different customers)

The code worked in isolation but failed in production.

2. The "Boring" Code Is Where Bugs Live

Error handling, resource cleanup, observability—these are the "boring" parts that AI generates quickly. But they're also where most production bugs live. When you delegate this to AI without careful review, you're offloading the most critical parts.

3. You Still Need Deep Systems Understanding

LLMs can accelerate implementation, but they can't replace the reasoning that prevents disasters. You need to:

Understand your infrastructure deeply
Anticipate failure modes
Design for production, not just correctness

A Framework for Reviewing AI-Generated Code

After this incident, we developed a systematic checklist for reviewing AI-generated code:

Security Checklist

[ ] Input validation (can users inject malicious data?)
[ ] Authentication/authorization (are permissions checked?)
[ ] Sensitive data handling (is logging exposing secrets?)
[ ] SQL injection / XSS vulnerabilities

Production Readiness

[ ] Error handling (what happens when things fail?)
[ ] Resource cleanup (memory leaks, connection pools)
[ ] Observability (logging, metrics, tracing)
[ ] Performance (will this scale? N+1 queries?)

Context & Integration

[ ] Matches existing patterns (or breaks conventions?)
[ ] Uses correct libraries (or suggests deprecated ones?)
[ ] Fits architecture (or creates technical debt?)
[ ] Handles edge cases (null values, empty arrays, etc.)

Understanding

[ ] Do I understand every line?
[ ] Can I explain why this approach was chosen?
[ ] Do I know what will break if this changes?

The rule: If you can't confidently answer "yes" to all of these, don't merge it.

The Bottom Line

LLMs are powerful tools. They can generate syntactically correct code in seconds. But they can't understand your infrastructure, your constraints, or your operational requirements.

Use AI to accelerate implementation, but maintain ownership of the reasoning.

The code that looks perfect might have subtle bugs that only become obvious when you understand systems deeply. The "boring" code deserves extra scrutiny, not less.

And most importantly: if you can't explain why the code works, don't ship it.

What's your framework for reviewing AI-generated code? Share it in the comments below!

If you found this useful, I've documented this and 8 other production case studies in my book, Being a Software Developer After LLMs. It covers frameworks for working with LLMs strategically while maintaining your core engineering skills.

Building profiler0x0: An Arcade-Style GitHub Profile Analyzer That Doesn't Judge

ackermannQ — Mon, 12 Jan 2026 15:42:38 +0000

What if analyzing your GitHub profile felt like unlocking a character in an arcade game instead of staring at a leaderboard? That's the idea behind profiler0x0 🎮 - a project I built that transforms GitHub profiles into collectible arcade-style cards with developer archetypes, signal analysis, and actionable insights.

No ranking. No judgment. Just signals.

The Philosophy

Most developer profile analyzers focus on metrics that create comparison and competition. Stars, followers, contributions - they all feed into a ranking system that can feel demotivating or reductive.

profiler0x0 takes a different approach. Instead of asking "How do you compare to others?", it asks "What does your profile signal about your development style?" The result is a fun, shareable identity that celebrates different developer patterns without creating hierarchy.

The Five Signals

The core of profiler0x0 is analyzing five key signals from your GitHub activity:

🔄 Consistency

How steady is your activity pattern? We analyze update patterns across months to detect steady builders vs. bursty sprinters.

🎯 Focus

Do you maintain a few meaningful projects or explore many ideas? We measure the ratio of active vs. abandoned repositories.

🔧 Maintenance

How well do you keep projects polished? We check for READMEs, licenses, recent updates, and general repository health.

📖 Narrative

Can others understand what you build? We analyze README quality, topics, and how well you tell your project stories.

🤝 Collaboration

How much do you work with others? (Estimate only) We use forks and contributions as proxies.

Each signal is calculated from publicly available GitHub data and scored 0-100, then mapped to developer archetypes.

Developer Archetypes

Based on your signal combinations, profiler0x0 assigns you one of eight archetypes:

The Maintainer: High maintenance + consistency. Keeps projects alive past the hype.
The Silent Builder: High consistency, low narrative. Builds quietly, needs clearer story.
The Prototype Machine: Low focus, generates ideas fast. Needs more finishes.
The Specialist: High focus. Deep investment in a few domains.
The Archivist: High narrative + maintenance. Documents well, shares knowledge.
The Comeback Kid: Strong base, ready to return.
The Hype Surfer: Rides trends, can convert spikes.
The Ghost: Profile needs a flagship project.

Each archetype comes with a rarity level (Common, Rare, Epic, Legendary) based on how distinctive your signal pattern is - not how "good" it is.

The Arcade Card System

Your profile becomes a collectible card with:

Level: Calculated from account age, active repos, and quality metrics (1-50)
Stats: RPG-style attributes (GRIT, FOCUS, CRAFT, AURA) derived from signals
Perks: Unlocked based on signal thresholds (e.g., "README Master", "Long-Term Builder")
Rarity: Visual distinction based on signal patterns

Here's an example of how signals map to stats:

// GRIT: consistency + maintenance blend (endurance, reliability)
const grit = Math.round(
  (signals.consistency.score * 0.6 + signals.maintenance.score * 0.4)
);

// FOCUS: direct mapping of focus score
const focus = signals.focus.score;

// CRAFT: maintenance + narrative blend (polish, professionalism)
const craft = Math.round(
  (signals.maintenance.score * 0.6 + signals.narrative.score * 0.4)
);

// AURA: narrative + distinctiveness (visibility, presence)
const aura = Math.round(
  (signals.narrative.score * 0.7 + distinctiveness * 0.3)
);

Tech Stack

Backend

Runtime: Node.js + TypeScript
Framework: Fastify (lightweight and fast)
Testing: Vitest (113 tests: 91 unit + 16 integration + 6 validation)
Validation: Zod schemas for request/response validation
Data Source: GitHub REST API
Caching: In-memory (10min TTL)

Frontend

Framework: Next.js 15 (App Router)
UI Library: React 19
Styling: Tailwind CSS with custom arcade aesthetics
Language: TypeScript
Animations: CSS + custom neon glow effects

Architecture Highlights

Signal Calculation

Signals are computed from repository data with careful attention to edge cases:

function computeConsistency(repos: GitHubRepo[]): SignalDetails {
  if (repos.length === 0) {
    return { score: 0, label: 'none', explanation: 'No repositories', metrics: {} };
  }

  // Group updates by month
  const monthlyUpdates = new Map<string, number>();
  repos.forEach(repo => {
    const month = repo.updatedAt.substring(0, 7); // YYYY-MM
    monthlyUpdates.set(month, (monthlyUpdates.get(month) || 0) + 1);
  });

  // Calculate coefficient of variation
  const updateCounts = Array.from(monthlyUpdates.values());
  const mean = updateCounts.reduce((a, b) => a + b, 0) / updateCounts.length;
  const variance = updateCounts.reduce((sum, val) => sum + Math.pow(val - mean, 2), 0) / updateCounts.length;
  const stdDev = Math.sqrt(variance);
  const cv = mean > 0 ? stdDev / mean : 1;

  // Lower CV = more consistent = higher score
  const score = Math.max(0, Math.min(100, Math.round(100 - (cv * 50))));

  // ... label and explanation logic
}

Archetype Selection

Archetypes are selected based on signal combinations using a decision tree:

export function selectArchetype(signals: Signals): Archetype {
  const scores = {
    consistency: signals.consistency.score,
    focus: signals.focus.score,
    maintenance: signals.maintenance.score,
    narrative: signals.narrative.score,
    collaboration: signals.collaboration.score
  };

  // Ghost: Very low overall activity
  if (avgScore < 20 && maxScore < 35) {
    return createArchetype('ghost', signals, 'Low overall signal scores');
  }

  // Maintainer: High maintenance + high consistency
  if (scores.maintenance >= 65 && scores.consistency >= 60) {
    return createArchetype('maintainer', signals, 'High maintenance and consistent activity');
  }

  // ... more archetype logic
}

API Design

The API is simple and focused:

// GET /api/analyze/:username
{
  "username": "octocat",
  "profile": { "name": "...", "avatarUrl": "..." },
  "signals": {
    "consistency": { "score": 72, "label": "steady", ... },
    "focus": { "score": 65, "label": "moderate", ... },
    // ...
  },
  "archetype": {
    "id": "maintainer",
    "name": "The Maintainer",
    "rarity": "epic",
    // ...
  },
  "card": {
    "level": 18,
    "stats": { "GRIT": 81, "FOCUS": 65, "CRAFT": 78, "AURA": 72 },
    "perks": ["README Master", "Long-Term Builder"]
  },
  "tips": [
    { "title": "Add more READMEs", "why": "...", "impact": "Medium" }
  ]
}

Testing Strategy

With 113 passing tests, the project has comprehensive coverage:

Unit Tests (91): Signal calculations, archetype selection, card generation
Integration Tests (16): API routes, cache behavior, schema validation
Validation Tests (6): Username validation with helpful error messages

Example test:

describe('computeConsistency', () => {
  it('should score high for steady monthly updates', () => {
    const repos = generateReposWithMonthlyUpdates(12, 5); // 12 months, 5 updates each
    const result = computeConsistency(repos);
    expect(result.score).toBeGreaterThan(70);
    expect(result.label).toBe('steady');
  });

  it('should score low for bursty activity', () => {
    const repos = [
      ...generateReposWithMonthlyUpdates(2, 50), // 2 months with 50 updates
      ...generateReposWithMonthlyUpdates(10, 0) // 10 months with 0 updates
    ];
    const result = computeConsistency(repos);
    expect(result.score).toBeLessThan(40);
    expect(result.label).toBe('bursty');
  });
});

The UI: Arcade Aesthetics

The frontend uses Tailwind CSS with custom neon color schemes and glow effects:

/* Custom neon colors */
--neon-cyan: #00f0ff;
--neon-purple: #a855f7;
--neon-pink: #ec4899;
--neon-blue: #3b82f6;

/* Glow effects */
.shadow-neon {
  box-shadow: 0 0 20px rgba(168, 85, 247, 0.5);
}

/* Animated gradients */
.bg-gradient-to-r {
  background: linear-gradient(to right, var(--neon-cyan), var(--neon-purple));
}

The result is a retro-futuristic aesthetic that makes profile analysis feel like a game.

What I Learned

Building profiler0x0 taught me several valuable lessons:

Philosophy matters: Starting with "no ranking, no judgment" shaped every design decision and made the project more inclusive.
Signal design is hard: Creating meaningful signals from limited public data requires careful thought about what you're actually measuring.
Testing pays off: The 113 tests caught numerous edge cases and made refactoring safe.
Simple APIs win: A single endpoint (/api/analyze/:username) is easier to use and maintain than a complex REST API.
Aesthetics enhance UX: The arcade theme makes the tool more engaging and shareable.

Try It Out

You can check it out, if this resonates with you. I would love to have your feedback and improvement ideas!

Limitations & Future Work

profiler0x0 is an MVP with known limitations:

Can't see private repos or internal work
Collaboration signal is perfectible (no PR/issue data in MVP)
New accounts will have low signals (not enough data)
Optimized for open-source activity patterns

Future enhancements could include:

More sophisticated collaboration signals (PRs, issues)
Historical trend analysis
Custom archetype definitions
Export/share functionality improvements

Conclusion

profiler0x0 demonstrates that developer tools don't have to be competitive or judgmental. By focusing on signals rather than rankings, we can create tools that celebrate different development styles and help developers understand their profiles in new ways.

The arcade aesthetic makes it fun, but the real value is in the insights - actionable tips that help you level up your GitHub profile based on what you actually want to signal.

No ranking. No judgment. Just signals. 🎮

Building SandpackVM: How to build a lightweight VM

ackermannQ — Tue, 28 Oct 2025 13:58:57 +0000

TL;DR

I'm building SandpackVM, a lightweight JavaScript sandbox that lets isolated Workers call host functions safely.

This post covers how I bridged the boundary between parent ↔ worker using proxy functions, TypeScript, and async messaging - turning a hard limitation into a design pattern.

👉 Part 1 focuses on the communication bridge.

Creating a portable, composable, and observable JavaScript Virtual Machine - built with TypeScript - documenting the journey from concept to implementation.

The Problem That Started It All

When you start building something that runs untrusted code - a playground, a plugin system, a REPL - you quickly hit the same wall I did: you can't just run user code directly.

JavaScript has Workers, Node has worker_threads, but they all suffer from the same fundamental limitation: the sandbox can't call functions defined outside its world. Communication becomes message-passing, serialization... frustration.

That's where SandpackVM started - as a personal experiment to make those two worlds (host ↔ sandbox) talk seamlessly again.

The challenge I faced on day one: How do you execute code in a Worker thread while letting it call functions from the parent process?

My first approach was simple:

const worker = new Worker(code, {
  workerData: { apis: { log: console.log } }, // Functions don't serialize!
})

I thought: great, I'll just send a function and call it.

Except it doesn't work that way.

The Worker sees only serialized data - not closures, not context, not even functions. That's when I realized the real challenge wasn't "running code in isolation", but making isolated code feel connected.

Why TypeScript? Building a VM requires careful control over types, interfaces, and API boundaries. TypeScript provides compile-time safety, excellent IDE support, and ensures our public API contracts are clearly defined. Plus, it compiles to clean JavaScript that runs everywhere.

Today's Challenge: Proxying the boundary

The next step was clear: if we can't share functions, we'll fake them.
The key insight: We can't pass functions directly, but we can create proxy functions that communicate via postMessage.

Architecture Overview

Let’s peek under the hood - here’s how a simple await log("hello") call travels between worlds:

┌─────────────────────────────────────────────────────────┐
│ User Code in Worker                                     │
│   await log("hello");                                   │
│      ↓                                                  │
│   [1] Proxy function created                            │
│      ↓                                                  │
│   [2] Intercept call, postMessage to parent             │
└────────────────────┬────────────────────────────────────┘
                     │
                     ↓ postMessage
┌─────────────────────────────────────────────────────────┐
│ Parent Process (SandpackVM)                             │
│   [4] Receive message                                   │
│      ↓                                                  │
│   [3] Execute real function (console.log)               │
│      ↓                                                  │
│   postMessage result back                               │
└────────────────────┬────────────────────────────────────┘
                     │
                     ↓ postMessage
┌─────────────────────────────────────────────────────────┐
│ Worker                                                  │
│   [5] Receive result, resolve Promise                   │
│      ↓                                                  │
│   User code continues execution                         │
└─────────────────────────────────────────────────────────┘

This architecture is the beating heart of SandpackVM - simple enough to grasp, yet flexible enough to extend.

Implementation: Step by Step

At this point, SandpackVM becomes less a single script and more a protocol between host and sandbox. Let's build it up step-by-step

Step 1: Generate the Proxy Code

I write a function that dynamically generates JavaScript code for each API. For every API in this._apis, I create a proxy function:

function createWorkerURL(code: string, apis: Apis): URL {
  const apiNames = Object.keys(apis)
  const proxyDefs: string[] = []

  apiNames.forEach(name => {
    const api = apis[name]

    if (typeof api === "function") {
      // Generate an async proxy function
      const proxyCode = [
        "const " + name + " = async (...args) => {",
        "  return new Promise((resolve, reject) => {",
        "    const callId = Math.random().toString(36).substr(2, 9);",
        "    pendingCalls[callId] = { resolve, reject };",
        "    // [2] Intercept the call and send message to parent",
        "    parentPort.postMessage({",
        "      type: 'apiCall',",
        "      id: callId,",
        "      functionName: '" + name + "',",
        "      arguments: args",
        "    });",
        "  });",
        "};",
      ].join("\n")
      proxyDefs.push(proxyCode)
    }
  })

  // ... assemble the worker code
}

This generates code like:

const log = async (...args) => {
  return new Promise((resolve, reject) => {
    const callId = Math.random().toString(36).substr(2, 9)
    pendingCalls[callId] = { resolve, reject }

    parentPort.postMessage({
      type: "apiCall",
      id: callId,
      functionName: "log",
      arguments: args,
    })
  })
}

Step 2: Handle Messages in Parent

In the main run() method, we listen for API calls from the Worker:

public async run(_code: string): Promise<void> {
  return new Promise<void>((resolve, reject) => {
    const worker = new Worker(createWorkerURL(_code, this._apis!));

    // [4] Parent receives message from Worker
    worker.on("message", (msg) => {
      if (msg.type === "apiCall") {
        // [3] Execute the real function from this._apis
        const fn = this._apis![msg.functionName] as Function;

        if (!fn) {
          worker.postMessage({
            type: "apiResult",
            id: msg.id,
            error: `Function ${msg.functionName} not found`,
          });
          return;
        }

        try {
          const result = fn(...msg.arguments);
          // Send result back to Worker
          worker.postMessage({
            type: "apiResult",
            id: msg.id,
            result,
          });
        } catch (error) {
          worker.postMessage({
            type: "apiResult",
            id: msg.id,
            error: error instanceof Error ? error.message : String(error),
          });
        }
      } else if (msg.type === "done") {
        worker.terminate();
        resolve();
      }
    });
  });
}

The parent now acts as an RPC router - forwarding calls, executing real functions, and sending structured results back to the sandbox.

Step 3: Worker Receives Results

The Worker needs to listen for API results and resolve the corresponding Promises:

// [5] Listen for API results from parent
parentPort.on("message", msg => {
  if (msg.type === "apiResult") {
    if (msg.error) {
      pendingCalls[msg.id].reject(new Error(msg.error))
    } else {
      pendingCalls[msg.id].resolve(msg.result)
    }
    delete pendingCalls[msg.id]
  }
})

At this point, we have a working request/response RPC bridge inside the VM. Everything else - observability, quotas, permissions - will hang on this foundation.

Principles that emerged

As SandpackVM took shape, a few principles emerged - lessons that apply to any system trying to balance safety, control, and developer experience.

1. ⚡Asynchronicity is Non-Negotiable

Isolation demands async boundaries - it's a feature, not a bug.

Here's the first gotcha I discovered: User code must now use await with all APIs:

// ❌ This won't work (synchronous)
log("hello")

// ✅ This works (asynchronous)
await log("hello")

I initially thought this was a bug, but it's actually a feature. True isolation requires async boundaries. We're building a sandbox, not a simple wrapper.

2. 🧩 The Proxy Pattern is Your Friend

Control, observability, security, debugging - all in one abstraction

The proxy pattern allows us:

Control: I decide exactly what functions can be called
Observability: I can log all API calls before they execute
Security: I can validate arguments, enforce quotas, add rate limits
Debugging: Every call gets a unique ID for tracing

3. Promise-based Communication is Elegant

Each API call is just a Promise with a side channel:

Generate unique call ID
PostMessage to parent
Wait for response (async)
Resolve or reject

It's like RPC, but built into the VM itself.

TLDR:

Isolation ≠ disconnection. True sandboxing is about controlled bridges, not walls.
Message protocols are APIs. The format of your postMessage payload is your interface contract.
Developer experience matters even for infra code. The fewer abstractions users need to learn, the more they'll trust the sandbox.

Current Status

✅ Working:

Worker creation & execution
Proxy-based API injection
Asynchronous communication via postMessage
Basic error handling

🚧 Next Steps:

Nested APIs (apis: { fs: { readFile: ... } })
Resource quotas (CPU, memory)
Observability layer (timeline, metrics)
Cleanup & edge cases handling

What's Next?

Loop protection: detect CPU-bound tasks via heartbeats or execution quotas.
Observability: mirror console.log, exceptions, and metrics from inside the sandbox to the host.
Security hardening: disallow access to fetch, importScripts, or Node's fs when not explicitly permitted.

Where this matters in the real world

These are not theoretical - each of these scenarios demands the same thing: run arbitrary code safely, without losing flexibility - exactly what SandpackVM aims to deliver:

Interactive docs: safely run examples in-browser.
Plugin systems: allow third-party extensions without risking host crashes.
AI code agents: execute user-generated functions securely.
Education tools: give each student an isolated REPL that can't break the main app.
Dev sandboxes: run user-submitted snippets in cloud IDEs (like StackBlitz or CodeSandbox) safely

Try It Yourself

Want to follow along? The code is on GitHub . You can clone it and experiment with different API configurations:

git clone https://github.com/ackermannQ/sandpackvm
cd sandpackvm
npm install
npm run start

Parting Thoughts

This journey started with a simple question: "How do I safely run untrusted code?" and building SandpackVM reminds me why I love infrastructure work: it's invisible when it works.

Every bridge between processes, every proxy call, every message passed - each is a tiny act of empathy for the next developer who just wants things to feel simple.

That's what I'm chasing - simplicity on the other side of complexity

In Part 2, I'll tackle resource quotas and observability. What happens when someone runs an infinite loop? How do we track CPU usage in real-time? These are the questions that keep me coding into the night.

Questions or feedback? Leave a comment below. I'd love to hear your thoughts.

Q. Ackermann

Senior Engineer, Toolmaker, Systems Thinker

GitHub | KodeReview | LinkedIn

ts-typed-errors v0.5.0: From Concept to Production-Ready Error Matching

ackermannQ — Fri, 17 Oct 2025 13:07:48 +0000

TL;DR: Since my initial article, ts-typed-errors has evolved from a simple error matching library to a full-featured pattern composition system. Here's what changed.

What Changed Since v0.1.0

When I first launched ts-typed-errors, it had basic exhaustive matching. The feedback was clear: developers wanted more power and composability.

So I went back to the drawing board and implemented 5 major phases of improvements.

📊 Before & After

Metric	v0.1.0 (Initial)	v0.5.0 (Now)
Bundle Size	~2 KB	~6.4 KB
Features	4	20+
Test Coverage	15 tests	92 tests
Pattern Builders	0	11
Phases Completed	1	5

Let's dive into what's new.

Phase 1-2: The Foundations (v0.1.0 - v0.2.0)

Property Selection with `.select()`

Extract properties directly in your handler:

const NetworkError = defineError('NetworkError')<{ status: number; url: string }>();

matchErrorOf<Err>(error)
  .select(NetworkError, 'status', (status) => {
    // Handler receives just the status number
    return `HTTP ${status}`;
  })
  .exhaustive();

Why it matters: No more manual destructuring. Cleaner handlers.

Composition Utilities

// Check multiple types at once
if (isAnyOf(error, [NetworkError, TimeoutError])) {
  // Handle connection errors
}

// Combine type guards
const isServerError = isAllOf([
  isErrorOf(NetworkError),
  (e) => e.data.status >= 500
]);

Async Support

await matchErrorAsync(error)
  .with(NetworkError, async (e) => {
    await logToService(e);
    return 'logged';
  })
  .otherwise(async () => 'unknown');

Phase 3: Performance & Serialization (v0.3.0)

Error Transformation with `.map()`

Transform errors before matching:

matchError(error)
  .map(e => e.cause ?? e) // Extract root cause
  .with(NetworkError, e => `Network: ${e.data.status}`)
  .otherwise(() => 'Unknown');

Use cases:

Normalize errors from different sources
Extract nested errors
Add contextual information

O(1) Tag-Based Matching

Under the hood, ts-typed-errors now uses a Map for instant lookups:

// Before: O(n) instanceof checks
for (const c of cases) if (c.test(e)) return c.run(e);

// After: O(1) tag lookup for defineError errors
const handler = tagHandlers.get(error.tag);
if (handler) return handler(error);

Result: Faster matching for large error unions.

Error Serialization

Send errors over the wire safely:

// Serialize for API
const serialized = serialize(error);
// { tag: 'NetworkError', message: '...', data: {...}, stack: '...' }

// Send to client
res.json(serialized);

// Deserialize on client
const error = deserialize(json, [NetworkError, ParseError]);

Phase 4: Pattern Composition (v0.4.0) 🔥

This is where it gets exciting. Inspired by ts-pattern, I built a full P namespace for pattern composition.

The `P` Namespace

import { P, matchError } from 'ts-typed-errors';

`P.union()` - Match ANY Pattern

const isConnectionError = P.union(
  P.instanceOf(NetworkError),
  P.instanceOf(TimeoutError)
);

matchError(error)
  .with(isConnectionError, () => 'Retry connection')
  .otherwise(() => 'Other error');

`P.intersection()` - Match ALL Patterns

// Match NetworkError with status >= 500
matchError(error)
  .with(
    P.intersection(
      P.instanceOf(NetworkError),
      P.when(e => e.data.status >= 500)
    ),
    e => `Server error: ${e.data.status}`
  )
  .otherwise(() => 'Other');

Composable & Reusable Patterns

This is the real power:

// Define reusable patterns
const isServerError = P.intersection(
  P.instanceOf(NetworkError),
  P.when(e => e.data.status >= 500)
);

const isClientError = P.intersection(
  P.instanceOf(NetworkError),
  P.when(e => e.data.status >= 400 && e.data.status < 500)
);

const isCritical = P.union(
  isServerError,
  P.instanceOf(DatabaseError)
);

// Use patterns everywhere
function handleError(error: unknown) {
  return matchError(error)
    .with(isCritical, () => 'ALERT TEAM')
    .with(isClientError, () => 'Show user message')
    .otherwise(() => 'Log and continue');
}

Available Pattern Builders

P.instanceOf(Constructor) - Match by constructor
P.when(predicate) - Match with predicate
P.guard(guardFn) - Use type guard functions
P.union(...patterns) - Match ANY pattern (OR logic)
P.intersection(...patterns) - Match ALL patterns (AND logic)
P.not(pattern) - Negate a pattern

Phase 5: Error-Specific Patterns (v0.5.0) 🚀

Now we have patterns specifically designed for error handling scenarios.

`P.array()` - Match Array Properties

Perfect for validation errors:

const ValidationError = defineError('ValidationError')<{
  errors: Array<{ field: string; message: string }>
}>();

matchError(error)
  .with(
    P.intersection(
      P.instanceOf(ValidationError),
      P.array('errors', P.when(e => e.field === 'email'))
    ),
    () => 'Email validation failed'
  )
  .otherwise(() => 'Other validation error');

Use cases:

ValidationError with multiple field errors
AggregateError with error collections
Batch processing errors

`P.hasCause()` - Match Error Chains

Traverse the entire cause chain:

const rootCause = new NetworkError('failed', { status: 500, url: '/api' });
const middleError = Object.assign(new Error('middle'), { cause: rootCause });
const topError = Object.assign(new Error('top'), { cause: middleError });

matchError(topError)
  .with(P.hasCause(NetworkError), () => 'Network issue in chain')
  .otherwise(() => 'Other');

Why it matters: Modern JavaScript supports error causes. Now you can match on them!

`P.hasStack()` - Match by Stack Trace

Categorize errors by where they came from:

matchError(error)
  .with(P.hasStack(/internal/), () => {
    // Internal application error
    alert('Our bad! We're on it.');
  })
  .with(P.hasStack(/node_modules/), () => {
    // Third-party library error
    logToSentry(error);
  })
  .otherwise(() => {
    // Application code error
    showUserFriendlyMessage();
  });

Use cases:

Debugging and error categorization
Different handling for internal vs external errors
Stack-based error routing

`P.optional()` / `P.nullish()`

Match optional properties:

matchError(error)
  .with(P.nullish('cause'), () => 'No underlying cause')
  .with(P.optional('metadata'), () => 'Has optional metadata')
  .otherwise(() => 'Other');

Complex Composition

Combine everything:

const ValidationError = defineError('ValidationError')<{
  errors: Array<{ field: string }>
}>();

const rootCause = new NetworkError('network', { status: 500, url: '/api' });
const error = Object.assign(
  new ValidationError('validation failed', {
    errors: [{ field: 'email' }]
  }),
  { cause: rootCause }
);

matchError(error)
  .with(
    P.intersection(
      P.instanceOf(ValidationError),
      P.array('errors', P.when(e => e.field === 'email')),
      P.hasCause(NetworkError)
    ),
    () => 'Email validation failed due to network issue'
  )
  .otherwise(() => 'Other');

Real-World Use Cases

1. API Error Handling

async function fetchUser(id: string) {
  const result = await wrap(async () => {
    const response = await fetch(`/api/users/${id}`);
    if (!response.ok) {
      throw new NetworkError('Request failed', {
        status: response.status,
        url: response.url
      });
    }
    return response.json();
  })();

  if (!result.ok) {
    return matchErrorOf<ApiError>(result.error)
      .with(
        P.intersection(
          P.instanceOf(NetworkError),
          P.when(e => e.data.status === 404)
        ),
        () => null
      )
      .with(
        P.intersection(
          P.instanceOf(NetworkError),
          P.when(e => e.data.status >= 500)
        ),
        () => {
          toast.error('Server error. Please try again.');
          return null;
        }
      )
      .with(P.instanceOf(NetworkError), (e) => {
        toast.error(`Request failed: ${e.data.status}`);
        return null;
      })
      .exhaustive();
  }

  return result.value;
}

2. Form Validation

const ValidationError = defineError('ValidationError')<{
  errors: Array<{ field: string; message: string }>
}>();

function handleFormError(error: unknown) {
  return matchError(error)
    .with(
      P.array('errors', P.when(e => e.field === 'email')),
      (e) => {
        showFieldError('email', 'Invalid email address');
      }
    )
    .with(
      P.array('errors', P.when(e => e.field === 'password')),
      (e) => {
        showFieldError('password', 'Password too weak');
      }
    )
    .with(
      P.instanceOf(ValidationError),
      (e) => {
        showGeneralError('Please fix the highlighted fields');
      }
    )
    .otherwise(() => {
      showGeneralError('An error occurred');
    });
}

3. Database Error Recovery

const DatabaseError = defineError('DatabaseError')<{
  code: string;
  query: string
}>();

async function queryWithRetry(query: string, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const result = await wrap(() => db.query(query))();

    if (result.ok) return result.value;

    const shouldRetry = matchError(result.error)
      .with(
        P.intersection(
          P.instanceOf(DatabaseError),
          P.when(e => e.data.code === 'CONNECTION_LOST')
        ),
        () => true
      )
      .with(
        P.intersection(
          P.instanceOf(DatabaseError),
          P.when(e => e.data.code === 'DEADLOCK')
        ),
        () => true
      )
      .otherwise(() => false);

    if (!shouldRetry) throw result.error;

    await sleep(Math.pow(2, i) * 1000); // Exponential backoff
  }

  throw new Error('Max retries exceeded');
}

Bundle Size Impact

Despite adding 20+ features, the bundle stayed incredibly small:

Version	Features	Bundle Size	Size per Feature
v0.1.0	4	2 KB	0.5 KB
v0.5.0	20+	6.4 KB	0.32 KB

How?

Tree-shaking friendly
No external dependencies
Optimized for minification
Shared code between features

Performance Benchmarks

Tested with 1,000,000 error matches:

Tag-based matching (defineError):    ~15ms  (O(1) lookup)
instanceof matching:                 ~85ms  (O(n) iteration)
Pattern composition:                 ~95ms  (multiple tests)

Key insight: For errors created with defineError(), matching is ~5.6x faster due to tag-based O(1) lookup.

What's Next: Phase 6 (v1.0.0)

The roadmap for v1.0.0 includes:

Error Recovery Patterns

// Built-in retry, fallback, circuit breaker
matchError(error)
  .with(NetworkError, retry(3, exponentialBackoff))
  .with(ValidationError, fallback(defaultValue))
  .exhaustive();

Framework Integrations

// Express middleware
app.use(errorHandler([NetworkError, DatabaseError, ValidationError]));

// tRPC error handling
export const createContext = createTRPCContext({
  errorFormatter: tsTypedErrorsFormatter
});

Error Context Propagation

// Automatic context tracking
const { wrap } = withContext({ requestId: '123', userId: 'abc' });
const result = await wrap(riskyOperation)();
// All errors include requestId and userId

Comparison with Alternatives

vs try/catch

// try/catch: No type safety, easy to forget cases
try {
  await fetchData();
} catch (error) {
  // error is unknown
  // No compile-time guarantees
}

// ts-typed-errors: Full type safety
const result = await wrap(fetchData)();
if (!result.ok) {
  matchErrorOf<Err>(result.error)
    .with(NetworkError, ...)
    .with(ParseError, ...)
    .exhaustive(); // TypeScript enforces all cases
}

vs neverthrow

// neverthrow: Great Result type, but manual matching
import { Result, ok, err } from 'neverthrow';

const result: Result<User, NetworkError | ParseError> = ...;
result.match(
  (user) => console.log(user),
  (error) => {
    // Manual instanceof checks
    if (error instanceof NetworkError) { ... }
    else if (error instanceof ParseError) { ... }
  }
);

// ts-typed-errors: Pattern matching + exhaustiveness
const result = await wrap(fetchUser)();
if (!result.ok) {
  matchErrorOf<Err>(result.error)
    .with(NetworkError, ...)
    .with(ParseError, ...)
    .exhaustive(); // Compile error if cases missing
}

vs ts-pattern (for errors)

// ts-pattern: General-purpose pattern matching
import { match, P } from 'ts-pattern';

match(error)
  .with({ name: 'NetworkError' }, ...)
  .with({ name: 'ParseError' }, ...)
  .exhaustive();

// ts-typed-errors: Specialized for errors with type inference
matchErrorOf<Err>(error)
  .with(NetworkError, (e) => {
    // e is fully typed with data property
    e.data.status // ✅ Type-safe
  })
  .exhaustive();

When to use what:

ts-pattern: General pattern matching (objects, arrays, primitives)
ts-typed-errors: Error-specific matching with error-focused features

Community Feedback & Iterations

Based on early adopter feedback, we made several changes:

1. "P namespace is verbose"

Solution: Keep both APIs - use P for composition, direct constructors for simple cases:

// Simple case: direct constructor
matchError(error)
  .with(NetworkError, ...)
  .otherwise(...);

// Complex case: P namespace
matchError(error)
  .with(P.intersection(P.instanceOf(NetworkError), P.when(...)), ...)
  .otherwise(...);

2. "How do I match on error data?"

Solution: Added .select() and pattern composition:

// Extract specific property
.select(NetworkError, 'status', (status) => ...)

// Or match with P.when
.with(P.when(e => e instanceof NetworkError && e.data.status >= 500), ...)

3. "Need better async support"

Solution: Added dedicated async matchers with proper Promise types:

await matchErrorAsync(error)
  .with(NetworkError, async (e) => {
    await logToService(e);
    return 'handled';
  })
  .otherwise(async () => 'unknown');

Migration Guide

From v0.1.0 to v0.5.0

All existing code continues to work! We maintained backward compatibility.

But here's how to leverage new features:

// Before (v0.1.0)
matchError(error)
  .with(NetworkError, (e) => {
    if (e.data.status >= 500) {
      return 'Server error';
    }
    return 'Client error';
  })
  .otherwise(() => 'Unknown');

// After (v0.5.0) - more expressive
const isServerError = P.intersection(
  P.instanceOf(NetworkError),
  P.when(e => e.data.status >= 500)
);

const isClientError = P.intersection(
  P.instanceOf(NetworkError),
  P.not(P.when(e => e.data.status >= 500))
);

matchError(error)
  .with(isServerError, () => 'Server error')
  .with(isClientError, () => 'Client error')
  .otherwise(() => 'Unknown');

Testing Strategy

All 92 tests pass with 100% coverage:

✓ test/integration.test.ts (7 tests)
✓ test/index.test.ts (85 tests)

Test Files  2 passed (2)
Tests       92 passed (92)

Test categories:

Basic matching (15 tests)
Pattern composition (16 tests)
Error-specific patterns (19 tests)
Async matching (8 tests)
Serialization (10 tests)
Edge cases (24 tests)

Installation & Quick Start

npm install ts-typed-errors

import { defineError, matchError, P } from 'ts-typed-errors';

const NetworkError = defineError('NetworkError')<{
  status: number;
  url: string
}>();

const error = new NetworkError('Request failed', {
  status: 500,
  url: '/api/users'
});

const result = matchError(error)
  .with(
    P.intersection(
      P.instanceOf(NetworkError),
      P.when(e => e.data.status >= 500)
    ),
    (e) => `Server error: ${e.data.status}`
  )
  .otherwise(() => 'Unknown error');

console.log(result); // "Server error: 500"

Final Thoughts

From v0.1.0 to v0.5.0, ts-typed-errors evolved from "exhaustive error matching" to "composable error pattern matching system".

The journey taught me:

Listen to users - Pattern composition came from community feedback
Iterate quickly - 5 phases in a few months
Stay focused - Every feature is error-specific
Performance matters - O(1) matching was crucial
DX is everything - Great docs and examples drive adoption

What would you add to Phase 6?

Drop your thoughts in the comments! 💬

Found this useful?

⭐ Star on GitHub
🐦 Follow me on Twitter
📝 Share this article

Image credits to Milad Fakurian

Why I Built ts-typed-errors: A TypeScript Error Handling Revolution

ackermannQ — Thu, 02 Oct 2025 15:13:32 +0000

How I solved the exhaustive error matching problem that every TypeScript developer faces

The Problem: TypeScript's `unknown` Error Hell

Since TypeScript 4.4, every catch block receives an unknown type. This was a great improvement for type safety, but it created a new problem: verbose, error-prone error handling.

// ❌ The reality of modern TypeScript error handling
try {
  await riskyOperation();
} catch (error) {
  // error is unknown - we need to narrow it manually
  if (error instanceof NetworkError) {
    handleNetworkError(error);
  } else if (error instanceof ValidationError) {
    handleValidationError(error);
  } else if (error instanceof DatabaseError) {
    handleDatabaseError(error);
  } else {
    // What if we forget a case? No compile-time safety!
    handleUnknownError(error);
  }
}

This approach has several problems:

Verbose: Lots of repetitive if/else chains
Error-prone: Easy to forget error cases
No exhaustiveness: TypeScript can't ensure all cases are handled
Poor DX: No autocomplete or type safety in handlers

The Solution: Exhaustive Error Matching

I built ts-typed-errors to solve this exact problem. Here's how it works:

// ✅ Clean, exhaustive, and type-safe
import { defineError, matchErrorOf, wrap } from 'ts-typed-errors';

// Define your error types
const NetworkError = defineError('NetworkError')<{ status: number; url: string }>();
const ValidationError = defineError('ValidationError')<{ field: string; value: any }>();
const DatabaseError = defineError('DatabaseError')<{ table: string; operation: string }>();

type AppError = InstanceType<typeof NetworkError> | InstanceType<typeof ValidationError> | InstanceType<typeof DatabaseError>;

// Wrap throwing functions
const safeOperation = wrap(async () => {
  // Your risky operation here
});

// Handle errors exhaustively
const result = await safeOperation();
if (!result.ok) {
  return matchErrorOf<AppError>(result.error)
    .with(NetworkError, e => `Network error: ${e.data.status} for ${e.data.url}`)
    .with(ValidationError, e => `Invalid ${e.data.field}: ${e.data.value}`)
    .with(DatabaseError, e => `Database error in ${e.data.table} during ${e.data.operation}`)
    .exhaustive(); // ✅ TypeScript ensures all cases are covered!
}

Why This Approach is Revolutionary

1. Compile-Time Exhaustiveness 🛡️

TypeScript enforces that you handle ALL possible error cases. If you add a new error type to your union, TypeScript will error until you handle it:

type AppError = NetworkError | ValidationError | DatabaseError | NewError; // Added NewError

const result = matchErrorOf<AppError>(error)
  .with(NetworkError, handleNetwork)
  .with(ValidationError, handleValidation)
  .with(DatabaseError, handleDatabase)
  // ❌ TypeScript error: NewError is not handled!
  .exhaustive();

2. Zero Dependencies, Tiny Bundle 📦

1-2kb gzipped - smaller than most utility libraries
Zero dependencies - works everywhere
Tree-shakeable - only import what you use

npm install ts-typed-errors
# That's it! No peer dependencies, no lockfile bloat

3. Better Developer Experience 🚀

// Full autocomplete and type safety
matchErrorOf<AppError>(error)
  .with(NetworkError, e => {
    // e is fully typed as NetworkError
    console.log(e.data.status); // ✅ TypeScript knows this exists
    console.log(e.data.url);    // ✅ TypeScript knows this exists
    console.log(e.data.invalid); // ❌ TypeScript error: property doesn't exist
  })
  .exhaustive();

4. Works Everywhere 🌍

Node.js - Server-side applications
Browser - Frontend applications
React/Next.js - Component error boundaries
Express - API error handling
Deno - Modern JavaScript runtime

Real-World Example: API Error Handling

Here's how I use ts-typed-errors in a real API:

import { defineError, matchErrorOf, wrap } from 'ts-typed-errors';

// Define API-specific errors
const ValidationError = defineError('ValidationError')<{ field: string; value: any }>();
const NotFoundError = defineError('NotFoundError')<{ resource: string; id: string }>();
const RateLimitError = defineError('RateLimitError')<{ limit: number; remaining: number }>();
const DatabaseError = defineError('DatabaseError')<{ operation: string; table: string }>();

type APIError = InstanceType<typeof ValidationError> | InstanceType<typeof NotFoundError> | 
                InstanceType<typeof RateLimitError> | InstanceType<typeof DatabaseError>;

// Wrap your API functions
const safeGetUser = wrap(async (id: string) => {
  if (!id) throw new ValidationError('ID required', { field: 'id', value: id });

  const user = await db.users.findById(id);
  if (!user) throw new NotFoundError('User not found', { resource: 'user', id });

  return user;
});

// Handle errors in your route
app.get('/users/:id', async (req, res) => {
  const result = await safeGetUser(req.params.id);

  if (!result.ok) {
    const errorResponse = matchErrorOf<APIError>(result.error)
      .with(ValidationError, e => ({ 
        status: 400, 
        message: `Invalid ${e.data.field}: ${e.data.value}` 
      }))
      .with(NotFoundError, e => ({ 
        status: 404, 
        message: `${e.data.resource} not found` 
      }))
      .with(RateLimitError, e => ({ 
        status: 429, 
        message: `Rate limit exceeded. ${e.data.remaining}/${e.data.limit} remaining` 
      }))
      .with(DatabaseError, e => ({ 
        status: 500, 
        message: `Database error during ${e.data.operation}` 
      }))
      .exhaustive(); // ✅ All cases handled!

    return res.status(errorResponse.status).json(errorResponse);
  }

  res.json(result.value);
});

The Journey: From Problem to Solution

The Inspiration

I was working on a large TypeScript codebase where error handling was becoming a nightmare. We had:

20+ different error types
Inconsistent error handling across the codebase
Silent failures due to forgotten error cases
Verbose, unreadable error handling code

The Research

I looked at existing solutions:

Result types: Great, but no exhaustive matching
Either types: Functional, but complex for most developers
Custom error classes: Better, but still verbose
Pattern matching libraries: Close, but not designed for errors

The Breakthrough

The key insight was combining:

TypeScript's discriminated unions for exhaustiveness
Fluent API design for ergonomics
Zero dependencies for adoption
Result pattern for explicit error handling

The Implementation

// The core insight: use TypeScript's type system to track remaining cases
export type Next<Left, T> = Exclude<Left, HandlerInput<T>>;

export interface Matcher<Left> {
  with<T>(ctorOrGuard: ErrorCtor<any> | Guard<any>, handler: (e: HandlerInput<T>) => any): Matcher<Next<Left, T>>;
  exhaustive(this: Matcher<never>): any; // Only callable when Left is never
}

When you call .with(), TypeScript removes the handled type from the union. When all types are handled, Left becomes never, and .exhaustive() becomes callable.

The Impact

Since releasing ts-typed-errors, I've seen:

Cleaner error handling across entire codebases
Fewer production bugs due to exhaustive error handling
Better developer experience with full type safety
Easier onboarding for new team members

Try It Yourself

npm install ts-typed-errors

import { defineError, matchErrorOf, wrap } from 'ts-typed-errors';

// Start with a simple example
const MyError = defineError('MyError')<{ code: string }>();
const safeFunction = wrap(() => { throw new MyError('Oops!', { code: 'E001' }); });

const result = await safeFunction();
if (!result.ok) {
  const message = matchErrorOf<InstanceType<typeof MyError>>(result.error)
    .with(MyError, e => `Error ${e.data.code}: ${e.message}`)
    .exhaustive();

  console.log(message); // "Error E001: Oops!"
}

The Future

I'm excited about the possibilities:

Framework integrations (React error boundaries, Express middleware)
Testing utilities (Jest/Vitest matchers)
IDE extensions (VSCode snippets and autocomplete)
Performance optimizations (even smaller bundle size)

Conclusion

ts-typed-errors isn't just another utility library. It's a fundamental shift in how we think about error handling in TypeScript. By leveraging TypeScript's type system, we get:

✅ Compile-time safety - impossible to forget error cases
✅ Better ergonomics - clean, readable error handling
✅ Zero dependencies - works everywhere
✅ Tiny bundle - 1-2kb of pure TypeScript

The best part? It's not just for new projects. You can gradually adopt it in existing codebases, one function at a time.

Ready to revolutionize your error handling?

Get started with ts-typed-errors and let me know what you think!

What's your biggest pain point with error handling in TypeScript? Let me know in the comments!

The Subtle Art of Trust: Syncing Auth Between Frontend, Backend, and Database

ackermannQ — Wed, 28 May 2025 12:45:56 +0000

How to architect a fullstack authentication system where your frontend, backend, and database all trust each other without leaking security or breaking developer flow.

Introduction

Authentication in a modern fullstack app isn't just about logging in-it's about establishing a durable trust contract between all parts of your system: the frontend, the backend API, and the data layer (often managed via a service like Supabase or a custom DB). And while frameworks like NextAuth, Firebase, or Supabase Auth promise convenience, the reality is often messier.

This article explores how to design a seamless, secure, and maintainable authentication pipeline where each layer communicates just enough to stay in sync-without coupling too tightly or leaking user data.

The Core Problem: Fragmented Auth Contexts

In a typical React+Node stack, you’ll often run into the following:

Your frontend holds a session via cookies (e.g., via NextAuth).
Your backend expects a Bearer token or session ID in headers.
Your database needs a user ID or tenant ID to apply row-level access control.

These systems often don’t agree on who the user is, unless you design the protocol and flow intentionally.

Real-World Symptoms

session.user exists in the frontend, but req.user is undefined on the backend.
Auth tokens exist, but are missing or stale in client-side requests.
Supabase rules fail silently because the user's ID isn't passed correctly.
Your app works in dev, but breaks in prod due to cookie domain mismatches.

Principle 1: One Source of Truth for Identity

Pick one place to derive identity, and propagate that downward.

If using NextAuth, let the session hold the canonical user.id.
When making client -> server calls, always inject that identity as a Bearer token or signed cookie.
On the backend, validate this token and extract the user.
Use the resulting user.id as a consistent key for all DB-level permissions.

// client/apiClient.ts
const session = await getSession()
config.headers.Authorization = `Bearer ${session?.user.id}`

Principle 2: Auth is a Flow, Not a Snapshot

Too many apps treat auth as a static object: session = {...}. But sessions evolve:

Users get logged out.
Tokens expire.
Accounts are deleted or permissions change.

Each layer (frontend, backend, database) should revalidate auth context when needed.

Use middleware on the API to validate every incoming token.
Keep token lifetimes short and refresh seamlessly.
Avoid caching stale identities.

// backend/middleware/auth.ts
const token = req.headers.authorization?.split(" ")[1]
const user = await getUserFromToken(token)
if (!user) return res.status(401).send("Unauthorized")
req.user = user

Principle 3: Use Context-Passing, Not Global State

Avoid relying on implicit global state like sessionStorage, cookies, or req.session-unless you control the whole pipeline. Instead, pass identity explicitly in requests.

This avoids issues like:

Inconsistent behavior between SSR and client-side calls
Undebuggable bugs in CI/CD environments
Session mismatch across subdomains

fetch("/api/data", {
  headers: { Authorization: `Bearer ${session.user.id}` },
})

Advanced Techniques and Deep Dives

🔐 Secure Token Storage

One of the most critical aspects of auth implementation is the secure storage of tokens.

Access tokens should never be stored in localStorage due to XSS vulnerabilities.
Refresh tokens should be stored in HttpOnly cookies, making them inaccessible to JavaScript and more resilient to XSS attacks.

Recommended pattern (SSR + CSR hybrid apps)

Store the refreshToken in a secure HttpOnly cookie after login.
Create a protected /api/token endpoint that reads the cookie and returns a fresh accessToken.
On the frontend, call this endpoint to get an accessToken and store it only in memory.

// server-side: set secure cookie
res.setHeader(
  "Set-Cookie",
  serialize("refreshToken", token, {
    httpOnly: true,
    secure: process.env.NODE_ENV === "production",
    sameSite: "lax",
    path: "/",
  })
)

// client-side: fetch access token
const res = await fetch("/api/token")
const { accessToken } = await res.json()

This ensures that no token ever sits in storage where an attacker could grab it.

🔁 Refresh Token Flow

Access tokens should be short-lived. When they expire, your client must:

Detect the 401 Unauthorized error.
Trigger a refresh flow using the secure cookie.
Retry the original request transparently.

Example interceptor logic

apiClient.interceptors.response.use(undefined, async error => {
  if (error.response?.status === 401) {
    await fetch("/api/token/refresh") // Refresh happens via secure cookie
    return apiClient.request(error.config) // Retry the original request
  }
  return Promise.reject(error)
})

On the backend:

// POST /api/token/refresh
const refreshToken = req.cookies.refreshToken
const user = await validateRefreshToken(refreshToken)
if (!user) return res.status(401).send("Invalid refresh token")
const newToken = createAccessToken(user)
res.json({ accessToken: newToken })

This creates a resilient auth pipeline that gracefully recovers without user interruption.

🧭 Multi-Provider Identity Normalization

When users can log in with different providers (GitHub, Google, credentials), it's easy for your system to lose track of who they are.

Strategy

Create a users table that maps external provider IDs to a unified internal userId.
Always store and propagate this unifiedUserId.

// Backend
function resolveUnifiedUser(providerId: string, provider: string): string {
  const user = db.users.findOne({ provider, providerId })
  return user?.internalId
}

// Attach this to token payloads
const token = sign({ userId: unifiedId }, SECRET)

By resolving all external identities to one consistent ID, you avoid edge cases where the same person gets treated as multiple users.

💥 Bug Case: Cookie Auth but API 401

Symptom: User logs in successfully, but every API request returns 401 Unauthorized.

Cause: The cookie storing the token is scoped to /api, but frontend fetches are made from /.

Diagnosis

Use DevTools > Application > Cookies to inspect path restrictions.
Look for missing Authorization header or absent cookie.

Solution

// Correct path on server
serialize("token", value, { path: "/" })

Always scope cookies to / unless you are certain you want to restrict them.

🧵 Session vs Database Identity Drift

Problem: Session token exists, but the user was deleted from the database.

This often causes silent failures-frontend appears logged in, but the backend refuses operations.

Solution

Always verify backend token and check user existence in DB:

const userId = await getCurrentUserId(req);
if (!userId) {
  logger.error("User not found");
  res.status(401).json({ error: "Unauthorized" });
  return;
}

if !(await db.users.exists(user.id)) {
  return res.status(403).send("Invalid session or deleted user");
}

export async function getCurrentUserId(req: Request): Promise<string | null> {
  const token = await getToken({ req, secret: process.env.NEXTAUTH_SECRET });
  return (token?.id as string) ?? null;
}

This guards against stale or orphaned sessions.

🧪 Debugging and Traceability Enhancements

To effectively debug and audit auth flows:

Add a trace ID to every request.
Return contextual headers during development.
Log token contents and associated user at the edge.

Example

// Middleware
const traceId = uuid()
req.traceId = traceId
logger.info({ traceId, userId: req.user?.id })

// Response headers (dev only)
res.setHeader("X-Trace-Id", traceId)
res.setHeader("X-User-Id", req.user?.id)

Use logs and these headers to correlate frontend/backend issues precisely.

🛡️ Role-Based and Attribute-Based Access Control

A flat user.id isn't always enough. You need roles (e.g. admin, editor) or scopes (repo:read, repo:write).

Encode roles in your token

const token = sign({ userId, role: "admin" }, SECRET)

Then check them in protected routes:

if (decoded.role !== "admin") return res.status(403).send("Forbidden")

In Supabase (with RLS):

CREATE POLICY "Admins can see all"
  ON "logs"
  FOR SELECT USING (auth.role() = 'admin');

Combine token claims and RLS policies for full-stack enforcement.

🧠 When to Build vs Delegate Auth

As a Senior or Staff-level engineer, choosing not to fully delegate authentication to platforms like Supabase Auth or Clerk isn’t about reinventing the wheel - it’s about owning the trust contract between your application layers: frontend, backend, and database.

However, fully delegating authentication essentially depends on your project, team, timeframe and budget. Like a lot of decisions, it’s a balancing act.

When to Build

When you need a custom auth system that meets your exact needs.
When you need a custom auth system that integrates with your existing infrastructure.
- e.g. integrating with an existing database, or integrating with a third-party API.

When to Delegate

When you don't need to have specfic auth flows or features.
When you don't need to integrate with existing infrastructure.
When you need to have a quick, simple auth system rapidly built.

Key strategic reasons

Full control over session propagation across SSR, API routes, and RLS database layers.
Support for hybrid authentication flows (OAuth, credentials, internal accounts).
Avoiding vendor lock-in for long-term maintainability and architectural freedom.

✅ TL;DR

Frontend, backend, and database must agree on who the user is.
Treat authentication as a living flow, not a frozen object.
Avoid implicit global state; pass identity explicitly.
Use short-lived access tokens + secure HttpOnly cookies.
Normalize external accounts with a unified user ID strategy.
Include roles and scopes in your tokens and enforce them across the stack.

Conclusion

Syncing authentication across the frontend, backend, and database isn’t trivial - but it becomes manageable when grounded in clear architectural principles:

Establish a single source of identity.
Design authentication as a renewable, revalidating flow.
Pass identity context intentionally across system boundaries.

Get these right, and your system becomes more secure, observable, and adaptable - without sacrificing developer velocity or user experience.

Q. Ackermann Senior Engineer, Toolmaker, Systems Thinker GitHub | KodeReview | LinkedIn

You Shouldn't Need to Reverse Engineer Your Own React App

ackermannQ — Mon, 26 May 2025 11:20:33 +0000

Structure isn't a luxury. It's how we prevent our systems from decaying under their own weight.

We've all been there.
You need to change a feature, fix a bug, or review a PR.
And suddenly, you realize: you don't even know where to start.

The code technically works. But it doesn't explain itself.
There's no obvious place to plug into. No signposts. Just fragments of logic scattered across components, hooks, and helpers.

So you do what any experienced developer does: you reverse engineer the system.
You crawl through files, rename variables locally to understand data flows, and slowly build a mental model - again.

That's not sustainable.

Structure isn't cosmetic. It's survival

What we call "technical debt" is often just the absence of intentional structure.
And it leads to silent failure modes:

PRs that no one wants to review because they touch too many unclear areas
New team members who can't find where logic lives
Developers who avoid changing things because they're afraid to break what they don't understand

Eventually, your codebase becomes a high-friction environment. Not because it's broken - but because it doesn't speak.

You know it's happening when...

Here are the real-world signals that tell you structure is decaying:

A component is doing five things, but it's "not worth the refactor right now"
A flow can only be understood by replaying it in your head
A new dev takes days to find where to add a simple feature
You have to jump between four files just to follow one behavior
PRs feel like archaeology

Most devs feel this and call it "complexity."
But it's actually a lack of architectural constraints.

Good structure makes the next step obvious. And when it doesn't, that ambiguity becomes a productivity sink.

What I look for when reading a new project

When I join a codebase, I open the app and interact like a user.
Then I trace how those behaviors are implemented.

Where is this UI rendered?
What logic powers it?
What side effects does it trigger?

If I can follow that loop in 10 minutes, I know the architecture holds.
If not, I'm looking at a system that wasn't built for humans - or at least not beyond its original authors.

I don't expect perfect modularity. But I expect graceful scale.
When a component grows, it should expand its structure. That means introducing separation, naming its parts clearly, and exposing boundaries that others can work within.

My system: separating flow, logic, and rendering

When I build systems meant to last, I rely on a few repeatable patterns and folder conventions:

flows/ - business actions modeled as imperative sequences
services/ - reusable pure logic (validation, formatting, utilities)
features/ - one per domain or screen, grouping UI, hooks, and tests
ui/ - low-level visual components with no business logic
hooks/ - reactive bridges, ideally dumb wrappers around flows/services

This gives developers mental orientation. It tells them "where things go" and makes refactoring less risky.

Example: billing system

Let's say we're building a screen to let users view their current invoice and pay it.

flows/payInvoice.ts

export async function payInvoiceFlow(invoiceId: string) {
  const invoice = await api.fetchInvoice(invoiceId)
  if (!invoice || invoice.status === "paid") return

  const paymentResult = await api.pay(invoiceId)
  await auditLog.record({ type: "payment", invoiceId })

  return paymentResult
}

services/invoice.ts

export function formatInvoiceAmount(invoice: Invoice): string {
  return `$${(invoice.totalCents / 100).toFixed(2)}`
}

export function canInvoiceBePaid(invoice: Invoice): boolean {
  return invoice.status === "pending"
}

features/billing/BillingScreen.tsx

import { payInvoiceFlow } from "@/flows/payInvoice"
import { formatInvoiceAmount, canInvoiceBePaid } from "@/services/invoice"

export function BillingScreen({ invoiceId }: { invoiceId: string }) {
  const { data: invoice } = useInvoiceQuery(invoiceId)
  const [loading, setLoading] = useState(false)

  const handlePay = async () => {
    setLoading(true)
    await payInvoiceFlow(invoiceId)
    setLoading(false)
  }

  if (!invoice) return <LoadingIndicator />

  return (
    <BillingCard>
      <Amount>{formatInvoiceAmount(invoice)}</Amount>
      <PayButton
        onClick={handlePay}
        disabled={!canInvoiceBePaid(invoice) || loading}
      />
    </BillingCard>
  )
}

ui/BillingCard.tsx

export function BillingCard({ children }: { children: React.ReactNode }) {
  return <div className="billing-card">{children}</div>
}

Why it works

The flow describes the business behavior end-to-end.
The service extracts testable logic and utility formatting.
The feature file holds the orchestration layer for one domain.
The UI component makes visual reuse explicit.

This means the billing logic is:

Easy to test
Easy to follow
Easy to change without fear
Easy to onboard into for new contributors

That's not overengineering. That's investing in code that explains itself.

Onboarding friction is not a rite of passage

I've seen well-structured projects decay in less than a year - not because people stopped caring, but because structure wasn't maintained.

Every "quick fix" that breaks separation is a tax on future developers.
Every logic shortcut that leaks into the UI costs us debug time later.

That's how rot starts. And by the time it's obvious, it's expensive to reverse.

For leads and engineering managers: these are real metrics

Structure is measurable - not just by LOC, test coverage, or bugs, but by friction.

Here are concrete signals:

Average time to review PRs (especially by team members outside the author's feature)
Time to first meaningful contribution for a new hire
Number of hotfixes or production bugs that involve tangled logic
How often the same modules appear in complex diffs
Ratio of reactive bugfixes to structural ones

These are early warning signs.
If your app requires archaeology before action, it's not healthy.
If your devs hesitate before opening files - that's not culture, it's pain avoidance.

Track the pain. Structure is how you reduce it.

Final thought

If you feel like you're always reverse engineering your own system, that's a signal - not a skill test.

Good code doesn't just work. It narrates.
It gives others a way in. It survives context loss.

You don't fix this by rewriting everything.
You fix it by:

Isolating flows
Clarifying services
Making views shallow and honest
Giving structure a name, and making it part of your culture

Because in the end, good architecture is not just for today's team. It's for the one who shows up next.

Q. Ackermann

Senior Engineer, Toolmaker, Systems Thinker

GitHub | KodeReview | LinkedIn

Structure your React code.

ackermannQ — Thu, 22 May 2025 12:40:54 +0000

Scalability in React has nothing to do with components - and everything to do with how you separate orchestration, effects, and logic.

React feels scalable - until you realize your team is afraid to open certain files.

“We had a component called CustomerDashboard. 900+ lines. It fetched data, handled feature flags, did date formatting, triggered analytics, and contained three modals. Nobody knew what was safe to touch.”

This isn't rare. And it's not React's fault. It's ours - for not building structure around it.

React is a rendering library, not a system architecture. If you don't explicitly define your system, your component tree will become it.

1. Where React stops helping

React is fantastic at rendering state. But beyond JSX and useEffect, you're on your own.

You'll start seeing this:

Hooks become orchestration engines
Logic spreads across multiple useEffects
Component props become a chain of derived state
Reusable logic becomes magic logic

🔥 Anti-pattern: Hook-as-everything

function useSubscriptionFlow(userId: string) {
  const [state, setState] = useState("idle")

  useEffect(() => {
    if (!userId) return

    track("SubscriptionStarted")
    fetchData(userId).then(res => {
      if (res.status === "error") router.push("/error")
      else setState("done")
    })
  }, [userId])

  return state
}

✅ What's wrong:

It tracks analytics
Performs network fetch
Triggers navigation
Manages UI state

One hook. Four responsibilities. Zero clarity.

2. What scales: structure

The only way to make React codebases scale is to introduce separation of roles:

Rendering vs orchestration vs logic
Effects vs queries vs business flows
Triggers vs processors

Let's look at concrete structures I now use.

3. Flow isolation: move business logic out of components

// flows/createCustomer.ts
export async function createCustomerAndLog(input: FormData) {
  const customer = await api.createCustomer(input)
  await analytics.track("CustomerCreated", { id: customer.id })
  return customer
}

Used from component:

const handleSubmit = async () => {
  await createCustomerAndLog(form)
  router.push("/success")
}

🧠 This lets components trigger, not orchestrate.

4. Pattern: Hook façade

Used in real-world design systems and dashboards:

function useCustomerDashboard(customerId: string) {
  const profile = useCustomerProfile(customerId)
  const usage = useCustomerUsage(customerId)
  const tags = useCustomerTags(customerId)

  return { profile, usage, tags }
}

The component does this:

const { profile, usage, tags } = useCustomerDashboard(id)

This isolates data-fetching composition, not UI logic. Think of it as the container pattern for hooks - but composable and invisible.

5. Pattern: Effect isolator

You'll find this in apps like Vercel's dashboard, Sentry's audit logic, and internally at Stripe.

function useBillingWarning(customer: Customer) {
  useEffect(() => {
    if (customer.balance > 1000) {
      toast.warning("Your balance is overdue")
    }
  }, [customer])
}

Used in component:

useBillingWarning(customer)

🧠 This makes effects pluggable and separable.

No business logic in the UI. No hidden triggers. Each concern has a name.

6. Pattern: Imperative flow manager

Sometimes, declarative React doesn't cut it. You want imperative orchestration - think onboarding flows, checkout steps, multi-API syncs.

Don't shove this in hooks. Model it explicitly.

// services/accountMigration.ts
export class AccountMigrationManager {
  constructor(private readonly user: User) {}

  async start() {
    await this.exportData()
    await this.deleteLegacyAccount()
    await this.createNewAccount()
  }

  private async exportData() {
    /* ... */
  }
  private async deleteLegacyAccount() {
    /* ... */
  }
  private async createNewAccount() {
    /* ... */
  }
}

From React:

const manager = useMemo(() => new AccountMigrationManager(user), [user])

const handleMigrate = () => {
  manager.start().then(() => router.push("/done"))
}

🧠 Pattern seen in apps that require step-by-step orchestration - like Replay.io, or admin dashboards with workflow systems.

7. Final thoughts

React gives you rendering.

But only your structure can give you clarity, scale, and maintainability.

Build flows that narrate themselves.

Encapsulate effects with intent.

Write code that separates thought from display.

React doesn't scale. Your structure does.

Q. Ackermann Senior Engineer, Toolmaker, Systems Thinker GitHub | KodeReview | LinkedIn