> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ladybugs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# How It Works

> Technical overview of Ladybugs runtime debugging

## Architecture Overview

Ladybugs consists of three main components that work together to provide comprehensive runtime debugging:

<Steps>
  <Step title="Code Instrumentation">
    Babel plugin adds tracing to your source code during build
  </Step>

  <Step title="Data Collection">
    Instrumented code captures runtime data and sends it to your server
  </Step>

  <Step title="AI Integration">
    MCP server provides AI assistants with query access to runtime data
  </Step>
</Steps>

## Code Instrumentation with Babel

Ladybugs uses a Babel plugin to automatically instrument your JavaScript and TypeScript code during the build process. This happens transparently without requiring you to manually add logging statements.

### What Gets Instrumented

The Babel plugin adds tracing for:

* **Function calls** - Entry and exit points, parameters, return values
* **Variable assignments** - Track how data changes throughout execution
* **Conditional statements** - Which branches were taken and why
* **Loops** - Iterations, break conditions, loop variables
* **Data access** - Object property reads/writes, array operations
* **Errors** - Full stack traces with runtime variable values
* And much more!

### Data Captured

Each trace event includes:

* **Timestamp** - Precise execution time
* **Context** - Request ID, user ID, session info
* **Location** - File, function, line number
* **Data** - Variable values, parameters, return values
* **Metadata** - Environment, version, deployment info
* And much more!

## AI Integration via MCP

The Model Context Protocol (MCP) server bridges your AI assistant with Ladybugs data.

### Query Capabilities

When you ask your AI assistant about a production issue, the MCP server can:

<CardGroup cols={2}>
  <Card title="Search by Context" icon="magnifying-glass">
    Find traces based on user actions, error messages, or specific data values
  </Card>

  <Card title="Trace Execution" icon="route">
    Follow the complete execution path of a request through your codebase
  </Card>

  <Card title="Analyze Data Flow" icon="arrow-right-arrow-left">
    Track how data transforms as it moves through your application
  </Card>

  <Card title="Identify Patterns" icon="chart-line">
    Discover common patterns in errors or unexpected behavior
  </Card>
</CardGroup>

### Example Query Flow

<Steps>
  <Step title="Natural Language Query">
    **You:** "I tried to create a post with the title 'Banana' and it failed"
  </Step>

  <Step title="AI Understanding">
    The AI assistant understands you want to find traces related to:

    * Function: `createPost`
    * Parameter: `title = 'Banana'`
    * Outcome: Error/failure
  </Step>

  <Step title="MCP Query">
    The MCP server translates this to a structured query:

    ```json theme={null}
    {
      "function": "createPost",
      "params.title": "Banana",
      "hasError": true,
      "timeRange": "last 24 hours"
    }
    ```
  </Step>

  <Step title="Data Retrieval">
    The server finds matching traces and returns:

    * Full execution flow
    * All variable values at each step
    * The exact error and why it occurred
  </Step>

  <Step title="AI Analysis">
    The AI analyzes the runtime data and provides:

    * Root cause explanation
    * Code location of the issue
    * Suggested fix
  </Step>
</Steps>

## Security & Privacy

### Data Isolation

* **Self-hosted** - All data stays in your infrastructure

## Supported Languages & Frameworks

### JavaScript & TypeScript

Full support for modern JavaScript/TypeScript features:

* ES6+ syntax (async/await, destructuring, etc.)
* JSX/TSX for React components
* TypeScript types (preserved in traces)
* Decorators and class syntax

### Frameworks

<Tabs>
  <Tab title="Node.js">
    * Express.js
    * Fastify
    * NestJS
    * Next.js (API routes)
    * Any Node.js application
  </Tab>

  <Tab title="React">
    * React components
    * Hooks
    * Context
    * State management (Redux, Zustand, etc.)
    * Next.js (pages & app router)
  </Tab>

  <Tab title="Vanilla">
    * Vanilla websites
    * DOM changes
    * User events
  </Tab>
</Tabs>

## Next Steps

<CardGroup cols={2}>
  <Card title="MCP Setup" icon="plug" href="/mcp/setup">
    Connect Ladybugs to your AI assistant
  </Card>

  <Card title="Setup Guide" icon="code" href="/quickstart/setup">
    Set up Ladybugs in your repository
  </Card>
</CardGroup>