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

# Trace Architecture (Public)

> Understanding how Trace connects agents to runtimes.

## 1. High-Level System Context

Trace is designed as a **Local-First** intelligence layer. It connects your AI Agent (Cursor, Claude) to your local runtime environment via the Model Context Protocol (MCP).

```mermaid theme={null}
flowchart LR
    subgraph Client ["Your Machine"]
        direction LR
        Agent[🤖 AI Agent]
        subgraph Trace ["Trace Platform"]
            MCP[🔌 MCP Server]
            SDK[📦 Trace SDK]
        end
        subgraph App ["Your Application"]
            Runtime[🌐 Browser / Node.js]
            State[📑 DOM / State]
            Network[📡 Network]
        end
    end

    Agent <-->|MCP Protocol| MCP
    MCP <-->|Internal Protocol| SDK
    SDK -->|Instrument| Runtime
    SDK -->|Read| State
    SDK -->|Read| Network
```

**Key Takeaway**: Everything happens on *your* machine. Trace acts as the translation layer between the text-based world of the Agent and the binary world of the Browser.

## 2. The "Vibe Loop" (Sequence)

How Trace turns a vague question into a concrete fix.

```mermaid theme={null}
sequenceDiagram
    actor User
    participant Agent as 🤖 AI Agent
    participant Trace as ⚡ Trace Engine
    participant App as 🌐 Application

    User->>Agent: "Why is the signup button broken?"
    Agent->>Trace: "Analyze signup flow"
    
    note right of Trace: ⚡ Runtime Analysis

    Trace->>App: trace_get_network_errors()
    App-->>Trace: { 403 Forbidden: /api/signup }
    
    Trace->>App: trace_get_dom_snapshot()
    App-->>Trace: { <button id='signup' disabled> }

    Trace-->>Agent: "403 Error on POST /signup (Missing CSRF)"
    Agent->>User: "Fixing missing CSRF token."
```

## 3. Security & Data Flow

Designed for privacy. We do not tunnel your localhost to the cloud for basic debugging.

```mermaid theme={null}
flowchart LR
    subgraph Local ["Local Security Boundary"]
        IDE[💻 VS Code / Cursor] <--> Daemon[🛡️ Trace Daemon]
        Daemon <--> App[🚀 Your Application]
    end
    
    Cloud[☁️ Internet]
    
    App <--> Cloud
    Daemon -.->|❌ No Code Exfiltration| Cloud
    
    style Local fill:#1a1a1a,stroke:#333,color:#fff
    style Cloud fill:#ffffff,stroke:#333,color:#000
```

* **Local Execution**: The SDK runs inside your application process.
* **No Code Exfiltration**: Trace analyzes metadata (errors, logs, structure), not your source code files.
* **Direct-Connect**: The MCP connection is a direct pipe/socket on your machine.