# soundpulse/hermes-live2d architecture

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

- Interactive diagram: https://gitdiagram.com/soundpulse/hermes-live2d
- Repository: https://github.com/soundpulse/hermes-live2d

## Overview

ATRI Live2D is a Tauri desktop pet that renders a Live2D character and accepts local HTTP commands. Its principal workflow is an agent’s generated recording sent by the bundled Hermes skill to the API, which stores inline audio if needed and emits events for the frontend to play with lip sync, expression, and speech bubble. Other documented capabilities include direct expression/motion/bubble controls, model loading, mouse tracking, and tray/window behavior. The README documents these subsystems; sampled source excerpts do not show every handler or frontend event listener.

Main entry points: [`src/main.ts`](https://github.com/soundpulse/hermes-live2d/blob/main/src/main.ts) (Live2D frontend), [`src-tauri/src/api.rs`](https://github.com/soundpulse/hermes-live2d/blob/main/src-tauri/src/api.rs) (Local HTTP API), [`src-tauri/src/lib.rs`](https://github.com/soundpulse/hermes-live2d/blob/main/src-tauri/src/lib.rs) (Tauri runtime), [`skills/hermes-live2d-voice`](https://github.com/soundpulse/hermes-live2d/tree/main/skills/hermes-live2d-voice) (Voice skill)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Agent integration"]
  node_skill["Voice skill"]
  node_tailscale["Tailscale access"]
end

subgraph group_http["HTTP API"]
  node_api["Local HTTP API<br/>[api.rs]"]
  node_audiofiles[("Uploaded audio")]
end

subgraph group_pet["Desktop pet"]
  node_frontend["Live2D frontend<br/>[main.ts]"]
  node_model["Live2D model"]
  node_audio["Audio playback<br/>[main.ts]"]
  node_bubble["Speech bubbles<br/>[main.ts]"]
  node_expressions["Expressions and motions<br/>[main.ts]"]
  node_tracking["Mouse tracking<br/>[main.ts]"]
end

subgraph group_platform["Desktop platform"]
  node_config[("App configuration<br/>[config.rs]")]
  node_runtime["Tauri runtime<br/>[lib.rs]"]
  node_window["Window and tray<br/>[lib.rs]"]
end

node_agent(("Hermes agent"))

node_agent -->|"uses"| node_skill
node_skill -->|"posts speech"| node_api
node_tailscale -.->|"forwards requests"| node_api
node_runtime -->|"loads and saves"| node_config
node_runtime -->|"starts server"| node_api
node_api -->|"writes uploads"| node_audiofiles
node_api -->|"emits commands"| node_frontend
node_frontend -->|"fetches audio"| node_api
node_frontend -->|"fetches model"| node_api
node_frontend -->|"loads model"| node_model
node_frontend -->|"plays audio"| node_audio
node_frontend -->|"shows text"| node_bubble
node_frontend -->|"sets expression or motion"| node_expressions
node_frontend -->|"updates focus"| node_tracking
node_frontend -->|"invokes window commands"| node_runtime
node_runtime -->|"manages tray and window"| node_window
node_window -->|"persists geometry"| node_config

click node_skill "https://github.com/soundpulse/hermes-live2d/tree/main/skills/hermes-live2d-voice"
click node_api "https://github.com/soundpulse/hermes-live2d/blob/main/src-tauri/src/api.rs"
click node_config "https://github.com/soundpulse/hermes-live2d/blob/main/src-tauri/src/config.rs"
click node_runtime "https://github.com/soundpulse/hermes-live2d/blob/main/src-tauri/src/lib.rs"
click node_frontend "https://github.com/soundpulse/hermes-live2d/blob/main/src/main.ts"
click node_audio "https://github.com/soundpulse/hermes-live2d/blob/main/src/main.ts"
click node_bubble "https://github.com/soundpulse/hermes-live2d/blob/main/src/main.ts"
click node_expressions "https://github.com/soundpulse/hermes-live2d/blob/main/src/main.ts"
click node_tracking "https://github.com/soundpulse/hermes-live2d/blob/main/src/main.ts"
click node_window "https://github.com/soundpulse/hermes-live2d/blob/main/src-tauri/src/lib.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_skill,node_tailscale toneBlue
class node_api,node_audiofiles toneAmber
class node_frontend,node_model,node_audio,node_bubble,node_expressions,node_tracking toneMint
class node_config,node_runtime,node_window toneRose
class node_agent toneIndigo
```

## Components

### Agent integration

- [Voice skill](https://github.com/soundpulse/hermes-live2d/tree/main/skills/hermes-live2d-voice): `skills/hermes-live2d-voice`
- **Tailscale access**

### HTTP API

- [Local HTTP API](https://github.com/soundpulse/hermes-live2d/blob/main/src-tauri/src/api.rs): `src-tauri/src/api.rs`
- **Uploaded audio**

### Desktop pet

- [Live2D frontend](https://github.com/soundpulse/hermes-live2d/blob/main/src/main.ts): `src/main.ts`
- **Live2D model**
- [Audio playback](https://github.com/soundpulse/hermes-live2d/blob/main/src/main.ts): `src/main.ts`
- [Speech bubbles](https://github.com/soundpulse/hermes-live2d/blob/main/src/main.ts): `src/main.ts`
- [Expressions and motions](https://github.com/soundpulse/hermes-live2d/blob/main/src/main.ts): `src/main.ts`
- [Mouse tracking](https://github.com/soundpulse/hermes-live2d/blob/main/src/main.ts): `src/main.ts`

### Desktop platform

- [App configuration](https://github.com/soundpulse/hermes-live2d/blob/main/src-tauri/src/config.rs): `src-tauri/src/config.rs`
- [Tauri runtime](https://github.com/soundpulse/hermes-live2d/blob/main/src-tauri/src/lib.rs): `src-tauri/src/lib.rs`
- [Window and tray](https://github.com/soundpulse/hermes-live2d/blob/main/src-tauri/src/lib.rs): `src-tauri/src/lib.rs`

### Other components

- **Hermes agent**

## Connections

- Hermes agent → Voice skill: uses
- Voice skill → Local HTTP API: posts speech
- Tailscale access → Local HTTP API: forwards requests
- Tauri runtime → App configuration: loads and saves
- Tauri runtime → Local HTTP API: starts server
- Local HTTP API → Uploaded audio: writes uploads
- Local HTTP API → Live2D frontend: emits commands
- Live2D frontend → Local HTTP API: fetches audio
- Live2D frontend → Local HTTP API: fetches model
- Live2D frontend → Live2D model: loads model
- Live2D frontend → Audio playback: plays audio
- Live2D frontend → Speech bubbles: shows text
- Live2D frontend → Expressions and motions: sets expression or motion
- Live2D frontend → Mouse tracking: updates focus
- Live2D frontend → Tauri runtime: invokes window commands
- Tauri runtime → Window and tray: manages tray and window
- Window and tray → App configuration: persists geometry