# yyhssr/desktop-pet architecture

> Architecture diagram of the GitHub repository yyhssr/desktop-pet, 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/yyhssr/desktop-pet
- Repository: https://github.com/yyhssr/desktop-pet

## Overview

Desktop-Pet is a Windows desktop companion built with PySide6, transparent WebM animation, and interactive physics. The primary workflow starts with the user launching or interacting with the pet: the app creates the pet window, which renders a selected character and handles gestures, menus, and settings; dragging can feed motion into collision simulation and produce a bounce. The repository also contains optional chat, music-lyrics, reminders, and DSH agent-link features. The graph follows README-described capabilities and the sampled call sites; some subsystem wiring is therefore left out where source was not sampled.

Main entry points: [`pet/app.py`](https://github.com/yyhssr/desktop-pet/blob/main/pet/app.py) (App Shell), [`pet/window.py`](https://github.com/yyhssr/desktop-pet/blob/main/pet/window.py) (Pet Window), [`pet/chat/widgets.py`](https://github.com/yyhssr/desktop-pet/blob/main/pet/chat/widgets.py) (Chat UI), [`pet/music_lyric_controller.py`](https://github.com/yyhssr/desktop-pet/blob/main/pet/music_lyric_controller.py) (Music Lyrics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["App Runtime"]
  node_app["App Shell<br/>[app.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_catalog["Character Catalog<br/>[catalog.py]"]
end

subgraph group_interaction["Pet Interaction"]
  node_window["Pet Window<br/>[window.py]"]
  node_animation["WebM Animation<br/>[webm_clip.py]"]
  node_framecache["Frame Cache<br/>[frame_cache.py]"]
  node_menus["Context Menus<br/>[modern.py]"]
  node_settings["Settings Panel"]
end

subgraph group_physics["Motion Physics"]
  node_movement["Movement<br/>[movement.py]"]
  node_collisionclient["Collision Client"]
  node_collisionipc["Collision IPC<br/>[collision_ipc.py]"]
  node_native["Native Loader<br/>[loader.py]"]
  node_nativecore["C++ Collision Core<br/>[collision.cpp]"]
end

subgraph group_features["Optional Features"]
  node_chatui["Chat UI<br/>[widgets.py]"]
  node_chatservice["Chat Service<br/>[service.py]"]
  node_sessions[("Chat Sessions<br/>[session_store.py]")]
  node_lyrics["Music Lyrics"]
  node_voice["Voice Chimes"]
  node_festival["Festival Reminders"]
  node_agentlink["DSH Agent Link<br/>[agent_link.py]"]
  node_agentprotocol["Agent Event Protocol"]
end

subgraph group_integrations["External Integrations"]
  node_chatprovider["Chat Provider<br/>[providers.py]"]
  node_musicplayers["Music Players<br/>[music_players.py]"]
  node_lyricfetch["Lyric Fetch<br/>[music_lyric.py]"]
  node_bridge["DSH Bridge<br/>[index.js]"]
  node_sharedfiles[("Shared Event Files")]
  node_llm(("Chat API"))
  node_desktopmedia(("Desktop Media"))
end

node_user(("User"))

node_user -->|"launches"| node_app
node_app -->|"loads settings"| node_config
node_app -->|"selects character"| node_catalog
node_app -->|"creates window"| node_window
node_window -->|"plays clips"| node_animation
node_animation -->|"uses cache"| node_framecache
node_user -->|"gestures"| node_window
node_window -->|"opens menu"| node_menus
node_menus -->|"opens settings"| node_settings
node_window -->|"updates motion"| node_movement
node_movement -->|"submits motion"| node_collisionclient
node_collisionclient -->|"exchanges state"| node_collisionipc
node_collisionipc -->|"dispatches solve"| node_native
node_native -->|"calls ABI"| node_nativecore
node_app -.->|"hosts optional chat"| node_chatui
node_chatui -->|"sends messages"| node_chatservice
node_chatservice -->|"streams response"| node_chatprovider
node_chatprovider -.->|"requests completion"| node_llm
node_chatui -->|"stores conversations"| node_sessions
node_app -.->|"installs optional controller"| node_lyrics
node_lyrics -->|"samples playback"| node_musicplayers
node_lyrics -->|"fetches lyrics"| node_lyricfetch
node_musicplayers -.->|"reads playback"| node_desktopmedia
node_app -.->|"starts optional service"| node_voice
node_app -.->|"starts optional service"| node_festival
node_app -.->|"starts when enabled"| node_agentlink
node_agentlink -->|"normalizes events"| node_agentprotocol
node_bridge -->|"appends events"| node_sharedfiles
node_agentlink -->|"tails events"| node_sharedfiles

click node_app "https://github.com/yyhssr/desktop-pet/blob/main/pet/app.py"
click node_config "https://github.com/yyhssr/desktop-pet/blob/main/pet/config.py"
click node_catalog "https://github.com/yyhssr/desktop-pet/blob/main/pet/catalog.py"
click node_window "https://github.com/yyhssr/desktop-pet/blob/main/pet/window.py"
click node_animation "https://github.com/yyhssr/desktop-pet/blob/main/pet/webm_clip.py"
click node_framecache "https://github.com/yyhssr/desktop-pet/blob/main/pet/frame_cache.py"
click node_menus "https://github.com/yyhssr/desktop-pet/blob/main/pet/context_menus/modern.py"
click node_settings "https://github.com/yyhssr/desktop-pet/blob/main/pet/modern_settings_dialog.py"
click node_movement "https://github.com/yyhssr/desktop-pet/blob/main/pet/movement.py"
click node_collisionclient "https://github.com/yyhssr/desktop-pet/blob/main/pet/collision_client.py"
click node_collisionipc "https://github.com/yyhssr/desktop-pet/blob/main/pet/collision_ipc.py"
click node_native "https://github.com/yyhssr/desktop-pet/blob/main/pet/native/loader.py"
click node_nativecore "https://github.com/yyhssr/desktop-pet/blob/main/C%2B%2B-Python/src/collision.cpp"
click node_chatui "https://github.com/yyhssr/desktop-pet/blob/main/pet/chat/widgets.py"
click node_chatservice "https://github.com/yyhssr/desktop-pet/blob/main/pet/chat/service.py"
click node_chatprovider "https://github.com/yyhssr/desktop-pet/blob/main/pet/chat/providers.py"
click node_sessions "https://github.com/yyhssr/desktop-pet/blob/main/pet/chat/session_store.py"
click node_lyrics "https://github.com/yyhssr/desktop-pet/blob/main/pet/music_lyric_controller.py"
click node_musicplayers "https://github.com/yyhssr/desktop-pet/blob/main/pet/music_players.py"
click node_lyricfetch "https://github.com/yyhssr/desktop-pet/blob/main/pet/music_lyric.py"
click node_voice "https://github.com/yyhssr/desktop-pet/blob/main/pet/voice_chime_service.py"
click node_festival "https://github.com/yyhssr/desktop-pet/blob/main/pet/festival_service.py"
click node_agentlink "https://github.com/yyhssr/desktop-pet/blob/main/pet/agent_link.py"
click node_bridge "https://github.com/yyhssr/desktop-pet/blob/main/integrations/dsh-pet-bridge/index.js"
click node_agentprotocol "https://github.com/yyhssr/desktop-pet/blob/main/pet/agent_event_protocol.py"

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_config,node_catalog,node_user toneBlue
class node_window,node_animation,node_framecache,node_menus,node_settings toneAmber
class node_movement,node_collisionclient,node_collisionipc,node_native,node_nativecore toneMint
class node_chatui,node_chatservice,node_sessions,node_lyrics,node_voice,node_festival,node_agentlink,node_agentprotocol toneRose
class node_chatprovider,node_musicplayers,node_lyricfetch,node_bridge,node_sharedfiles,node_llm,node_desktopmedia toneIndigo
```

## Components

### App Runtime

- [App Shell](https://github.com/yyhssr/desktop-pet/blob/main/pet/app.py): `pet/app.py`
- [Configuration](https://github.com/yyhssr/desktop-pet/blob/main/pet/config.py): `pet/config.py`
- [Character Catalog](https://github.com/yyhssr/desktop-pet/blob/main/pet/catalog.py): `pet/catalog.py`

### Pet Interaction

- [Pet Window](https://github.com/yyhssr/desktop-pet/blob/main/pet/window.py): `pet/window.py`
- [WebM Animation](https://github.com/yyhssr/desktop-pet/blob/main/pet/webm_clip.py): `pet/webm_clip.py`
- [Frame Cache](https://github.com/yyhssr/desktop-pet/blob/main/pet/frame_cache.py): `pet/frame_cache.py`
- [Context Menus](https://github.com/yyhssr/desktop-pet/blob/main/pet/context_menus/modern.py): `pet/context_menus/modern.py`
- [Settings Panel](https://github.com/yyhssr/desktop-pet/blob/main/pet/modern_settings_dialog.py): `pet/modern_settings_dialog.py`

### Motion Physics

- [Movement](https://github.com/yyhssr/desktop-pet/blob/main/pet/movement.py): `pet/movement.py`
- [Collision Client](https://github.com/yyhssr/desktop-pet/blob/main/pet/collision_client.py): `pet/collision_client.py`
- [Collision IPC](https://github.com/yyhssr/desktop-pet/blob/main/pet/collision_ipc.py): `pet/collision_ipc.py`
- [Native Loader](https://github.com/yyhssr/desktop-pet/blob/main/pet/native/loader.py): `pet/native/loader.py`
- [C++ Collision Core](https://github.com/yyhssr/desktop-pet/blob/main/C%2B%2B-Python/src/collision.cpp): `C++-Python/src/collision.cpp`

### Optional Features

- [Chat UI](https://github.com/yyhssr/desktop-pet/blob/main/pet/chat/widgets.py): `pet/chat/widgets.py`
- [Chat Service](https://github.com/yyhssr/desktop-pet/blob/main/pet/chat/service.py): `pet/chat/service.py`
- [Chat Sessions](https://github.com/yyhssr/desktop-pet/blob/main/pet/chat/session_store.py): `pet/chat/session_store.py`
- [Music Lyrics](https://github.com/yyhssr/desktop-pet/blob/main/pet/music_lyric_controller.py): `pet/music_lyric_controller.py`
- [Voice Chimes](https://github.com/yyhssr/desktop-pet/blob/main/pet/voice_chime_service.py): `pet/voice_chime_service.py`
- [Festival Reminders](https://github.com/yyhssr/desktop-pet/blob/main/pet/festival_service.py): `pet/festival_service.py`
- [DSH Agent Link](https://github.com/yyhssr/desktop-pet/blob/main/pet/agent_link.py): `pet/agent_link.py`
- [Agent Event Protocol](https://github.com/yyhssr/desktop-pet/blob/main/pet/agent_event_protocol.py): `pet/agent_event_protocol.py`

### External Integrations

- [Chat Provider](https://github.com/yyhssr/desktop-pet/blob/main/pet/chat/providers.py): `pet/chat/providers.py`
- [Music Players](https://github.com/yyhssr/desktop-pet/blob/main/pet/music_players.py): `pet/music_players.py`
- [Lyric Fetch](https://github.com/yyhssr/desktop-pet/blob/main/pet/music_lyric.py): `pet/music_lyric.py`
- [DSH Bridge](https://github.com/yyhssr/desktop-pet/blob/main/integrations/dsh-pet-bridge/index.js): `integrations/dsh-pet-bridge/index.js`
- **Shared Event Files**
- **Chat API**
- **Desktop Media**

### Other components

- **User**

## Connections

- User → App Shell: launches
- App Shell → Configuration: loads settings
- App Shell → Character Catalog: selects character
- App Shell → Pet Window: creates window
- Pet Window → WebM Animation: plays clips
- WebM Animation → Frame Cache: uses cache
- User → Pet Window: gestures
- Pet Window → Context Menus: opens menu
- Context Menus → Settings Panel: opens settings
- Pet Window → Movement: updates motion
- Movement → Collision Client: submits motion
- Collision Client → Collision IPC: exchanges state
- Collision IPC → Native Loader: dispatches solve
- Native Loader → C++ Collision Core: calls ABI
- App Shell → Chat UI: hosts optional chat
- Chat UI → Chat Service: sends messages
- Chat Service → Chat Provider: streams response
- Chat Provider → Chat API: requests completion
- Chat UI → Chat Sessions: stores conversations
- App Shell → Music Lyrics: installs optional controller
- Music Lyrics → Music Players: samples playback
- Music Lyrics → Lyric Fetch: fetches lyrics
- Music Players → Desktop Media: reads playback
- App Shell → Voice Chimes: starts optional service
- App Shell → Festival Reminders: starts optional service
- App Shell → DSH Agent Link: starts when enabled
- DSH Agent Link → Agent Event Protocol: normalizes events
- DSH Bridge → Shared Event Files: appends events
- DSH Agent Link → Shared Event Files: tails events