# muwinds/deluxe-agent architecture

> Architecture diagram of the GitHub repository muwinds/deluxe-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/muwinds/deluxe-agent
- Repository: https://github.com/muwinds/deluxe-agent

## Overview

This is a native desktop coding-agent application. A user submits a project-scoped prompt in the UI; the host runs an agent turn, which calls a model provider and executes requested tools, then persists the conversation for transcript display. The host also manages Wasmtime plugins, attachments, context compaction, and background jobs. Edges are limited to relationships visible in excerpts, SOURCE INDEX references, or the documented module contracts; unsampled subsystems are represented by their supported source paths.

Main entry points: [`src/agent.rs`](https://github.com/muwinds/deluxe-agent/blob/main/src/agent.rs) (Agent loop), [`src/plugins/mod.rs`](https://github.com/muwinds/deluxe-agent/blob/main/src/plugins/mod.rs) (Plugin lifecycle), [`src/app/mod.rs`](https://github.com/muwinds/deluxe-agent/blob/main/src/app/mod.rs) (App controller and UI), [`src/session.rs`](https://github.com/muwinds/deluxe-agent/blob/main/src/session.rs) (Session model and store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop app"]
  node_main["App composition<br/>[main.rs]"]
  node_app["App controller and UI<br/>[mod.rs]"]
  node_renderer["Native renderer<br/>[mod.rs]"]
  node_ipc["IPC interface<br/>[ipc.rs]"]
end

subgraph group_runtime["Agent runtime"]
  node_agent["Agent loop<br/>[agent.rs]"]
  node_harness["Runtime contracts<br/>[ports.rs]"]
  node_services["Native services<br/>[services.rs]"]
  node_tools["Tool registry<br/>[mod.rs]"]
  node_jobs["Background jobs<br/>[jobs.rs]"]
  node_context["Context compaction<br/>[context.rs]"]
  node_project["Project runtime<br/>[project.rs]"]
end

subgraph group_plugins["Plugin system"]
  node_plugins["Plugin lifecycle<br/>[mod.rs]"]
  node_capabilities["Plugin capabilities<br/>[capabilities.rs]"]
  node_wasm["Wasm runtime<br/>[wasm_runtime.rs]"]
  node_plugin_llm["Provider adapter<br/>[llm.rs]"]
end

subgraph group_providers["Provider components"]
  node_llm_component["LLM provider component<br/>[lib.rs]"]
  node_mcp["MCP client component<br/>[lib.rs]"]
  node_hooks["Hooks component<br/>[lib.rs]"]
end

subgraph group_state["Conversation state"]
  node_session[("Session model and store<br/>[session.rs]")]
  node_attachments[("Image attachments<br/>[attachments.rs]")]
  node_config["Configuration<br/>[config.rs]"]
end

node_user(("User"))
node_model_service(("Model endpoint"))

node_user -->|"submits prompt"| node_app
node_main -->|"composes"| node_app
node_main -->|"starts runtime"| node_agent
node_main -->|"composes contracts"| node_harness
node_main -->|"starts renderer"| node_renderer
node_app -->|"routes requests"| node_ipc
node_app -->|"uses sessions"| node_session
node_app -->|"uses settings"| node_config
node_renderer -->|"renders UI"| node_app
node_ipc -->|"uses runtime"| node_agent
node_ipc -->|"uses sessions"| node_session
node_agent -->|"uses contracts"| node_harness
node_agent -->|"compacts history"| node_context
node_agent -->|"dispatches calls"| node_tools
node_agent -->|"assembles images"| node_attachments
node_agent -.->|"updates turns"| node_session
node_services -->|"implements ports"| node_harness
node_services -->|"manages plugins"| node_plugins
node_services -->|"uses registry"| node_jobs
node_tools -->|"registers job tools"| node_jobs
node_project -->|"runs agent"| node_agent
node_project -->|"resolves plugins"| node_plugins
node_project -->|"uses services"| node_services
node_plugins -->|"loads capabilities"| node_capabilities
node_plugins -->|"loads components"| node_wasm
node_plugin_llm -->|"uses component actor"| node_wasm
node_plugin_llm -->|"shapes requests"| node_llm_component
node_plugin_llm -->|"sends HTTP"| node_model_service
node_plugins -.->|"loads default component"| node_mcp
node_plugins -.->|"loads default component"| node_hooks
node_session -->|"stores image references"| node_attachments
node_context -->|"summarizes history"| node_session
node_context -.->|"requests completion"| node_llm_component
node_config -->|"stores plugin settings"| node_plugins

click node_main "https://github.com/muwinds/deluxe-agent/blob/main/src/main.rs"
click node_app "https://github.com/muwinds/deluxe-agent/blob/main/src/app/mod.rs"
click node_renderer "https://github.com/muwinds/deluxe-agent/blob/main/src/renderer/mod.rs"
click node_ipc "https://github.com/muwinds/deluxe-agent/blob/main/src/ipc.rs"
click node_agent "https://github.com/muwinds/deluxe-agent/blob/main/src/agent.rs"
click node_harness "https://github.com/muwinds/deluxe-agent/blob/main/src/harness/ports.rs"
click node_services "https://github.com/muwinds/deluxe-agent/blob/main/src/harness/services.rs"
click node_tools "https://github.com/muwinds/deluxe-agent/blob/main/src/tools/mod.rs"
click node_jobs "https://github.com/muwinds/deluxe-agent/blob/main/src/tools/jobs.rs"
click node_context "https://github.com/muwinds/deluxe-agent/blob/main/src/context.rs"
click node_project "https://github.com/muwinds/deluxe-agent/blob/main/src/runtime/project.rs"
click node_plugins "https://github.com/muwinds/deluxe-agent/blob/main/src/plugins/mod.rs"
click node_capabilities "https://github.com/muwinds/deluxe-agent/blob/main/src/plugins/capabilities.rs"
click node_wasm "https://github.com/muwinds/deluxe-agent/blob/main/src/plugins/wasm_runtime.rs"
click node_plugin_llm "https://github.com/muwinds/deluxe-agent/blob/main/src/plugins/llm.rs"
click node_llm_component "https://github.com/muwinds/deluxe-agent/blob/main/plugin-src/llm-provider/src/lib.rs"
click node_mcp "https://github.com/muwinds/deluxe-agent/blob/main/plugin-src/mcp-client/src/lib.rs"
click node_hooks "https://github.com/muwinds/deluxe-agent/blob/main/plugin-src/hooks-provider/src/lib.rs"
click node_session "https://github.com/muwinds/deluxe-agent/blob/main/src/session.rs"
click node_attachments "https://github.com/muwinds/deluxe-agent/blob/main/src/attachments.rs"
click node_config "https://github.com/muwinds/deluxe-agent/blob/main/src/config.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_app,node_renderer,node_ipc,node_user toneBlue
class node_agent,node_harness,node_services,node_tools,node_jobs,node_context,node_project toneAmber
class node_plugins,node_capabilities,node_wasm,node_plugin_llm toneMint
class node_llm_component,node_mcp,node_hooks toneRose
class node_session,node_attachments,node_config,node_model_service toneIndigo
```

## Components

### Desktop app

- [App composition](https://github.com/muwinds/deluxe-agent/blob/main/src/main.rs): `src/main.rs`
- [App controller and UI](https://github.com/muwinds/deluxe-agent/blob/main/src/app/mod.rs): `src/app/mod.rs`
- [Native renderer](https://github.com/muwinds/deluxe-agent/blob/main/src/renderer/mod.rs): `src/renderer/mod.rs`
- [IPC interface](https://github.com/muwinds/deluxe-agent/blob/main/src/ipc.rs): `src/ipc.rs`

### Agent runtime

- [Agent loop](https://github.com/muwinds/deluxe-agent/blob/main/src/agent.rs): `src/agent.rs`
- [Runtime contracts](https://github.com/muwinds/deluxe-agent/blob/main/src/harness/ports.rs): `src/harness/ports.rs`
- [Native services](https://github.com/muwinds/deluxe-agent/blob/main/src/harness/services.rs): `src/harness/services.rs`
- [Tool registry](https://github.com/muwinds/deluxe-agent/blob/main/src/tools/mod.rs): `src/tools/mod.rs`
- [Background jobs](https://github.com/muwinds/deluxe-agent/blob/main/src/tools/jobs.rs): `src/tools/jobs.rs`
- [Context compaction](https://github.com/muwinds/deluxe-agent/blob/main/src/context.rs): `src/context.rs`
- [Project runtime](https://github.com/muwinds/deluxe-agent/blob/main/src/runtime/project.rs): `src/runtime/project.rs`

### Plugin system

- [Plugin lifecycle](https://github.com/muwinds/deluxe-agent/blob/main/src/plugins/mod.rs): `src/plugins/mod.rs`
- [Plugin capabilities](https://github.com/muwinds/deluxe-agent/blob/main/src/plugins/capabilities.rs): `src/plugins/capabilities.rs`
- [Wasm runtime](https://github.com/muwinds/deluxe-agent/blob/main/src/plugins/wasm_runtime.rs): `src/plugins/wasm_runtime.rs`
- [Provider adapter](https://github.com/muwinds/deluxe-agent/blob/main/src/plugins/llm.rs): `src/plugins/llm.rs`

### Provider components

- [LLM provider component](https://github.com/muwinds/deluxe-agent/blob/main/plugin-src/llm-provider/src/lib.rs): `plugin-src/llm-provider/src/lib.rs`
- [MCP client component](https://github.com/muwinds/deluxe-agent/blob/main/plugin-src/mcp-client/src/lib.rs): `plugin-src/mcp-client/src/lib.rs`
- [Hooks component](https://github.com/muwinds/deluxe-agent/blob/main/plugin-src/hooks-provider/src/lib.rs): `plugin-src/hooks-provider/src/lib.rs`

### Conversation state

- [Session model and store](https://github.com/muwinds/deluxe-agent/blob/main/src/session.rs): `src/session.rs`
- [Image attachments](https://github.com/muwinds/deluxe-agent/blob/main/src/attachments.rs): `src/attachments.rs`
- [Configuration](https://github.com/muwinds/deluxe-agent/blob/main/src/config.rs): `src/config.rs`

### Other components

- **User**
- **Model endpoint**

## Connections

- User → App controller and UI: submits prompt (evidence: `src/app/mod.rs`)
- App composition → App controller and UI: composes (evidence: `src/main.rs`)
- App composition → Agent loop: starts runtime (evidence: `src/main.rs`)
- App composition → Runtime contracts: composes contracts (evidence: `src/main.rs`)
- App composition → Native renderer: starts renderer (evidence: `src/main.rs`)
- App controller and UI → IPC interface: routes requests (evidence: `src/app/mod.rs`)
- App controller and UI → Session model and store: uses sessions (evidence: `src/app/mod.rs`)
- App controller and UI → Configuration: uses settings (evidence: `src/app/mod.rs`)
- Native renderer → App controller and UI: renders UI (evidence: `src/renderer/mod.rs`)
- IPC interface → Agent loop: uses runtime (evidence: `src/ipc.rs`)
- IPC interface → Session model and store: uses sessions (evidence: `src/ipc.rs`)
- Agent loop → Runtime contracts: uses contracts (evidence: `src/agent.rs`)
- Agent loop → Context compaction: compacts history (evidence: `src/agent.rs`)
- Agent loop → Tool registry: dispatches calls (evidence: `src/agent.rs`)
- Agent loop → Image attachments: assembles images (evidence: `src/agent.rs`)
- Agent loop → Session model and store: updates turns
- Native services → Runtime contracts: implements ports (evidence: `src/harness/mod.rs`)
- Native services → Plugin lifecycle: manages plugins (evidence: `src/harness/services.rs`)
- Native services → Background jobs: uses registry (evidence: `src/harness/services.rs`)
- Tool registry → Background jobs: registers job tools (evidence: `src/tools/mod.rs`)
- Project runtime → Agent loop: runs agent (evidence: `src/runtime/project.rs`)
- Project runtime → Plugin lifecycle: resolves plugins (evidence: `src/runtime/project.rs`)
- Project runtime → Native services: uses services (evidence: `src/runtime/project.rs`)
- Plugin lifecycle → Plugin capabilities: loads capabilities (evidence: `src/plugins/mod.rs`)
- Plugin lifecycle → Wasm runtime: loads components (evidence: `src/plugins/mod.rs`)
- Provider adapter → Wasm runtime: uses component actor (evidence: `src/plugins/llm.rs`)
- Provider adapter → LLM provider component: shapes requests (evidence: `src/plugins/llm.rs`)
- Provider adapter → Model endpoint: sends HTTP (evidence: `src/plugins/llm.rs`)
- Plugin lifecycle → MCP client component: loads default component
- Plugin lifecycle → Hooks component: loads default component
- Session model and store → Image attachments: stores image references (evidence: `src/session.rs`)
- Context compaction → Session model and store: summarizes history (evidence: `src/context.rs`)
- Context compaction → LLM provider component: requests completion
- Configuration → Plugin lifecycle: stores plugin settings (evidence: `src/config.rs`)