# v7ren/puppet-master architecture

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

- Interactive diagram: https://gitdiagram.com/v7ren/puppet-master
- Repository: https://github.com/v7ren/puppet-master

## Overview

Puppet Master coordinates real agent and shell PTY sessions through a shared local HTTP bridge. Users launch workers and orchestrate them from the desktop sidebar, mobile PWA, or an external MCP host; the bridge exposes the same panes and project-scoped coordination state to each surface. The desktop terminal session renders PTY data, while the Rust runtime manages panes and coordination. The README documents major capabilities beyond the sampled excerpts; those links are shown as documented relationships rather than claims that their source was inspected.

Main entry points: [`packages/app/src-tauri/src/bridge.rs`](https://github.com/v7ren/puppet-master/blob/main/packages/app/src-tauri/src/bridge.rs) (Local HTTP bridge), [`packages/app/src/App.tsx`](https://github.com/v7ren/puppet-master/blob/main/packages/app/src/App.tsx) (Desktop app), [`packages/app/src/lib/tauri.ts`](https://github.com/v7ren/puppet-master/blob/main/packages/app/src/lib/tauri.ts) (Tauri API client), [`packages/app/src/components/PuppetMasterSidebar.tsx`](https://github.com/v7ren/puppet-master/blob/main/packages/app/src/components/PuppetMasterSidebar.tsx) (Orchestrator sidebar)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_surfaces["User surfaces"]
  node_desktop_app["Desktop app<br/>[App.tsx]"]
  node_pwa["Mobile PWA<br/>[PwaApp.tsx]"]
  node_terminal_ui["Terminal UI"]
  node_pane_registry_hook["Pane registry hook<br/>[usePaneRegistry.ts]"]
end

subgraph group_orchestration["Orchestration"]
  node_sidebar["Orchestrator sidebar"]
  node_llm_chat["LLM chat<br/>[llm.ts]"]
  node_cli_orchestrator["CLI orchestrator panes"]
end

subgraph group_runtime["PTY runtime"]
  node_terminal_session["Terminal session"]
  node_tauri_api["Tauri API client<br/>[tauri.ts]"]
  node_rust_commands["Rust app commands<br/>[commands.rs]"]
  node_pty_registry["PTY pane registry<br/>[registry.rs]"]
  node_agent_adapters["Agent adapters"]
end

subgraph group_bridge["Bridge and clients"]
  node_http_bridge["Local HTTP bridge<br/>[bridge.rs]"]
  node_mcp_server["Stdio MCP server<br/>[index.ts]"]
  node_cli_launcher["CLI launcher<br/>[index.ts]"]
  node_shared_protocol["Shared protocol<br/>[protocol.ts]"]
  node_mobile_pairing["Mobile pairing<br/>[mobile_pairing.rs]"]
end

subgraph group_coordination["Coordination state"]
  node_coordination_log[("Coordination event log<br/>[event_log.rs]")]
  node_coordination_views["Tasks, locks, context<br/>[projections.rs]"]
end

node_desktop_user(("Desktop user"))
node_mobile_user(("Mobile user"))
node_mcp_host(("External MCP host"))
node_agent_processes["Agent and shell processes"]

node_desktop_user -->|"uses"| node_desktop_app
node_mobile_user -->|"uses"| node_pwa
node_mcp_host -->|"invokes tools"| node_mcp_server
node_desktop_app -->|"initializes"| node_pane_registry_hook
node_desktop_app -->|"renders"| node_sidebar
node_sidebar -->|"calls"| node_llm_chat
node_sidebar -->|"selects backend"| node_cli_orchestrator
node_cli_orchestrator -->|"spawns panes"| node_tauri_api
node_terminal_ui -->|"mounts"| node_terminal_session
node_terminal_session -->|"resizes PTY"| node_tauri_api
node_pane_registry_hook -->|"subscribes events"| node_tauri_api
node_tauri_api -->|"invokes commands"| node_rust_commands
node_rust_commands -->|"manages panes"| node_pty_registry
node_pty_registry -->|"launches agents"| node_agent_adapters
node_agent_adapters -->|"starts"| node_agent_processes
node_desktop_app -->|"shares local bridge"| node_http_bridge
node_pwa -->|"mirrors panes"| node_http_bridge
node_mcp_server -->|"forwards tool calls"| node_http_bridge
node_cli_launcher -->|"launches"| node_desktop_app
node_http_bridge -->|"records events"| node_coordination_log
node_http_bridge -->|"serves coordination"| node_coordination_views
node_coordination_views -->|"projects events"| node_coordination_log
node_http_bridge -->|"supports pairing"| node_mobile_pairing
node_mcp_server -->|"uses shared types"| node_shared_protocol

click node_desktop_app "https://github.com/v7ren/puppet-master/blob/main/packages/app/src/App.tsx"
click node_pwa "https://github.com/v7ren/puppet-master/blob/main/packages/app/src/PwaApp.tsx"
click node_sidebar "https://github.com/v7ren/puppet-master/blob/main/packages/app/src/components/PuppetMasterSidebar.tsx"
click node_llm_chat "https://github.com/v7ren/puppet-master/blob/main/packages/app/src/lib/llm.ts"
click node_cli_orchestrator "https://github.com/v7ren/puppet-master/blob/main/packages/app/src/lib/orchestrator-panes.ts"
click node_terminal_ui "https://github.com/v7ren/puppet-master/blob/main/packages/app/src/components/OrchestratorTerminal.tsx"
click node_terminal_session "https://github.com/v7ren/puppet-master/blob/main/packages/app/src/terminal/terminal-session.ts"
click node_pane_registry_hook "https://github.com/v7ren/puppet-master/blob/main/packages/app/src/hooks/usePaneRegistry.ts"
click node_tauri_api "https://github.com/v7ren/puppet-master/blob/main/packages/app/src/lib/tauri.ts"
click node_rust_commands "https://github.com/v7ren/puppet-master/blob/main/packages/app/src-tauri/src/commands.rs"
click node_pty_registry "https://github.com/v7ren/puppet-master/blob/main/packages/app/src-tauri/src/pty/registry.rs"
click node_agent_adapters "https://github.com/v7ren/puppet-master/tree/main/packages/app/src-tauri/src/agent_adapters"
click node_http_bridge "https://github.com/v7ren/puppet-master/blob/main/packages/app/src-tauri/src/bridge.rs"
click node_mcp_server "https://github.com/v7ren/puppet-master/blob/main/packages/mcp-server/src/index.ts"
click node_cli_launcher "https://github.com/v7ren/puppet-master/blob/main/packages/cli/src/index.ts"
click node_shared_protocol "https://github.com/v7ren/puppet-master/blob/main/packages/shared/src/protocol.ts"
click node_coordination_log "https://github.com/v7ren/puppet-master/blob/main/packages/app/src-tauri/src/event_log.rs"
click node_coordination_views "https://github.com/v7ren/puppet-master/blob/main/packages/app/src-tauri/src/projections.rs"
click node_mobile_pairing "https://github.com/v7ren/puppet-master/blob/main/packages/app/src-tauri/src/mobile_pairing.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_desktop_app,node_pwa,node_terminal_ui,node_pane_registry_hook,node_desktop_user,node_mobile_user toneBlue
class node_sidebar,node_llm_chat,node_cli_orchestrator toneAmber
class node_terminal_session,node_tauri_api,node_rust_commands,node_pty_registry,node_agent_adapters toneMint
class node_http_bridge,node_mcp_server,node_cli_launcher,node_shared_protocol,node_mobile_pairing toneRose
class node_coordination_log,node_coordination_views,node_mcp_host,node_agent_processes toneIndigo
```

## Components

### User surfaces

- [Desktop app](https://github.com/v7ren/puppet-master/blob/main/packages/app/src/App.tsx): `packages/app/src/App.tsx`
- [Mobile PWA](https://github.com/v7ren/puppet-master/blob/main/packages/app/src/PwaApp.tsx): `packages/app/src/PwaApp.tsx`
- [Terminal UI](https://github.com/v7ren/puppet-master/blob/main/packages/app/src/components/OrchestratorTerminal.tsx): `packages/app/src/components/OrchestratorTerminal.tsx`
- [Pane registry hook](https://github.com/v7ren/puppet-master/blob/main/packages/app/src/hooks/usePaneRegistry.ts): `packages/app/src/hooks/usePaneRegistry.ts`

### Orchestration

- [Orchestrator sidebar](https://github.com/v7ren/puppet-master/blob/main/packages/app/src/components/PuppetMasterSidebar.tsx): `packages/app/src/components/PuppetMasterSidebar.tsx`
- [LLM chat](https://github.com/v7ren/puppet-master/blob/main/packages/app/src/lib/llm.ts): `packages/app/src/lib/llm.ts`
- [CLI orchestrator panes](https://github.com/v7ren/puppet-master/blob/main/packages/app/src/lib/orchestrator-panes.ts): `packages/app/src/lib/orchestrator-panes.ts`

### PTY runtime

- [Terminal session](https://github.com/v7ren/puppet-master/blob/main/packages/app/src/terminal/terminal-session.ts): `packages/app/src/terminal/terminal-session.ts`
- [Tauri API client](https://github.com/v7ren/puppet-master/blob/main/packages/app/src/lib/tauri.ts): `packages/app/src/lib/tauri.ts`
- [Rust app commands](https://github.com/v7ren/puppet-master/blob/main/packages/app/src-tauri/src/commands.rs): `packages/app/src-tauri/src/commands.rs`
- [PTY pane registry](https://github.com/v7ren/puppet-master/blob/main/packages/app/src-tauri/src/pty/registry.rs): `packages/app/src-tauri/src/pty/registry.rs`
- [Agent adapters](https://github.com/v7ren/puppet-master/tree/main/packages/app/src-tauri/src/agent_adapters): `packages/app/src-tauri/src/agent_adapters`

### Bridge and clients

- [Local HTTP bridge](https://github.com/v7ren/puppet-master/blob/main/packages/app/src-tauri/src/bridge.rs): `packages/app/src-tauri/src/bridge.rs`
- [Stdio MCP server](https://github.com/v7ren/puppet-master/blob/main/packages/mcp-server/src/index.ts): `packages/mcp-server/src/index.ts`
- [CLI launcher](https://github.com/v7ren/puppet-master/blob/main/packages/cli/src/index.ts): `packages/cli/src/index.ts`
- [Shared protocol](https://github.com/v7ren/puppet-master/blob/main/packages/shared/src/protocol.ts): `packages/shared/src/protocol.ts`
- [Mobile pairing](https://github.com/v7ren/puppet-master/blob/main/packages/app/src-tauri/src/mobile_pairing.rs): `packages/app/src-tauri/src/mobile_pairing.rs`

### Coordination state

- [Coordination event log](https://github.com/v7ren/puppet-master/blob/main/packages/app/src-tauri/src/event_log.rs): `packages/app/src-tauri/src/event_log.rs`
- [Tasks, locks, context](https://github.com/v7ren/puppet-master/blob/main/packages/app/src-tauri/src/projections.rs): `packages/app/src-tauri/src/projections.rs`

### Other components

- **Desktop user**
- **Mobile user**
- **External MCP host**
- **Agent and shell processes**

## Connections

- Desktop user → Desktop app: uses
- Mobile user → Mobile PWA: uses
- External MCP host → Stdio MCP server: invokes tools
- Desktop app → Pane registry hook: initializes (evidence: `packages/app/src/App.tsx`)
- Desktop app → Orchestrator sidebar: renders (evidence: `packages/app/src/App.tsx`)
- Orchestrator sidebar → LLM chat: calls (evidence: `packages/app/src/components/PuppetMasterSidebar.tsx`)
- Orchestrator sidebar → CLI orchestrator panes: selects backend (evidence: `packages/app/src/components/PuppetMasterSidebar.tsx`)
- CLI orchestrator panes → Tauri API client: spawns panes (evidence: `packages/app/src/lib/orchestrator-panes.ts`)
- Terminal UI → Terminal session: mounts (evidence: `packages/app/src/components/OrchestratorTerminal.tsx`)
- Terminal session → Tauri API client: resizes PTY
- Pane registry hook → Tauri API client: subscribes events (evidence: `packages/app/src/hooks/usePaneRegistry.ts`)
- Tauri API client → Rust app commands: invokes commands
- Rust app commands → PTY pane registry: manages panes
- PTY pane registry → Agent adapters: launches agents
- Agent adapters → Agent and shell processes: starts
- Desktop app → Local HTTP bridge: shares local bridge
- Mobile PWA → Local HTTP bridge: mirrors panes
- Stdio MCP server → Local HTTP bridge: forwards tool calls
- CLI launcher → Desktop app: launches
- Local HTTP bridge → Coordination event log: records events
- Local HTTP bridge → Tasks, locks, context: serves coordination
- Tasks, locks, context → Coordination event log: projects events
- Local HTTP bridge → Mobile pairing: supports pairing
- Stdio MCP server → Shared protocol: uses shared types