# uzairansaruzi/hermex architecture

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

- Interactive diagram: https://gitdiagram.com/uzairansaruzi/hermex
- Repository: https://github.com/uzairansaruzi/hermex

## Overview

Hermex is a native iPhone control client for a self-hosted Hermes agent; the server performs the computation and retains the agent’s data. The principal workflow is connecting and signing in, selecting or resuming a session, sending a configured message, then viewing its streamed response and tool activity. Other documented branches cover scheduled tasks, skills, workspace and Git browsing, memory and usage insights, and direct-Hermes Bot Mode. The graph uses README capabilities and paths in the tree; unsampled implementation details and wiring are not asserted.

Main entry points: [`HermesMobile/Features/Chat/ChatViewModel.swift`](https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Features/Chat/ChatViewModel.swift) (Chat orchestration), [`HermesMobile/Features/SessionList/SessionListView.swift`](https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Features/SessionList/SessionListView.swift) (Session browser), [`HermesMobile/Networking/APIClient.swift`](https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Networking/APIClient.swift) (Server API), [`HermesMobile/Networking/APIClient+Chat.swift`](https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Networking/APIClient%2BChat.swift) (Chat endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and access"]
  node_root["App shell<br/>[ContentView.swift]"]
  node_auth["Sign-in<br/>[AuthManager.swift]"]
  node_onboarding["Connection setup"]
  node_settings["Providers and models"]
  node_push["Optional push"]
  node_share["Shared content"]
end

subgraph group_conversation["Sessions and chat"]
  node_sessions["Session browser"]
  node_sessionvm["Session actions"]
  node_chat["Chat screen<br/>[ChatView.swift]"]
  node_chatvm["Chat orchestration"]
  node_composer["Message composer"]
  node_stream["Stream handling"]
end

subgraph group_agent["Agent features"]
  node_tasks["Scheduled tasks<br/>[TasksView.swift]"]
  node_skills["Skills browser<br/>[SkillsView.swift]"]
  node_memory["Memory panel<br/>[MemoryView.swift]"]
  node_insights["Usage insights<br/>[InsightsView.swift]"]
  node_bots["Bot Mode<br/>[BotChatView.swift]"]
end

subgraph group_workspace["Workspace tools"]
  node_workspaceview["Workspace browser"]
  node_git["Git workspace"]
end

subgraph group_transport["Network and state"]
  node_cache[("Offline cache<br/>[CacheStore.swift]")]
  node_api["Server API<br/>[APIClient.swift]"]
  node_chatapi["Chat endpoints"]
  node_sessionapi["Session endpoints"]
  node_botapi["Bot connection<br/>[BotClient.swift]"]
  node_workspaceapi["Workspace endpoints"]
end

node_person(("iPhone user"))
node_server["Hermes server"]

node_person -->|"uses"| node_root
node_root -->|"starts setup"| node_onboarding
node_onboarding -->|"configures access"| node_auth
node_person -->|"selects session"| node_sessions
node_sessions -->|"requests actions"| node_sessionvm
node_sessionvm -->|"loads or mutates"| node_sessionapi
node_sessionapi -->|"sends requests"| node_api
node_api -->|"calls"| node_server
node_sessions -->|"opens conversation"| node_chat
node_person -->|"writes message"| node_composer
node_chat -->|"presents state"| node_chatvm
node_composer -->|"submits message"| node_chatvm
node_chatvm -->|"sends and steers"| node_chatapi
node_chatapi -->|"sends requests"| node_api
node_chatvm -->|"tracks response"| node_stream
node_stream -->|"receives events"| node_chatapi
node_chatvm -->|"caches history"| node_cache
node_sessions -->|"reads offline"| node_cache
node_person -->|"manages schedules"| node_tasks
node_person -->|"browses skills"| node_skills
node_person -->|"reads memory"| node_memory
node_person -->|"views usage"| node_insights
node_person -->|"opens Bot Mode"| node_bots
node_bots -->|"connects directly"| node_botapi
node_botapi -.->|"connects"| node_server
node_person -->|"browses files"| node_workspaceview
node_person -->|"reviews changes"| node_git
node_workspaceview -->|"requests files"| node_workspaceapi
node_git -->|"uses server API"| node_api
node_person -->|"chooses providers"| node_settings
node_person -.->|"taps notification"| node_push
node_person -->|"shares content"| node_share

click node_root "https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/ContentView.swift"
click node_auth "https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Auth/AuthManager.swift"
click node_onboarding "https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Features/Onboarding/OnboardingView.swift"
click node_sessions "https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Features/SessionList/SessionListView.swift"
click node_sessionvm "https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Features/SessionList/SessionListViewModel.swift"
click node_chat "https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Features/Chat/ChatView.swift"
click node_chatvm "https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Features/Chat/ChatViewModel.swift"
click node_composer "https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Features/Chat/ChatComposerView.swift"
click node_stream "https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Features/Chat/ChatStreamCoordinator.swift"
click node_cache "https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Persistence/CacheStore.swift"
click node_api "https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Networking/APIClient.swift"
click node_chatapi "https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Networking/APIClient%2BChat.swift"
click node_sessionapi "https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Networking/APIClient%2BSessions.swift"
click node_tasks "https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Features/Tasks/TasksView.swift"
click node_skills "https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Features/Skills/SkillsView.swift"
click node_memory "https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Features/Memory/MemoryView.swift"
click node_insights "https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Features/Insights/InsightsView.swift"
click node_bots "https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Features/Bots/BotChatView.swift"
click node_botapi "https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Networking/Bots/BotClient.swift"
click node_workspaceview "https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Features/Workspace/FileBrowserView.swift"
click node_git "https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Features/Workspace/GitWorkspaceView.swift"
click node_workspaceapi "https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Networking/APIClient%2BWorkspace.swift"
click node_settings "https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Features/Settings/ProvidersView.swift"
click node_push "https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Push/PushNotificationRouter.swift"
click node_share "https://github.com/uzairansaruzi/hermex/blob/master/HermesShareExtension/ShareViewController.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_root,node_auth,node_onboarding,node_settings,node_push,node_share,node_person toneBlue
class node_sessions,node_sessionvm,node_chat,node_chatvm,node_composer,node_stream toneAmber
class node_tasks,node_skills,node_memory,node_insights,node_bots,node_server toneMint
class node_workspaceview,node_git toneRose
class node_cache,node_api,node_chatapi,node_sessionapi,node_botapi,node_workspaceapi toneIndigo
```

## Components

### App and access

- [App shell](https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/ContentView.swift): `HermesMobile/ContentView.swift`
- [Sign-in](https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Auth/AuthManager.swift): `HermesMobile/Auth/AuthManager.swift`
- [Connection setup](https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Features/Onboarding/OnboardingView.swift): `HermesMobile/Features/Onboarding/OnboardingView.swift`
- [Providers and models](https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Features/Settings/ProvidersView.swift): `HermesMobile/Features/Settings/ProvidersView.swift`
- [Optional push](https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Push/PushNotificationRouter.swift): `HermesMobile/Push/PushNotificationRouter.swift`
- [Shared content](https://github.com/uzairansaruzi/hermex/blob/master/HermesShareExtension/ShareViewController.swift): `HermesShareExtension/ShareViewController.swift`

### Sessions and chat

- [Session browser](https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Features/SessionList/SessionListView.swift): `HermesMobile/Features/SessionList/SessionListView.swift`
- [Session actions](https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Features/SessionList/SessionListViewModel.swift): `HermesMobile/Features/SessionList/SessionListViewModel.swift`
- [Chat screen](https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Features/Chat/ChatView.swift): `HermesMobile/Features/Chat/ChatView.swift`
- [Chat orchestration](https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Features/Chat/ChatViewModel.swift): `HermesMobile/Features/Chat/ChatViewModel.swift`
- [Message composer](https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Features/Chat/ChatComposerView.swift): `HermesMobile/Features/Chat/ChatComposerView.swift`
- [Stream handling](https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Features/Chat/ChatStreamCoordinator.swift): `HermesMobile/Features/Chat/ChatStreamCoordinator.swift`

### Agent features

- [Scheduled tasks](https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Features/Tasks/TasksView.swift): `HermesMobile/Features/Tasks/TasksView.swift`
- [Skills browser](https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Features/Skills/SkillsView.swift): `HermesMobile/Features/Skills/SkillsView.swift`
- [Memory panel](https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Features/Memory/MemoryView.swift): `HermesMobile/Features/Memory/MemoryView.swift`
- [Usage insights](https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Features/Insights/InsightsView.swift): `HermesMobile/Features/Insights/InsightsView.swift`
- [Bot Mode](https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Features/Bots/BotChatView.swift): `HermesMobile/Features/Bots/BotChatView.swift`

### Workspace tools

- [Workspace browser](https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Features/Workspace/FileBrowserView.swift): `HermesMobile/Features/Workspace/FileBrowserView.swift`
- [Git workspace](https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Features/Workspace/GitWorkspaceView.swift): `HermesMobile/Features/Workspace/GitWorkspaceView.swift`

### Network and state

- [Offline cache](https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Persistence/CacheStore.swift): `HermesMobile/Persistence/CacheStore.swift`
- [Server API](https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Networking/APIClient.swift): `HermesMobile/Networking/APIClient.swift`
- [Chat endpoints](https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Networking/APIClient%2BChat.swift): `HermesMobile/Networking/APIClient+Chat.swift`
- [Session endpoints](https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Networking/APIClient%2BSessions.swift): `HermesMobile/Networking/APIClient+Sessions.swift`
- [Bot connection](https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Networking/Bots/BotClient.swift): `HermesMobile/Networking/Bots/BotClient.swift`
- [Workspace endpoints](https://github.com/uzairansaruzi/hermex/blob/master/HermesMobile/Networking/APIClient%2BWorkspace.swift): `HermesMobile/Networking/APIClient+Workspace.swift`

### Other components

- **iPhone user**
- **Hermes server**

## Connections

- iPhone user → App shell: uses
- App shell → Connection setup: starts setup
- Connection setup → Sign-in: configures access
- iPhone user → Session browser: selects session
- Session browser → Session actions: requests actions
- Session actions → Session endpoints: loads or mutates
- Session endpoints → Server API: sends requests
- Server API → Hermes server: calls
- Session browser → Chat screen: opens conversation
- iPhone user → Message composer: writes message
- Chat screen → Chat orchestration: presents state
- Message composer → Chat orchestration: submits message
- Chat orchestration → Chat endpoints: sends and steers
- Chat endpoints → Server API: sends requests
- Chat orchestration → Stream handling: tracks response
- Stream handling → Chat endpoints: receives events
- Chat orchestration → Offline cache: caches history
- Session browser → Offline cache: reads offline
- iPhone user → Scheduled tasks: manages schedules
- iPhone user → Skills browser: browses skills
- iPhone user → Memory panel: reads memory
- iPhone user → Usage insights: views usage
- iPhone user → Bot Mode: opens Bot Mode
- Bot Mode → Bot connection: connects directly
- Bot connection → Hermes server: connects
- iPhone user → Workspace browser: browses files
- iPhone user → Git workspace: reviews changes
- Workspace browser → Workspace endpoints: requests files
- Git workspace → Server API: uses server API
- iPhone user → Providers and models: chooses providers
- iPhone user → Optional push: taps notification
- iPhone user → Shared content: shares content