# Architecture

Custom AI Agent is implemented in Kotlin on the JVM using the Burp Montoya API. The architecture is intentionally layered so UI, context collection, redaction, backend execution, scanning, MCP, and audit concerns can evolve independently.

## Layered Design

```mermaid
flowchart TD
    subgraph L1[1. UI Layer]
      UI[MainTab, ChatPanel, SettingsPanel]
    end

    subgraph L2[2. Context Collection]
      CC[ContextCollector]
    end

    subgraph L3[3. Redaction Pipeline]
      RP[Privacy modes and sanitization]
    end

    subgraph L4[4. Prompt Resolution]
      PR[Built-in templates and BountyPrompt]
    end

    subgraph L5[5. Backend Adapters]
      BA[CLI and HTTP backends]
    end

    subgraph L6[6. Supervisors]
      SUP[AgentSupervisor and McpSupervisor]
    end

    subgraph L7[7. MCP Server]
      MCP[SSE and STDIO bridge]
    end

    subgraph L8[8. Scanners]
      SCN[Passive and Active scanners]
    end

    subgraph L9[9. Audit Logging]
      AUD[JSONL events and hashes]
    end

    subgraph L9b[9b. AI Request Logger]
      RQL[Activity buffer, rolling JSONL, trace correlation]
    end

    subgraph L10[10. Alerts]
      ALT[Optional webhook notifications]
    end

    UI --> CC --> RP --> PR --> BA
    BA --> SUP
    CC --> SCN
    RP --> MCP
    BA --> AUD
    BA --> RQL
    SCN --> AUD
    SCN --> RQL
    MCP --> AUD
    MCP --> RQL
    AUD --> ALT
```

## Initialization Sequence

`BurpAiAgentExtension.initialize(MontoyaApi)` performs startup in a strict order.

```mermaid
sequenceDiagram
    participant Burp as Burp Suite
    participant Ext as BurpAiAgentExtension
    participant Reg as BackendRegistry
    participant Core as Settings/Supervisors/Scanners
    participant UI as MainTab + Menus
    participant MCP as MCP Server

    Burp->>Ext: initialize(api)
    Ext->>Reg: load built-in + drop-in backends
    Ext->>Core: initialize settings, audit, scanners, supervisors
    Ext->>UI: register tab and context menus
    Ext->>Core: register scanner integration (Pro/Community paths)
    alt MCP enabled
      Ext->>MCP: start server
    else MCP disabled
      Ext-->>Burp: continue without MCP transport
    end
```

## Design Goals

* **Modularity**: separate concerns to reduce coupling.
* **Testability**: keep parsing and privacy logic unit-testable.
* **Extensibility**: backend/tool additions should not require core refactors.
* **Determinism**: stable ordering and stable anonymization when configured.
* **Privacy-first**: redaction happens before outbound backend or MCP output.

## Key Modules

| Package                  | Purpose                                                                                                      |
| ------------------------ | ------------------------------------------------------------------------------------------------------------ |
| `ui/*`                   | Swing UI, settings panels, interaction components, AI Logger panel.                                          |
| `ui/UiActions`           | Context menu wiring for request/response and issue actions.                                                  |
| `ui/ToolCallParser`      | Extracts MCP tool-call payloads from AI model responses (fenced blocks, raw JSON, OpenAI-style).             |
| `ui/ChatPanel`           | Chat orchestration with auto tool chaining (up to 8 iterations) and trace ID propagation.                    |
| `context/*`              | Context collection from Burp selections.                                                                     |
| `redact/*`               | Privacy policy and redaction engine.                                                                         |
| `prompts/bountyprompt/*` | Curated prompt loader, resolver, parser, and catalog.                                                        |
| `backends/*`             | Backend registry, built-in adapters, diagnostics.                                                            |
| `supervisor/*`           | Backend and MCP lifecycle supervision.                                                                       |
| `mcp/*`                  | MCP manager, catalog, limiter, and transports.                                                               |
| `scanner/*`              | Passive/active scanner engines and analyzers.                                                                |
| `audit/*`                | JSONL writer, integrity hashes, AI Request Logger (activity buffer, rolling persistence, trace correlation). |
| `alerts/*`               | Optional webhook notifications.                                                                              |
| `config/*`               | Settings model, persistence, defaults, migration.                                                            |

## Related Pages

* [Data Flow](https://burp-ai-agent.six2dez.com/developer/data-flow)
* [Redaction Pipeline](https://burp-ai-agent.six2dez.com/developer/redaction-pipeline)
* [Supervisor & Backends](https://burp-ai-agent.six2dez.com/developer/supervisor-backends)
* [Feature Coverage](https://burp-ai-agent.six2dez.com/developer/feature-coverage)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://burp-ai-agent.six2dez.com/developer/architecture.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.