# penso/herdr-gpui architecture

> Architecture diagram of the GitHub repository penso/herdr-gpui, 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/penso/herdr-gpui
- Repository: https://github.com/penso/herdr-gpui

## Overview

Herdr GPUI is a native desktop client for an already-installed Herdr daemon. A user opens a window for a local or remote session; the client connects to the daemon, exchanges framed protocol messages, and the GUI renders terminal surfaces and sends input while the daemon retains session state. The application also exposes session management, provider usage reporting, GitHub and repository workflows, configuration, notifications, and updates. The README documents the GUI–client–protocol boundary; sampled source supports the session worker and several feature modules, but not every UI-to-service call, so uncertain wiring is omitted.

Main entry points: [`crates/herdr-gpui/src/window.rs`](https://github.com/penso/herdr-gpui/blob/main/crates/herdr-gpui/src/window.rs) (Window and terminal UI), [`crates/herdr-client/src/lib.rs`](https://github.com/penso/herdr-gpui/blob/main/crates/herdr-client/src/lib.rs) (Client connection), [`crates/herdr-gpui/src/app.rs`](https://github.com/penso/herdr-gpui/blob/main/crates/herdr-gpui/src/app.rs) (App bootstrap), [`crates/herdr-client/src/session.rs`](https://github.com/penso/herdr-gpui/blob/main/crates/herdr-client/src/session.rs) (Session state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop UI"]
  node_app["App bootstrap<br/>[app.rs]"]
  node_window["Window and terminal UI<br/>[window.rs]"]
  node_terminal["Terminal rendering<br/>[terminal.rs]"]
  node_sidebar["Workspace sidebar<br/>[sidebar.rs]"]
  node_config["Configuration<br/>[config.rs]"]
  node_notifications["Notifications and sound<br/>[notifications.rs]"]
end

subgraph group_connection["Daemon connection"]
  node_client["Client connection<br/>[lib.rs]"]
  node_discovery["Endpoint discovery<br/>[discovery.rs]"]
  node_sessions["Session state<br/>[session.rs]"]
  node_session_catalog["Session catalog<br/>[sessions.rs]"]
  node_protocol["Wire protocol<br/>[lib.rs]"]
end

subgraph group_workflows["Developer workflows"]
  node_worktree["Worktrees and Git<br/>[worktree.rs]"]
  node_repo_items["Issues and pull requests<br/>[repo_items.rs]"]
  node_pr["Pull request details<br/>[pull_request.rs]"]
  node_agent_context["Agent task context<br/>[context.rs]"]
end

subgraph group_services["Account services"]
  node_github["GitHub sign-in<br/>[github.rs]"]
  node_usage["Usage reporting<br/>[service.rs]"]
  node_usage_providers["Usage providers<br/>[providers.rs]"]
  node_updater["App updater<br/>[updater.rs]"]
end

node_user(("User"))
node_daemon(("Herdr daemon"))
node_terminal_processes(("Terminal processes"))
node_github_service(("GitHub"))
node_ai_services(("AI service providers"))
node_release_service(("Release service"))

node_user -->|"launches"| node_app
node_app -->|"opens window"| node_window
node_window -->|"connects and inputs"| node_client
node_client -->|"discovers endpoint"| node_discovery
node_client -->|"runs worker"| node_sessions
node_sessions -->|"exchanges frames"| node_protocol
node_protocol -->|"sends and receives"| node_daemon
node_daemon -->|"owns sessions"| node_terminal_processes
node_window -->|"renders surface"| node_terminal
node_user -->|"manages sessions"| node_session_catalog
node_user -->|"browses workspaces"| node_sidebar
node_user -->|"sets preferences"| node_config
node_user -->|"receives alerts"| node_notifications
node_user -->|"works with checkouts"| node_worktree
node_user -->|"browses repository items"| node_repo_items
node_user -->|"views pull requests"| node_pr
node_repo_items -->|"writes checkout context"| node_agent_context
node_user -->|"signs in"| node_github
node_github -->|"authenticates and fetches"| node_github_service
node_user -->|"views usage"| node_usage
node_usage -->|"dispatches probes"| node_usage_providers
node_usage_providers -->|"fetches account usage"| node_ai_services
node_user -->|"checks for updates"| node_updater
node_updater -->|"checks releases"| node_release_service

click node_app "https://github.com/penso/herdr-gpui/blob/main/crates/herdr-gpui/src/app.rs"
click node_window "https://github.com/penso/herdr-gpui/blob/main/crates/herdr-gpui/src/window.rs"
click node_terminal "https://github.com/penso/herdr-gpui/blob/main/crates/herdr-gpui/src/terminal.rs"
click node_sidebar "https://github.com/penso/herdr-gpui/blob/main/crates/herdr-gpui/src/sidebar.rs"
click node_config "https://github.com/penso/herdr-gpui/blob/main/crates/herdr-gpui/src/config.rs"
click node_notifications "https://github.com/penso/herdr-gpui/blob/main/crates/herdr-gpui/src/notifications.rs"
click node_client "https://github.com/penso/herdr-gpui/blob/main/crates/herdr-client/src/lib.rs"
click node_discovery "https://github.com/penso/herdr-gpui/blob/main/crates/herdr-client/src/discovery.rs"
click node_sessions "https://github.com/penso/herdr-gpui/blob/main/crates/herdr-client/src/session.rs"
click node_session_catalog "https://github.com/penso/herdr-gpui/blob/main/crates/herdr-client/src/sessions.rs"
click node_protocol "https://github.com/penso/herdr-gpui/blob/main/crates/herdr-protocol/src/lib.rs"
click node_worktree "https://github.com/penso/herdr-gpui/blob/main/crates/herdr-gpui/src/worktree.rs"
click node_repo_items "https://github.com/penso/herdr-gpui/blob/main/crates/herdr-gpui/src/repo_items.rs"
click node_pr "https://github.com/penso/herdr-gpui/blob/main/crates/herdr-gpui/src/pull_request.rs"
click node_agent_context "https://github.com/penso/herdr-gpui/blob/main/crates/herdr-gpui/src/repo_items/context.rs"
click node_github "https://github.com/penso/herdr-gpui/blob/main/crates/herdr-gpui/src/github.rs"
click node_usage "https://github.com/penso/herdr-gpui/blob/main/crates/herdr-gpui/src/usage/service.rs"
click node_usage_providers "https://github.com/penso/herdr-gpui/blob/main/crates/herdr-gpui/src/usage/providers.rs"
click node_updater "https://github.com/penso/herdr-gpui/blob/main/crates/herdr-gpui/src/updater.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_app,node_window,node_terminal,node_sidebar,node_config,node_notifications,node_user toneBlue
class node_client,node_discovery,node_sessions,node_session_catalog,node_protocol toneAmber
class node_worktree,node_repo_items,node_pr,node_agent_context toneMint
class node_github,node_usage,node_usage_providers,node_updater toneRose
class node_daemon,node_terminal_processes,node_github_service,node_ai_services,node_release_service toneIndigo
```

## Components

### Desktop UI

- [App bootstrap](https://github.com/penso/herdr-gpui/blob/main/crates/herdr-gpui/src/app.rs): `crates/herdr-gpui/src/app.rs`
- [Window and terminal UI](https://github.com/penso/herdr-gpui/blob/main/crates/herdr-gpui/src/window.rs): `crates/herdr-gpui/src/window.rs`
- [Terminal rendering](https://github.com/penso/herdr-gpui/blob/main/crates/herdr-gpui/src/terminal.rs): `crates/herdr-gpui/src/terminal.rs`
- [Workspace sidebar](https://github.com/penso/herdr-gpui/blob/main/crates/herdr-gpui/src/sidebar.rs): `crates/herdr-gpui/src/sidebar.rs`
- [Configuration](https://github.com/penso/herdr-gpui/blob/main/crates/herdr-gpui/src/config.rs): `crates/herdr-gpui/src/config.rs`
- [Notifications and sound](https://github.com/penso/herdr-gpui/blob/main/crates/herdr-gpui/src/notifications.rs): `crates/herdr-gpui/src/notifications.rs`

### Daemon connection

- [Client connection](https://github.com/penso/herdr-gpui/blob/main/crates/herdr-client/src/lib.rs): `crates/herdr-client/src/lib.rs`
- [Endpoint discovery](https://github.com/penso/herdr-gpui/blob/main/crates/herdr-client/src/discovery.rs): `crates/herdr-client/src/discovery.rs`
- [Session state](https://github.com/penso/herdr-gpui/blob/main/crates/herdr-client/src/session.rs): `crates/herdr-client/src/session.rs`
- [Session catalog](https://github.com/penso/herdr-gpui/blob/main/crates/herdr-client/src/sessions.rs): `crates/herdr-client/src/sessions.rs`
- [Wire protocol](https://github.com/penso/herdr-gpui/blob/main/crates/herdr-protocol/src/lib.rs): `crates/herdr-protocol/src/lib.rs`

### Developer workflows

- [Worktrees and Git](https://github.com/penso/herdr-gpui/blob/main/crates/herdr-gpui/src/worktree.rs): `crates/herdr-gpui/src/worktree.rs`
- [Issues and pull requests](https://github.com/penso/herdr-gpui/blob/main/crates/herdr-gpui/src/repo_items.rs): `crates/herdr-gpui/src/repo_items.rs`
- [Pull request details](https://github.com/penso/herdr-gpui/blob/main/crates/herdr-gpui/src/pull_request.rs): `crates/herdr-gpui/src/pull_request.rs`
- [Agent task context](https://github.com/penso/herdr-gpui/blob/main/crates/herdr-gpui/src/repo_items/context.rs): `crates/herdr-gpui/src/repo_items/context.rs`

### Account services

- [GitHub sign-in](https://github.com/penso/herdr-gpui/blob/main/crates/herdr-gpui/src/github.rs): `crates/herdr-gpui/src/github.rs`
- [Usage reporting](https://github.com/penso/herdr-gpui/blob/main/crates/herdr-gpui/src/usage/service.rs): `crates/herdr-gpui/src/usage/service.rs`
- [Usage providers](https://github.com/penso/herdr-gpui/blob/main/crates/herdr-gpui/src/usage/providers.rs): `crates/herdr-gpui/src/usage/providers.rs`
- [App updater](https://github.com/penso/herdr-gpui/blob/main/crates/herdr-gpui/src/updater.rs): `crates/herdr-gpui/src/updater.rs`

### Other components

- **User**
- **Herdr daemon**
- **Terminal processes**
- **GitHub**
- **AI service providers**
- **Release service**

## Connections

- User → App bootstrap: launches
- App bootstrap → Window and terminal UI: opens window
- Window and terminal UI → Client connection: connects and inputs
- Client connection → Endpoint discovery: discovers endpoint
- Client connection → Session state: runs worker
- Session state → Wire protocol: exchanges frames
- Wire protocol → Herdr daemon: sends and receives
- Herdr daemon → Terminal processes: owns sessions
- Window and terminal UI → Terminal rendering: renders surface
- User → Session catalog: manages sessions
- User → Workspace sidebar: browses workspaces
- User → Configuration: sets preferences
- User → Notifications and sound: receives alerts
- User → Worktrees and Git: works with checkouts
- User → Issues and pull requests: browses repository items
- User → Pull request details: views pull requests
- Issues and pull requests → Agent task context: writes checkout context
- User → GitHub sign-in: signs in
- GitHub sign-in → GitHub: authenticates and fetches
- User → Usage reporting: views usage
- Usage reporting → Usage providers: dispatches probes
- Usage providers → AI service providers: fetches account usage
- User → App updater: checks for updates
- App updater → Release service: checks releases