# wavetermdev/waveterm architecture

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

- Interactive diagram: https://gitdiagram.com/wavetermdev/waveterm
- Repository: https://github.com/wavetermdev/waveterm

## Overview

Wave Terminal is an AI-integrated desktop terminal for organizing terminal sessions, editors, previews, browsers, and AI assistants into workspaces. Users create and arrange blocks, connect to local or remote shells, and interact with their output; they can also edit and preview files or ask Wave AI to analyze workspace context and perform approved file operations. The frontend communicates with backend services through RPC and events, while controllers manage processes, connections, and durable jobs. README capabilities fill in branches not visible in the sampled source; those implementation details are represented at their supported directory paths.

Main entry points: [`pkg/service/service.go`](https://github.com/wavetermdev/waveterm/blob/main/pkg/service/service.go) (Backend services), [`frontend/app/workspace/workspace.tsx`](https://github.com/wavetermdev/waveterm/blob/main/frontend/app/workspace/workspace.tsx) (Tabs and blocks), [`frontend/app/store/wshclient.ts`](https://github.com/wavetermdev/waveterm/blob/main/frontend/app/store/wshclient.ts) (RPC client), [`pkg/jobcontroller/jobcontroller.go`](https://github.com/wavetermdev/waveterm/blob/main/pkg/jobcontroller/jobcontroller.go) (Durable jobs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop experience"]
  node_frontend["Workspace UI<br/>[app.tsx]"]
  node_workspace["Tabs and blocks<br/>[workspace.tsx]"]
  node_layout["Block layout<br/>[index.ts]"]
  node_terminal["Terminal view<br/>[term.tsx]"]
  node_editor["Code editor<br/>[codeeditor.tsx]"]
  node_previews["File previews<br/>[preview.tsx]"]
  node_webview["Web view<br/>[webview.tsx]"]
end

subgraph group_runtime["Workspace runtime"]
  node_frontendrpc["RPC client<br/>[wshclient.ts]"]
  node_desktopmain["Electron main<br/>[emain.ts]"]
  node_server["Wave server<br/>[main-server.go]"]
  node_services["Backend services<br/>[service.go]"]
  node_blockcontroller["Block controllers<br/>[blockcontroller.go]"]
  node_shell["Shell execution<br/>[shellcontroller.go]"]
  node_jobs["Durable jobs<br/>[jobcontroller.go]"]
  node_jobmanager["Job manager<br/>[jobmanager.go]"]
  node_stream["Output streaming<br/>[streambroker.go]"]
end

subgraph group_ai["AI assistance"]
  node_aipanel["AI panel<br/>[aipanel.tsx]"]
  node_ai["AI orchestration<br/>[usechat.go]"]
  node_aitools["AI tools<br/>[tools.go]"]
  node_providers["Model providers<br/>[usechat-backend.go]"]
end

subgraph group_connections["Connections and files"]
  node_connections["SSH connections<br/>[conncontroller.go]"]
  node_wsh["WSH commands<br/>[wshcmd-root.go]"]
  node_files["Remote file access<br/>[wshfs.go]"]
end

subgraph group_state["Persistence and events"]
  node_store[("Wave object store<br/>[wstore.go]")]
  node_filestore[("Block file store<br/>[blockstore.go]")]
  node_events["Event broker<br/>[wps.go]"]
end

node_user(("Wave user"))
node_externalmodels(("Model services"))
node_remotehost(("SSH host"))

node_user -->|"uses"| node_frontend
node_frontend -->|"renders"| node_workspace
node_workspace -->|"arranges"| node_layout
node_workspace -->|"hosts"| node_terminal
node_workspace -->|"hosts"| node_editor
node_workspace -->|"hosts"| node_previews
node_workspace -->|"hosts"| node_webview
node_workspace -->|"hosts"| node_aipanel
node_frontend -->|"requests"| node_frontendrpc
node_frontendrpc -->|"IPC requests"| node_desktopmain
node_desktopmain -->|"RPC and events"| node_server
node_server -->|"dispatches"| node_services
node_services -->|"controls blocks"| node_blockcontroller
node_blockcontroller -->|"runs shell"| node_shell
node_shell -->|"starts remote shells"| node_connections
node_connections -->|"connects"| node_remotehost
node_services -->|"manages jobs"| node_jobs
node_jobs -->|"attaches job"| node_jobmanager
node_jobs -->|"streams output"| node_stream
node_jobmanager -->|"transfers output"| node_stream
node_stream -->|"delivers output"| node_terminal
node_services -->|"accesses files"| node_files
node_files -->|"reads and writes"| node_remotehost
node_editor -->|"file operations"| node_frontendrpc
node_previews -->|"requests file data"| node_frontendrpc
node_aipanel -->|"submits chat"| node_frontendrpc
node_services -->|"routes chat"| node_ai
node_ai -->|"selects backend"| node_providers
node_providers -.->|"sends prompts"| node_externalmodels
node_ai -->|"invokes tools"| node_aitools
node_aitools -->|"file operations"| node_files
node_aitools -.->|"reads context"| node_terminal
node_services -->|"reads and writes"| node_store
node_jobs -->|"updates job state"| node_store
node_jobs -->|"stores output"| node_filestore
node_services -->|"publishes events"| node_events
node_events -->|"delivers updates"| node_frontendrpc
node_wsh -->|"invokes commands"| node_services

click node_frontend "https://github.com/wavetermdev/waveterm/blob/main/frontend/app/app.tsx"
click node_workspace "https://github.com/wavetermdev/waveterm/blob/main/frontend/app/workspace/workspace.tsx"
click node_layout "https://github.com/wavetermdev/waveterm/blob/main/frontend/layout/index.ts"
click node_terminal "https://github.com/wavetermdev/waveterm/blob/main/frontend/app/view/term/term.tsx"
click node_editor "https://github.com/wavetermdev/waveterm/blob/main/frontend/app/view/codeeditor/codeeditor.tsx"
click node_previews "https://github.com/wavetermdev/waveterm/blob/main/frontend/app/view/preview/preview.tsx"
click node_webview "https://github.com/wavetermdev/waveterm/blob/main/frontend/app/view/webview/webview.tsx"
click node_aipanel "https://github.com/wavetermdev/waveterm/blob/main/frontend/app/aipanel/aipanel.tsx"
click node_frontendrpc "https://github.com/wavetermdev/waveterm/blob/main/frontend/app/store/wshclient.ts"
click node_desktopmain "https://github.com/wavetermdev/waveterm/blob/main/emain/emain.ts"
click node_server "https://github.com/wavetermdev/waveterm/blob/main/cmd/server/main-server.go"
click node_services "https://github.com/wavetermdev/waveterm/blob/main/pkg/service/service.go"
click node_blockcontroller "https://github.com/wavetermdev/waveterm/blob/main/pkg/blockcontroller/blockcontroller.go"
click node_shell "https://github.com/wavetermdev/waveterm/blob/main/pkg/blockcontroller/shellcontroller.go"
click node_jobs "https://github.com/wavetermdev/waveterm/blob/main/pkg/jobcontroller/jobcontroller.go"
click node_jobmanager "https://github.com/wavetermdev/waveterm/blob/main/pkg/jobmanager/jobmanager.go"
click node_stream "https://github.com/wavetermdev/waveterm/blob/main/pkg/streamclient/streambroker.go"
click node_connections "https://github.com/wavetermdev/waveterm/blob/main/pkg/remote/conncontroller/conncontroller.go"
click node_wsh "https://github.com/wavetermdev/waveterm/blob/main/cmd/wsh/cmd/wshcmd-root.go"
click node_files "https://github.com/wavetermdev/waveterm/blob/main/pkg/remote/fileshare/wshfs/wshfs.go"
click node_ai "https://github.com/wavetermdev/waveterm/blob/main/pkg/aiusechat/usechat.go"
click node_aitools "https://github.com/wavetermdev/waveterm/blob/main/pkg/aiusechat/tools.go"
click node_providers "https://github.com/wavetermdev/waveterm/blob/main/pkg/aiusechat/usechat-backend.go"
click node_store "https://github.com/wavetermdev/waveterm/blob/main/pkg/wstore/wstore.go"
click node_filestore "https://github.com/wavetermdev/waveterm/blob/main/pkg/filestore/blockstore.go"
click node_events "https://github.com/wavetermdev/waveterm/blob/main/pkg/wps/wps.go"

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_frontend,node_workspace,node_layout,node_terminal,node_editor,node_previews,node_webview,node_user toneBlue
class node_frontendrpc,node_desktopmain,node_server,node_services,node_blockcontroller,node_shell,node_jobs,node_jobmanager,node_stream toneAmber
class node_aipanel,node_ai,node_aitools,node_providers toneMint
class node_connections,node_wsh,node_files toneRose
class node_store,node_filestore,node_events,node_externalmodels,node_remotehost toneIndigo
```

## Components

### Desktop experience

- [Workspace UI](https://github.com/wavetermdev/waveterm/blob/main/frontend/app/app.tsx): `frontend/app/app.tsx`
- [Tabs and blocks](https://github.com/wavetermdev/waveterm/blob/main/frontend/app/workspace/workspace.tsx): `frontend/app/workspace/workspace.tsx`
- [Block layout](https://github.com/wavetermdev/waveterm/blob/main/frontend/layout/index.ts): `frontend/layout/index.ts`
- [Terminal view](https://github.com/wavetermdev/waveterm/blob/main/frontend/app/view/term/term.tsx): `frontend/app/view/term/term.tsx`
- [Code editor](https://github.com/wavetermdev/waveterm/blob/main/frontend/app/view/codeeditor/codeeditor.tsx): `frontend/app/view/codeeditor/codeeditor.tsx`
- [File previews](https://github.com/wavetermdev/waveterm/blob/main/frontend/app/view/preview/preview.tsx): `frontend/app/view/preview/preview.tsx`
- [Web view](https://github.com/wavetermdev/waveterm/blob/main/frontend/app/view/webview/webview.tsx): `frontend/app/view/webview/webview.tsx`

### Workspace runtime

- [RPC client](https://github.com/wavetermdev/waveterm/blob/main/frontend/app/store/wshclient.ts): `frontend/app/store/wshclient.ts`
- [Electron main](https://github.com/wavetermdev/waveterm/blob/main/emain/emain.ts): `emain/emain.ts`
- [Wave server](https://github.com/wavetermdev/waveterm/blob/main/cmd/server/main-server.go): `cmd/server/main-server.go`
- [Backend services](https://github.com/wavetermdev/waveterm/blob/main/pkg/service/service.go): `pkg/service/service.go`
- [Block controllers](https://github.com/wavetermdev/waveterm/blob/main/pkg/blockcontroller/blockcontroller.go): `pkg/blockcontroller/blockcontroller.go`
- [Shell execution](https://github.com/wavetermdev/waveterm/blob/main/pkg/blockcontroller/shellcontroller.go): `pkg/blockcontroller/shellcontroller.go`
- [Durable jobs](https://github.com/wavetermdev/waveterm/blob/main/pkg/jobcontroller/jobcontroller.go): `pkg/jobcontroller/jobcontroller.go`
- [Job manager](https://github.com/wavetermdev/waveterm/blob/main/pkg/jobmanager/jobmanager.go): `pkg/jobmanager/jobmanager.go`
- [Output streaming](https://github.com/wavetermdev/waveterm/blob/main/pkg/streamclient/streambroker.go): `pkg/streamclient/streambroker.go`

### AI assistance

- [AI panel](https://github.com/wavetermdev/waveterm/blob/main/frontend/app/aipanel/aipanel.tsx): `frontend/app/aipanel/aipanel.tsx`
- [AI orchestration](https://github.com/wavetermdev/waveterm/blob/main/pkg/aiusechat/usechat.go): `pkg/aiusechat/usechat.go`
- [AI tools](https://github.com/wavetermdev/waveterm/blob/main/pkg/aiusechat/tools.go): `pkg/aiusechat/tools.go`
- [Model providers](https://github.com/wavetermdev/waveterm/blob/main/pkg/aiusechat/usechat-backend.go): `pkg/aiusechat/usechat-backend.go`

### Connections and files

- [SSH connections](https://github.com/wavetermdev/waveterm/blob/main/pkg/remote/conncontroller/conncontroller.go): `pkg/remote/conncontroller/conncontroller.go`
- [WSH commands](https://github.com/wavetermdev/waveterm/blob/main/cmd/wsh/cmd/wshcmd-root.go): `cmd/wsh/cmd/wshcmd-root.go`
- [Remote file access](https://github.com/wavetermdev/waveterm/blob/main/pkg/remote/fileshare/wshfs/wshfs.go): `pkg/remote/fileshare/wshfs/wshfs.go`

### Persistence and events

- [Wave object store](https://github.com/wavetermdev/waveterm/blob/main/pkg/wstore/wstore.go): `pkg/wstore/wstore.go`
- [Block file store](https://github.com/wavetermdev/waveterm/blob/main/pkg/filestore/blockstore.go): `pkg/filestore/blockstore.go`
- [Event broker](https://github.com/wavetermdev/waveterm/blob/main/pkg/wps/wps.go): `pkg/wps/wps.go`

### Other components

- **Wave user**
- **Model services**
- **SSH host**

## Connections

- Wave user → Workspace UI: uses
- Workspace UI → Tabs and blocks: renders
- Tabs and blocks → Block layout: arranges
- Tabs and blocks → Terminal view: hosts
- Tabs and blocks → Code editor: hosts
- Tabs and blocks → File previews: hosts
- Tabs and blocks → Web view: hosts
- Tabs and blocks → AI panel: hosts
- Workspace UI → RPC client: requests
- RPC client → Electron main: IPC requests
- Electron main → Wave server: RPC and events
- Wave server → Backend services: dispatches
- Backend services → Block controllers: controls blocks
- Block controllers → Shell execution: runs shell
- Shell execution → SSH connections: starts remote shells
- SSH connections → SSH host: connects
- Backend services → Durable jobs: manages jobs
- Durable jobs → Job manager: attaches job
- Durable jobs → Output streaming: streams output
- Job manager → Output streaming: transfers output
- Output streaming → Terminal view: delivers output
- Backend services → Remote file access: accesses files
- Remote file access → SSH host: reads and writes
- Code editor → RPC client: file operations
- File previews → RPC client: requests file data
- AI panel → RPC client: submits chat
- Backend services → AI orchestration: routes chat
- AI orchestration → Model providers: selects backend
- Model providers → Model services: sends prompts
- AI orchestration → AI tools: invokes tools
- AI tools → Remote file access: file operations
- AI tools → Terminal view: reads context
- Backend services → Wave object store: reads and writes
- Durable jobs → Wave object store: updates job state
- Durable jobs → Block file store: stores output
- Backend services → Event broker: publishes events
- Event broker → RPC client: delivers updates
- WSH commands → Backend services: invokes commands
