# goncharik/hermes-mobile architecture

> Architecture diagram of the GitHub repository goncharik/hermes-mobile, 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/goncharik/hermes-mobile
- Repository: https://github.com/goncharik/hermes-mobile

## Overview

Hermes Mobile is a native iPhone/iPad companion for a self-hosted Hermes Agent; agent execution remains on the server. The principal workflow is to connect and authenticate, browse or create a session, then send prompts and follow streamed responses while handling approvals. Separate branches cover profile and session administration, archived sessions, scheduled jobs, settings, and push notifications. The graph reflects documented capabilities and indexed references; unsampled feature internals and some wiring are intentionally not asserted.

Main entry points: [`HermesKit/Sources/HermesKit/Features/SessionListFeature.swift`](https://github.com/goncharik/hermes-mobile/blob/main/HermesKit/Sources/HermesKit/Features/SessionListFeature.swift) (Session management), [`HermesMobile/Sources/Features/SessionListView.swift`](https://github.com/goncharik/hermes-mobile/blob/main/HermesMobile/Sources/Features/SessionListView.swift) (Session list UI), [`HermesKit/Sources/HermesKit/Features/ChatScreen.swift`](https://github.com/goncharik/hermes-mobile/blob/main/HermesKit/Sources/HermesKit/Features/ChatScreen.swift) (Chat interface), [`HermesKit/Sources/HermesKit/Features/ChatFeature.swift`](https://github.com/goncharik/hermes-mobile/blob/main/HermesKit/Sources/HermesKit/Features/ChatFeature.swift) (Chat workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Mobile experience"]
  node_appview["App shell<br/>[AppView.swift]"]
  node_sessionview["Session list UI"]
  node_sessionrow["Session row"]
  node_settings["Settings"]
  node_chatview["Chat interface<br/>[ChatScreen.swift]"]
  node_transcript["Transcript renderer"]
end

subgraph group_session["Sessions and profiles"]
  node_sessionlist["Session management"]
  node_archived["Archived sessions"]
  node_profiles["Profile management"]
  node_cron["Scheduled jobs<br/>[CronJob.swift]"]
end

subgraph group_conversation["Live conversation"]
  node_chat["Chat workflow<br/>[ChatFeature.swift]"]
  node_chatrow["Transcript rows<br/>[ChatRow.swift]"]
end

subgraph group_connectivity["Connection and services"]
  node_connection["Connection flow"]
  node_reauth["Reauthentication"]
  node_oauth["OAuth login"]
  node_loopback["Callback listener"]
  node_rest["REST API client"]
  node_gateway["WebSocket gateway"]
  node_preferences["User preferences"]
  node_push["Push notifications<br/>[PushClient.swift]"]
end

node_user(("Mobile user"))
node_agent{{"Hermes Agent"}}
node_apns{{"Apple Push service"}}

node_user -->|"uses"| node_appview
node_appview -.->|"connects through"| node_connection
node_connection -.->|"authenticates with"| node_rest
node_connection -.->|"offers OAuth"| node_oauth
node_oauth -->|"starts listener"| node_loopback
node_oauth -->|"exchanges code"| node_rest
node_user -->|"browses"| node_sessionview
node_sessionview -->|"sends actions"| node_sessionlist
node_sessionlist -->|"loads sessions"| node_rest
node_sessionlist -->|"reads preferences"| node_preferences
node_sessionlist -->|"opens archive"| node_archived
node_sessionlist -->|"manages profiles"| node_profiles
node_sessionlist -->|"configures push"| node_push
node_sessionview -->|"renders rows"| node_sessionrow
node_user -->|"composes prompts"| node_chatview
node_chatview -.->|"dispatches actions"| node_chat
node_chat -.->|"sends RPC"| node_gateway
node_gateway -->|"streams events"| node_agent
node_chat -->|"builds transcript"| node_chatrow
node_chatview -->|"renders transcript"| node_transcript
node_transcript -->|"displays rows"| node_chatrow
node_user -->|"configures app"| node_settings
node_settings -.->|"stores options"| node_preferences
node_push -->|"delivers notifications"| node_apns
node_apns -->|"alerts user"| node_user
node_agent -->|"triggers alerts"| node_apns

click node_appview "https://github.com/goncharik/hermes-mobile/blob/main/HermesMobile/Sources/AppView.swift"
click node_connection "https://github.com/goncharik/hermes-mobile/blob/main/HermesKit/Sources/HermesKit/Features/ConnectionFeature.swift"
click node_reauth "https://github.com/goncharik/hermes-mobile/blob/main/HermesKit/Sources/HermesKit/Features/ReauthFeature.swift"
click node_oauth "https://github.com/goncharik/hermes-mobile/blob/main/HermesKit/Sources/HermesKit/Clients/OAuthLoginClient.swift"
click node_loopback "https://github.com/goncharik/hermes-mobile/blob/main/HermesKit/Sources/HermesKit/Clients/LoopbackCallbackListener.swift"
click node_rest "https://github.com/goncharik/hermes-mobile/blob/main/HermesKit/Sources/HermesKit/Clients/HermesRESTClient.swift"
click node_gateway "https://github.com/goncharik/hermes-mobile/blob/main/HermesKit/Sources/HermesKit/Clients/HermesGatewayClient.swift"
click node_sessionlist "https://github.com/goncharik/hermes-mobile/blob/main/HermesKit/Sources/HermesKit/Features/SessionListFeature.swift"
click node_sessionview "https://github.com/goncharik/hermes-mobile/blob/main/HermesMobile/Sources/Features/SessionListView.swift"
click node_sessionrow "https://github.com/goncharik/hermes-mobile/blob/main/HermesMobile/Sources/Features/SessionRowView.swift"
click node_archived "https://github.com/goncharik/hermes-mobile/blob/main/HermesKit/Sources/HermesKit/Features/ArchivedSessionsFeature.swift"
click node_profiles "https://github.com/goncharik/hermes-mobile/blob/main/HermesKit/Sources/HermesKit/Features/AddProfileFeature.swift"
click node_cron "https://github.com/goncharik/hermes-mobile/blob/main/HermesKit/Sources/HermesKit/Models/CronJob.swift"
click node_preferences "https://github.com/goncharik/hermes-mobile/blob/main/HermesKit/Sources/HermesKit/Clients/PreferencesClient.swift"
click node_settings "https://github.com/goncharik/hermes-mobile/blob/main/HermesKit/Sources/HermesKit/Features/SettingsFeature.swift"
click node_chat "https://github.com/goncharik/hermes-mobile/blob/main/HermesKit/Sources/HermesKit/Features/ChatFeature.swift"
click node_chatview "https://github.com/goncharik/hermes-mobile/blob/main/HermesKit/Sources/HermesKit/Features/ChatScreen.swift"
click node_chatrow "https://github.com/goncharik/hermes-mobile/blob/main/HermesKit/Sources/HermesKit/Models/ChatRow.swift"
click node_transcript "https://github.com/goncharik/hermes-mobile/blob/main/HermesMobile/Sources/Features/Chat/Transcript/CollectionTranscriptView.swift"
click node_push "https://github.com/goncharik/hermes-mobile/blob/main/HermesKit/Sources/HermesKit/Clients/PushClient.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_appview,node_sessionview,node_sessionrow,node_settings,node_chatview,node_transcript,node_user toneBlue
class node_sessionlist,node_archived,node_profiles,node_cron toneAmber
class node_chat,node_chatrow toneMint
class node_connection,node_reauth,node_oauth,node_loopback,node_rest,node_gateway,node_preferences,node_push toneRose
class node_agent,node_apns toneIndigo
```

## Components

### Mobile experience

- [App shell](https://github.com/goncharik/hermes-mobile/blob/main/HermesMobile/Sources/AppView.swift): `HermesMobile/Sources/AppView.swift`
- [Session list UI](https://github.com/goncharik/hermes-mobile/blob/main/HermesMobile/Sources/Features/SessionListView.swift): `HermesMobile/Sources/Features/SessionListView.swift`
- [Session row](https://github.com/goncharik/hermes-mobile/blob/main/HermesMobile/Sources/Features/SessionRowView.swift): `HermesMobile/Sources/Features/SessionRowView.swift`
- [Settings](https://github.com/goncharik/hermes-mobile/blob/main/HermesKit/Sources/HermesKit/Features/SettingsFeature.swift): `HermesKit/Sources/HermesKit/Features/SettingsFeature.swift`
- [Chat interface](https://github.com/goncharik/hermes-mobile/blob/main/HermesKit/Sources/HermesKit/Features/ChatScreen.swift): `HermesKit/Sources/HermesKit/Features/ChatScreen.swift`
- [Transcript renderer](https://github.com/goncharik/hermes-mobile/blob/main/HermesMobile/Sources/Features/Chat/Transcript/CollectionTranscriptView.swift): `HermesMobile/Sources/Features/Chat/Transcript/CollectionTranscriptView.swift`

### Sessions and profiles

- [Session management](https://github.com/goncharik/hermes-mobile/blob/main/HermesKit/Sources/HermesKit/Features/SessionListFeature.swift): `HermesKit/Sources/HermesKit/Features/SessionListFeature.swift`
- [Archived sessions](https://github.com/goncharik/hermes-mobile/blob/main/HermesKit/Sources/HermesKit/Features/ArchivedSessionsFeature.swift): `HermesKit/Sources/HermesKit/Features/ArchivedSessionsFeature.swift`
- [Profile management](https://github.com/goncharik/hermes-mobile/blob/main/HermesKit/Sources/HermesKit/Features/AddProfileFeature.swift): `HermesKit/Sources/HermesKit/Features/AddProfileFeature.swift`
- [Scheduled jobs](https://github.com/goncharik/hermes-mobile/blob/main/HermesKit/Sources/HermesKit/Models/CronJob.swift): `HermesKit/Sources/HermesKit/Models/CronJob.swift`

### Live conversation

- [Chat workflow](https://github.com/goncharik/hermes-mobile/blob/main/HermesKit/Sources/HermesKit/Features/ChatFeature.swift): `HermesKit/Sources/HermesKit/Features/ChatFeature.swift`
- [Transcript rows](https://github.com/goncharik/hermes-mobile/blob/main/HermesKit/Sources/HermesKit/Models/ChatRow.swift): `HermesKit/Sources/HermesKit/Models/ChatRow.swift`

### Connection and services

- [Connection flow](https://github.com/goncharik/hermes-mobile/blob/main/HermesKit/Sources/HermesKit/Features/ConnectionFeature.swift): `HermesKit/Sources/HermesKit/Features/ConnectionFeature.swift`
- [Reauthentication](https://github.com/goncharik/hermes-mobile/blob/main/HermesKit/Sources/HermesKit/Features/ReauthFeature.swift): `HermesKit/Sources/HermesKit/Features/ReauthFeature.swift`
- [OAuth login](https://github.com/goncharik/hermes-mobile/blob/main/HermesKit/Sources/HermesKit/Clients/OAuthLoginClient.swift): `HermesKit/Sources/HermesKit/Clients/OAuthLoginClient.swift`
- [Callback listener](https://github.com/goncharik/hermes-mobile/blob/main/HermesKit/Sources/HermesKit/Clients/LoopbackCallbackListener.swift): `HermesKit/Sources/HermesKit/Clients/LoopbackCallbackListener.swift`
- [REST API client](https://github.com/goncharik/hermes-mobile/blob/main/HermesKit/Sources/HermesKit/Clients/HermesRESTClient.swift): `HermesKit/Sources/HermesKit/Clients/HermesRESTClient.swift`
- [WebSocket gateway](https://github.com/goncharik/hermes-mobile/blob/main/HermesKit/Sources/HermesKit/Clients/HermesGatewayClient.swift): `HermesKit/Sources/HermesKit/Clients/HermesGatewayClient.swift`
- [User preferences](https://github.com/goncharik/hermes-mobile/blob/main/HermesKit/Sources/HermesKit/Clients/PreferencesClient.swift): `HermesKit/Sources/HermesKit/Clients/PreferencesClient.swift`
- [Push notifications](https://github.com/goncharik/hermes-mobile/blob/main/HermesKit/Sources/HermesKit/Clients/PushClient.swift): `HermesKit/Sources/HermesKit/Clients/PushClient.swift`

### Other components

- **Mobile user**
- **Hermes Agent**
- **Apple Push service**

## Connections

- Mobile user → App shell: uses
- App shell → Connection flow: connects through
- Connection flow → REST API client: authenticates with (evidence: `HermesKit/Sources/HermesKit/Features/ConnectionFeature.swift`)
- Connection flow → OAuth login: offers OAuth (evidence: `HermesKit/Sources/HermesKit/Features/ConnectionFeature.swift`)
- OAuth login → Callback listener: starts listener (evidence: `HermesKit/Sources/HermesKit/Clients/OAuthLoginClient.swift`)
- OAuth login → REST API client: exchanges code (evidence: `HermesKit/Sources/HermesKit/Clients/OAuthLoginClient.swift`)
- Mobile user → Session list UI: browses
- Session list UI → Session management: sends actions (evidence: `HermesMobile/Sources/Features/SessionListView.swift`)
- Session management → REST API client: loads sessions (evidence: `HermesKit/Sources/HermesKit/Features/SessionListFeature.swift`)
- Session management → User preferences: reads preferences (evidence: `HermesKit/Sources/HermesKit/Features/SessionListFeature.swift`)
- Session management → Archived sessions: opens archive (evidence: `HermesKit/Sources/HermesKit/Features/SessionListFeature.swift`)
- Session management → Profile management: manages profiles (evidence: `HermesKit/Sources/HermesKit/Features/SessionListFeature.swift`)
- Session management → Push notifications: configures push (evidence: `HermesKit/Sources/HermesKit/Features/SessionListFeature.swift`)
- Session list UI → Session row: renders rows (evidence: `HermesMobile/Sources/Features/SessionListView.swift`)
- Mobile user → Chat interface: composes prompts
- Chat interface → Chat workflow: dispatches actions
- Chat workflow → WebSocket gateway: sends RPC (evidence: `HermesKit/Sources/HermesKit/Features/ChatFeature.swift`)
- WebSocket gateway → Hermes Agent: streams events (evidence: `HermesKit/Sources/HermesKit/Clients/HermesGatewayClient.swift`)
- Chat workflow → Transcript rows: builds transcript (evidence: `HermesKit/Sources/HermesKit/Models/ChatRow.swift`)
- Chat interface → Transcript renderer: renders transcript (evidence: `HermesMobile/Sources/Features/Chat/Transcript/CollectionTranscriptView.swift`)
- Transcript renderer → Transcript rows: displays rows (evidence: `HermesMobile/Sources/Features/Chat/Transcript/CollectionTranscriptView.swift`)
- Mobile user → Settings: configures app
- Settings → User preferences: stores options (evidence: `HermesKit/Sources/HermesKit/Features/SettingsFeature.swift`)
- Push notifications → Apple Push service: delivers notifications
- Apple Push service → Mobile user: alerts user
- Hermes Agent → Apple Push service: triggers alerts