How It Works

Limelight gives you deep visibility into your running app without rebuilds, heavy configuration, or invasive instrumentation. This page explains the architecture — from event capture to the structured context that powers AI-assisted debugging.

Architecture Overview

Your App (SDK)
    ↓ captures runtime events
    ↓ streams over WebSocket
Limelight Engine
    ├── Event Store (in-memory)
    ├── Correlation Engine (links events into causal chains)
    └── Debug IR Generator (structured, token-efficient output)
         ↓
    Consumption Surfaces
    ├── MCP Server → AI Editors (Cursor, Claude Code)
    └── Desktop App → Visual Timeline UI

Every surface — the MCP server, the desktop app, the API — consumes the same Debug IR. The intelligence is built once in the engine and delivered everywhere.

Step 1: Event Capture

When you call Limelight.connect(), the SDK attaches lightweight interceptors inside your app:

Client Side (React / React Native)

What’s captured	How
Network requests	Intercepts `fetch` and `XMLHttpRequest` — captures method, URL, headers, body, response, timing, and status
Console logs	Wraps `console.*` methods — captures level, message, timestamps, and stack traces
Component renders	Walks the React Fiber tree — captures component name, render count, cost, phase, cause (props/state/context/parent), and prop changes
State changes	Instruments Zustand and Redux stores — captures action name, changed keys, and diffs
GraphQL operations	Automatically detects GraphQL requests — parses queries, extracts operation names, scores complexity

Server Side (Node.js / Express / Next.js)

When you add Limelight middleware to your server:

Captures every incoming HTTP request with method, URL, headers, and body
Records the response including status code, body, and timing
Propagates trace IDs via AsyncLocalStorage so context flows through async handlers
Streams events to the same engine as your client-side data

Full-Stack Tracing

When both sides are connected, Limelight automatically correlates client and server events using a shared x-limelight-trace-id header. The client attaches it to every outgoing request, and the server middleware reads it to link the incoming request to the same trace. No configuration needed.

Step 2: Correlation Engine

Raw events are useful. Correlated events are powerful. The correlation engine links events together by analyzing:

Temporal proximity — what happened immediately before and after an event
Causal relationships — a state update that triggered a re-render, a network response that caused a state change
Cross-boundary links — frontend request → backend response → state update → re-render, connected automatically via trace IDs and timing
Pattern detection — recurring sequences that indicate known anti-patterns

The output is a correlation graph where each event has typed edges to related events:

Edge Type	Meaning
`TRIGGERED`	This event directly caused another
`CONTRIBUTED`	This event was a contributing factor
`FOLLOWED`	This event happened after, likely related
`EVIDENCE`	This event provides context for understanding another

Each edge carries a confidence score, so consumers know how strong the relationship is.

Step 3: Debug IR

Debug IR (Debug Intermediate Representation) is the structured output of the correlation engine. It’s designed to be:

Structured — JSON with consistent schemas, not free-text logs
Token-efficient — optimized for LLM consumption without wasting context window
Anonymized — sensitive values are type-described, not exposed (e.g., "password": "[string, 12 chars]")
Pre-analyzed — includes detected violations, causal chains, and suggested fixes

A Debug IR analysis includes:

Field	What it contains
`issue`	Framed question — what went wrong
`causalChain`	Sequence of events that led to the problem
`violations`	Detected abnormal behaviors (e.g., “response took 475% longer than baseline”)
`stateDeltas`	How state changed around the error
`excludedCauses`	What was ruled out — preventing the AI from chasing false leads
`renderCascade`	Component render tree if the issue is UI-related

This is what makes Limelight’s context fundamentally different from raw logs or browser DevTools data. The AI receives pre-analyzed, correlated context — not a wall of text to parse.

Step 4: Delivery

Debug IR flows to whichever surface needs it:

MCP Server

Your AI coding assistant calls Limelight’s 11 tools via the MCP protocol. Each tool returns structured Debug IR — the AI gets pre-analyzed context and can diagnose issues, suggest fixes, and explain behavior using real runtime data.

Desktop App

The visual timeline UI renders the same Debug IR as an interactive experience — click any event to see the full cause-and-effect chain, correlated events, and AI-powered diagnosis.

What Gets Detected Automatically

The engine identifies these patterns without any configuration:

Pattern	Severity	Description
Failed requests	Critical	4xx/5xx responses, network errors, aborted requests
Render loops	Critical	Components re-rendering at unsustainable velocity
State-render loops	Critical	State updates triggering renders that trigger more state updates
N+1 queries	Warning	Repeated identical or near-identical requests
Race conditions	Warning	Out-of-order responses overwriting correct state
Retry storms	Warning	Rapid repeated requests to the same endpoint
Unstable props	Warning	Props changing reference on every render (inline objects/arrays)
Render cascades	Warning	Parent re-render causing deep child re-render chains
Stale closures	Warning	Event handlers capturing outdated state
Slow requests	Warning	Requests significantly slower than baseline

Data Privacy

All data stays on your machine — the MCP server and desktop app run locally
No telemetry, no cloud dependency for core functionality
Sensitive headers (Authorization, Cookie, etc.) are automatically redacted
State values are type-described by default, not exposed as raw values
The beforeSend hook lets you filter or transform any event before it’s processed

Getting Started

Features

Limelight MCP

Help

How It Works

Architecture Overview

Step 1: Event Capture

Client Side (React / React Native)

Server Side (Node.js / Express / Next.js)

Full-Stack Tracing

Step 2: Correlation Engine

Step 3: Debug IR

Step 4: Delivery

MCP Server

Desktop App

What Gets Detected Automatically

Data Privacy

​Architecture Overview

​Step 1: Event Capture

​Client Side (React / React Native)

​Server Side (Node.js / Express / Next.js)

​Full-Stack Tracing

​Step 2: Correlation Engine

​Step 3: Debug IR

​Step 4: Delivery

​MCP Server

​Desktop App

​What Gets Detected Automatically

​Data Privacy

Architecture Overview

Step 1: Event Capture

Client Side (React / React Native)

Server Side (Node.js / Express / Next.js)

Full-Stack Tracing

Step 2: Correlation Engine

Step 3: Debug IR

Step 4: Delivery

MCP Server

Desktop App

What Gets Detected Automatically

Data Privacy