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

# Under the Hood

> What happens when you send a message — the file pipeline, where things run, and how your design stays in sync.

## The Big Picture

Trace is a desktop PCB design app with an AI assistant built in. You work in a graphical schematic and PCB editor. The AI works alongside you — reading your design, making edits, searching for components, and running checks — all through a chat panel on the right side of the editor.

The core idea: **the AI edits structured text, you edit visually, and both interfaces stay in sync with the same design.**

```mermaid theme={null}
flowchart LR
  You["You (visual editor)"] -->|edit| KiCad[".kicad_sch / .kicad_pcb"]
  AI["AI (chat panel)"] -->|edit| Trace[".trace_sch / .trace_pcb"]
  Trace -->|"auto-converts"| KiCad
  KiCad -->|"editor renders"| You
```

## The File Format Pipeline

This is the key architectural decision that makes Trace possible.

### Two formats, one design

Your project contains two representations of the same circuit:

| Format                      | Who uses it      | What it looks like                                                      |
| --------------------------- | ---------------- | ----------------------------------------------------------------------- |
| `.trace_sch` / `.trace_pcb` | The AI           | Structured text designed for language models to read and edit precisely |
| `.kicad_sch` / `.kicad_pcb` | You (the editor) | Standard KiCad s-expression format that the visual editor renders       |

### How they stay in sync

When the AI edits a `.trace_sch` file, Trace automatically converts it to the corresponding `.kicad_sch` file. The visual editor then reloads and you see the change. This conversion is debounced (batched over 200ms) so rapid edits don't cause flickering.

```mermaid theme={null}
flowchart LR
  AIEdit["AI writes .trace_sch"] --> Convert["Converter runs"]
  Convert --> KiCadFile[".kicad_sch updated"]
  KiCadFile --> Reload["Editor reloads"]
  Reload --> YouSee["You see the change"]
```

The `.kicad_sch` / `.kicad_pcb` files are what you keep. They're standard KiCad — open them in vanilla KiCad anytime. The `.trace_sch` / `.trace_pcb` files are an intermediate step, like compiled output. You never need to touch them directly.

## Where Things Run

Trace splits work between your machine and a cloud backend. Your design files never leave your computer.

| Runs on your machine              | Runs on the server                   |
| --------------------------------- | ------------------------------------ |
| Visual editor (schematic + PCB)   | AI reasoning                         |
| File reading and writing          | Web search                           |
| Design rule checks (DRC/ERC)      | Parts search (DigiKey, Mouser, LCSC) |
| Gerber/drill file generation      | Datasheet parsing                    |
| Autorouting                       | Symbol/footprint search              |
| Format conversion (trace → kicad) | Component availability checks        |

When the AI needs to read or edit your files, it sends a tool call back to the desktop app. The app executes the tool locally and returns the result. This means your schematic and PCB data stay on your machine — the server only sees the tool results you send back.

## Three Modes

| Mode      | What it does                                                                                      | When to use it                                              |
| --------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| **Ask**   | Answers questions, analyzes your design, explains circuits. Read-only — no changes to your files. | "What does this capacitor do?" or "Explain the power path." |
| **Agent** | Makes direct edits to your schematic or PCB. Reads files, writes changes, runs checks.            | "Add a 100nF decoupling cap to U1" or "Route all traces."   |
| **Plan**  | Researches, creates a step-by-step plan, waits for your approval, then executes.                  | "Design a USB-C charging circuit" or any multi-step task.   |

You can pick a mode explicitly or let Trace choose based on your message.

## What Happens When You Send a Message

Here's the full lifecycle of a single chat interaction in Agent mode:

```mermaid theme={null}
sequenceDiagram
  participant You
  participant App as Desktop App
  participant Server as Backend Server
  participant AI as Trace AI

  You->>App: Type message in chat
  App->>Server: POST /chat/stream (SSE)
  Server->>AI: Classify request + send to model
  AI-->>Server: Reasoning + tool calls
  Server-->>App: Stream events (text, status, tool calls)
  App->>App: Execute tools locally (read/write files)
  App->>Server: POST /tools/result
  Server->>AI: Continue with tool results
  AI-->>Server: More reasoning or final response
  Server-->>App: Stream completion
  App->>App: Convert trace → kicad, reload editor
  App-->>You: See response + design updates
```

1. **You send a message** — typed in the chat panel.
2. **Backend classifies** — determines mode (ask/agent/plan) and whether research is needed.
3. **Research phase** (if needed) — the server searches the web, queries distributors, parses datasheets in parallel. Results stream as a collapsible research card.
4. **AI reasons** — the model analyzes your design context, conversation history, and research results.
5. **Tool calls stream back** — the AI requests actions like "read this file" or "write this component." These execute on your machine, not the server.
6. **Results return** — your app sends tool results back. The AI continues reasoning with that information.
7. **Response completes** — the AI's text response finalizes, file conversion runs, and your editor reloads with any changes.

The entire exchange streams in real-time — you see thinking steps, status messages, and text appearing as the AI works.

## Trust and Control

### Every edit is versioned

Every time the AI modifies your design, a version is saved automatically:

* **Local** — git commits in a `.history/` directory (works offline)
* **Cloud** — synced for cross-device access
* **Per-message undo** — click the undo button on any assistant message to roll back to before that message's changes

Rolling back creates a new version. No history is ever deleted. You can always go forward again.

### Plan mode approval

For complex tasks, the AI shows you exactly what it intends to do before doing it. You approve, adjust, or reject. Nothing executes without your say-so.

### Validation during iteration

The AI runs ERC (electrical rule checks) and DRC (design rule checks) as it works — not just at the end. It catches its own mistakes during the design process.

## Next Steps

* [Quick Start](/quick-start) — build your first PCB in 5 minutes
* [Intelligent Tools](/concepts/intelligent-tools) — full reference for what the AI can do
* [Plan Mode](/guides/plan-mode) — deep dive into the multi-step planning workflow
* [How Trace Works](/concepts/how-trace-works) — why this approach works better than alternatives