# zingerlittlebee/heeler architecture

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

- Interactive diagram: https://gitdiagram.com/zingerlittlebee/heeler
- Repository: https://github.com/zingerlittlebee/heeler

## Overview

Heeler is a native iOS console for herdr agents. The main path is Host setup and pairing, SSH connection, live agent/event discovery, terminal attach and Composer input; supporting branches cover shell/SFTP, encrypted notifications, and Live Activities. The README documents these capabilities, but only a subset of implementation is excerpted, so undocumented internal links are omitted or marked unverified.

Main entry points: [`Packages/HeelerSSH/Sources/HeelerSSH/SessionDriver.swift`](https://github.com/zingerlittlebee/heeler/blob/main/Packages/HeelerSSH/Sources/HeelerSSH/SessionDriver.swift) (SSH Sessions), [`Sources/Heeler/Terminal/TerminalInputController.swift`](https://github.com/zingerlittlebee/heeler/blob/main/Sources/Heeler/Terminal/TerminalInputController.swift) (Terminal Attach), [`plugin/src/pairing-session.js`](https://github.com/zingerlittlebee/heeler/blob/main/plugin/src/pairing-session.js) (Key Pairing), [`Sources/HeelerNotificationService/NotificationService.swift`](https://github.com/zingerlittlebee/heeler/blob/main/Sources/HeelerNotificationService/NotificationService.swift) (Notification Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["iOS Console"]
  node_console["Agent Console<br/>[ConsoleAgent.swift]"]
  node_hosts["Host Records<br/>[Host.swift]"]
  node_hostlist["Host Browser<br/>[HostListView.swift]"]
  node_transport["Herdr Transport<br/>[Transport.swift]"]
  node_events["Event Stream"]
  node_attach["Terminal Attach"]
  node_messageindex["Message Index"]
  node_skills["Agent Skills<br/>[AgentSkill.swift]"]
end

subgraph group_ssh["SSH Access"]
  node_sshdriver["SSH Sessions"]
  node_sftp["SFTP Attachments"]
end

subgraph group_push["Pairing and Push"]
  node_pairing["Key Pairing<br/>[pairing-session.js]"]
  node_authorized["Authorized Keys<br/>[authorized-keys.js]"]
  node_notifyplugin["Notify Hook<br/>[notify-hook.js]"]
  node_relay["Push Relay<br/>[worker.js]"]
  node_apns["Apple Push"]
  node_notification["Notification Service"]
  node_notifenv["Notification Envelope"]
  node_codec["Sealed Codec"]
  node_keyring["Notification Keys"]
  node_router["Notification Routing"]
  node_relayclient(("Host Plugin"))
end

subgraph group_activity["Live Activities"]
  node_activityenv["Activity Envelope"]
  node_decryptor["Activity Decryptor"]
  node_widget["Activity Widget"]
end

node_user(("iOS User"))
node_herdr(("herdr Host"))

node_user -.->|"manages Hosts"| node_hostlist
node_hostlist -.->|"configures"| node_hosts
node_console -->|"uses Host"| node_hosts
node_console -.->|"shows updates"| node_events
node_events -->|"uses transport"| node_transport
node_transport -.->|"opens SSH"| node_sshdriver
node_sshdriver -.->|"connects"| node_herdr
node_user -.->|"steers Agent"| node_attach
node_attach -.->|"writes PTY"| node_sshdriver
node_attach -->|"indexes drafts"| node_messageindex
node_user -.->|"selects skills"| node_skills
node_user -.->|"stages files"| node_sftp
node_sftp -->|"uses session"| node_sshdriver
node_user -.->|"scans code"| node_pairing
node_pairing -->|"edits keys"| node_authorized
node_pairing -.->|"enrolls key"| node_herdr
node_relayclient -.->|"emits alerts"| node_notifyplugin
node_notifyplugin -.->|"forwards envelope"| node_relay
node_relay -->|"sends push"| node_apns
node_apns -.->|"delivers push"| node_notification
node_notification -->|"loads keys"| node_keyring
node_notification -->|"renders alert"| node_notifenv
node_notifenv -->|"decrypts with"| node_codec
node_user -.->|"opens notification"| node_router
node_router -->|"routes Agent"| node_console
node_activityenv -->|"seals details"| node_codec
node_decryptor -.->|"opens details"| node_activityenv
node_widget -->|"renders state"| node_decryptor

click node_console "https://github.com/zingerlittlebee/heeler/blob/main/Sources/Heeler/Console/ConsoleAgent.swift"
click node_hosts "https://github.com/zingerlittlebee/heeler/blob/main/Sources/Heeler/Hosts/Host.swift"
click node_hostlist "https://github.com/zingerlittlebee/heeler/blob/main/Sources/Heeler/Hosts/HostListView.swift"
click node_transport "https://github.com/zingerlittlebee/heeler/blob/main/Sources/Heeler/Transport/Transport.swift"
click node_events "https://github.com/zingerlittlebee/heeler/blob/main/Sources/Heeler/Transport/EventsSession.swift"
click node_attach "https://github.com/zingerlittlebee/heeler/blob/main/Sources/Heeler/Terminal/TerminalInputController.swift"
click node_messageindex "https://github.com/zingerlittlebee/heeler/blob/main/Sources/Heeler/Terminal/AttachUserMessageIndex.swift"
click node_skills "https://github.com/zingerlittlebee/heeler/blob/main/Sources/Heeler/Skills/AgentSkill.swift"
click node_sshdriver "https://github.com/zingerlittlebee/heeler/blob/main/Packages/HeelerSSH/Sources/HeelerSSH/SessionDriver.swift"
click node_sftp "https://github.com/zingerlittlebee/heeler/blob/main/Packages/HeelerSSH/Sources/HeelerSSH/SSHSFTPClient.swift"
click node_pairing "https://github.com/zingerlittlebee/heeler/blob/main/plugin/src/pairing-session.js"
click node_authorized "https://github.com/zingerlittlebee/heeler/blob/main/plugin/src/authorized-keys.js"
click node_notifyplugin "https://github.com/zingerlittlebee/heeler/blob/main/plugin/src/notify-hook.js"
click node_relay "https://github.com/zingerlittlebee/heeler/blob/main/relay/src/worker.js"
click node_notification "https://github.com/zingerlittlebee/heeler/blob/main/Sources/HeelerNotificationService/NotificationService.swift"
click node_notifenv "https://github.com/zingerlittlebee/heeler/blob/main/Sources/HeelerNotificationCore/NotificationEnvelope.swift"
click node_codec "https://github.com/zingerlittlebee/heeler/blob/main/Sources/HeelerNotificationCore/SealedEnvelopeCodec.swift"
click node_keyring "https://github.com/zingerlittlebee/heeler/blob/main/Sources/HeelerNotificationCore/NotificationKeyStore.swift"
click node_router "https://github.com/zingerlittlebee/heeler/blob/main/Sources/Heeler/Notifications/AgentNotificationRouter.swift"
click node_activityenv "https://github.com/zingerlittlebee/heeler/blob/main/Sources/HeelerActivityCore/AgentActivityEnvelope.swift"
click node_decryptor "https://github.com/zingerlittlebee/heeler/blob/main/Sources/HeelerWidgets/AgentActivityDecryptor.swift"
click node_widget "https://github.com/zingerlittlebee/heeler/blob/main/Sources/HeelerWidgets/AgentLiveActivityWidget.swift"

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_console,node_hosts,node_hostlist,node_transport,node_events,node_attach,node_messageindex,node_skills,node_user toneBlue
class node_sshdriver,node_sftp toneAmber
class node_pairing,node_authorized,node_notifyplugin,node_relay,node_apns,node_notification,node_notifenv,node_codec,node_keyring,node_router,node_relayclient toneMint
class node_activityenv,node_decryptor,node_widget toneRose
class node_herdr toneIndigo
```

## Components

### iOS Console

- [Agent Console](https://github.com/zingerlittlebee/heeler/blob/main/Sources/Heeler/Console/ConsoleAgent.swift): `Sources/Heeler/Console/ConsoleAgent.swift`
- [Host Records](https://github.com/zingerlittlebee/heeler/blob/main/Sources/Heeler/Hosts/Host.swift): `Sources/Heeler/Hosts/Host.swift`
- [Host Browser](https://github.com/zingerlittlebee/heeler/blob/main/Sources/Heeler/Hosts/HostListView.swift): `Sources/Heeler/Hosts/HostListView.swift`
- [Herdr Transport](https://github.com/zingerlittlebee/heeler/blob/main/Sources/Heeler/Transport/Transport.swift): `Sources/Heeler/Transport/Transport.swift`
- [Event Stream](https://github.com/zingerlittlebee/heeler/blob/main/Sources/Heeler/Transport/EventsSession.swift): `Sources/Heeler/Transport/EventsSession.swift`
- [Terminal Attach](https://github.com/zingerlittlebee/heeler/blob/main/Sources/Heeler/Terminal/TerminalInputController.swift): `Sources/Heeler/Terminal/TerminalInputController.swift`
- [Message Index](https://github.com/zingerlittlebee/heeler/blob/main/Sources/Heeler/Terminal/AttachUserMessageIndex.swift): `Sources/Heeler/Terminal/AttachUserMessageIndex.swift`
- [Agent Skills](https://github.com/zingerlittlebee/heeler/blob/main/Sources/Heeler/Skills/AgentSkill.swift): `Sources/Heeler/Skills/AgentSkill.swift`

### SSH Access

- [SSH Sessions](https://github.com/zingerlittlebee/heeler/blob/main/Packages/HeelerSSH/Sources/HeelerSSH/SessionDriver.swift): `Packages/HeelerSSH/Sources/HeelerSSH/SessionDriver.swift`
- [SFTP Attachments](https://github.com/zingerlittlebee/heeler/blob/main/Packages/HeelerSSH/Sources/HeelerSSH/SSHSFTPClient.swift): `Packages/HeelerSSH/Sources/HeelerSSH/SSHSFTPClient.swift`

### Pairing and Push

- [Key Pairing](https://github.com/zingerlittlebee/heeler/blob/main/plugin/src/pairing-session.js): `plugin/src/pairing-session.js`
- [Authorized Keys](https://github.com/zingerlittlebee/heeler/blob/main/plugin/src/authorized-keys.js): `plugin/src/authorized-keys.js`
- [Notify Hook](https://github.com/zingerlittlebee/heeler/blob/main/plugin/src/notify-hook.js): `plugin/src/notify-hook.js`
- [Push Relay](https://github.com/zingerlittlebee/heeler/blob/main/relay/src/worker.js): `relay/src/worker.js`
- **Apple Push**
- [Notification Service](https://github.com/zingerlittlebee/heeler/blob/main/Sources/HeelerNotificationService/NotificationService.swift): `Sources/HeelerNotificationService/NotificationService.swift`
- [Notification Envelope](https://github.com/zingerlittlebee/heeler/blob/main/Sources/HeelerNotificationCore/NotificationEnvelope.swift): `Sources/HeelerNotificationCore/NotificationEnvelope.swift`
- [Sealed Codec](https://github.com/zingerlittlebee/heeler/blob/main/Sources/HeelerNotificationCore/SealedEnvelopeCodec.swift): `Sources/HeelerNotificationCore/SealedEnvelopeCodec.swift`
- [Notification Keys](https://github.com/zingerlittlebee/heeler/blob/main/Sources/HeelerNotificationCore/NotificationKeyStore.swift): `Sources/HeelerNotificationCore/NotificationKeyStore.swift`
- [Notification Routing](https://github.com/zingerlittlebee/heeler/blob/main/Sources/Heeler/Notifications/AgentNotificationRouter.swift): `Sources/Heeler/Notifications/AgentNotificationRouter.swift`
- **Host Plugin**

### Live Activities

- [Activity Envelope](https://github.com/zingerlittlebee/heeler/blob/main/Sources/HeelerActivityCore/AgentActivityEnvelope.swift): `Sources/HeelerActivityCore/AgentActivityEnvelope.swift`
- [Activity Decryptor](https://github.com/zingerlittlebee/heeler/blob/main/Sources/HeelerWidgets/AgentActivityDecryptor.swift): `Sources/HeelerWidgets/AgentActivityDecryptor.swift`
- [Activity Widget](https://github.com/zingerlittlebee/heeler/blob/main/Sources/HeelerWidgets/AgentLiveActivityWidget.swift): `Sources/HeelerWidgets/AgentLiveActivityWidget.swift`

### Other components

- **iOS User**
- **herdr Host**

## Connections

- iOS User → Host Browser: manages Hosts (evidence: `README.md`)
- Host Browser → Host Records: configures (evidence: `README.md`)
- Agent Console → Host Records: uses Host (evidence: `Sources/Heeler/Console/ConsoleAgent.swift`)
- Agent Console → Event Stream: shows updates (evidence: `README.md`)
- Event Stream → Herdr Transport: uses transport (evidence: `Sources/Heeler/Transport/EventsSession.swift`)
- Herdr Transport → SSH Sessions: opens SSH (evidence: `README.md`)
- SSH Sessions → herdr Host: connects (evidence: `README.md`)
- iOS User → Terminal Attach: steers Agent (evidence: `README.md`)
- Terminal Attach → SSH Sessions: writes PTY (evidence: `README.md`)
- Terminal Attach → Message Index: indexes drafts (evidence: `Sources/Heeler/Terminal/TerminalInputController.swift`)
- iOS User → Agent Skills: selects skills (evidence: `README.md`)
- iOS User → SFTP Attachments: stages files (evidence: `README.md`)
- SFTP Attachments → SSH Sessions: uses session (evidence: `Packages/HeelerSSH/Sources/HeelerSSH/SSHSFTPClient.swift`)
- iOS User → Key Pairing: scans code (evidence: `README.md`)
- Key Pairing → Authorized Keys: edits keys (evidence: `plugin/src/pairing-session.js`)
- Key Pairing → herdr Host: enrolls key (evidence: `README.md`)
- Host Plugin → Notify Hook: emits alerts (evidence: `README.md`)
- Notify Hook → Push Relay: forwards envelope (evidence: `README.md`)
- Push Relay → Apple Push: sends push (evidence: `relay/src/worker.js`)
- Apple Push → Notification Service: delivers push (evidence: `README.md`)
- Notification Service → Notification Keys: loads keys (evidence: `Sources/HeelerNotificationService/NotificationService.swift`)
- Notification Service → Notification Envelope: renders alert (evidence: `Sources/HeelerNotificationService/NotificationService.swift`)
- Notification Envelope → Sealed Codec: decrypts with (evidence: `Sources/HeelerNotificationCore/NotificationEnvelope.swift`)
- iOS User → Notification Routing: opens notification (evidence: `README.md`)
- Notification Routing → Agent Console: routes Agent (evidence: `Sources/Heeler/Notifications/AgentNotificationRouter.swift`)
- Activity Envelope → Sealed Codec: seals details (evidence: `Sources/HeelerActivityCore/AgentActivityEnvelope.swift`)
- Activity Decryptor → Activity Envelope: opens details (evidence: `Sources/HeelerWidgets/AgentActivityDecryptor.swift`)
- Activity Widget → Activity Decryptor: renders state (evidence: `Sources/HeelerWidgets/AgentLiveActivityWidget.swift`)
