# qingcheng3962/dsh-balance-desk-pet architecture

> Architecture diagram of the GitHub repository qingcheng3962/dsh-balance-desk-pet, 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/qingcheng3962/dsh-balance-desk-pet
- Repository: https://github.com/qingcheng3962/dsh-balance-desk-pet

## Overview

This tree is a Python Windows desktop companion for DSH, rather than the README’s primary DSH Web plugin. Its central workflow is to launch the whale widget, read shared DSH settings and usage data, query DeepSeek balance, and present results through the widget and its bubbles. The README also describes customizable bubble content and desktop interaction. Several modules are indexed as imports, but their call sites are not shown in the excerpts, so those links are omitted or marked unverified; the broader Web-plugin capabilities are not mapped as Python components.

Main entry points: [`python/dsh_whale_pet.py`](https://github.com/qingcheng3962/dsh-balance-desk-pet/blob/main/python/dsh_whale_pet.py) (Whale widget), [`python/whale_data.py`](https://github.com/qingcheng3962/dsh-balance-desk-pet/blob/main/python/whale_data.py) (DSH data access), [`python/whale_bubble.py`](https://github.com/qingcheng3962/dsh-balance-desk-pet/blob/main/python/whale_bubble.py) (Bubble graphics), [`python/whale_card.py`](https://github.com/qingcheng3962/dsh-balance-desk-pet/blob/main/python/whale_card.py) (Card renderer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Widget runtime"]
  node_widget["Whale widget<br/>[dsh_whale_pet.py]"]
end

subgraph group_accounting["Balance and data"]
  node_data["DSH data access<br/>[whale_data.py]"]
  node_sharedfiles["Shared DSH files"]
  node_deepseek["DeepSeek API"]
end

subgraph group_bubbles["Bubble presentation"]
  node_editor["Bubble editor<br/>[whale_editor.py]"]
  node_card["Card renderer<br/>[whale_card.py]"]
  node_bubble["Bubble graphics<br/>[whale_bubble.py]"]
  node_svg["SVG balloon renderer<br/>[whale_svg.py]"]
end

subgraph group_media["Audio and styling"]
  node_audio["Audio playback<br/>[whale_audio.py]"]
  node_presets["Bubble presets<br/>[whale_presets.py]"]
  node_colors["Color schemes<br/>[whale_colors.py]"]
end

node_user(("Desktop user"))

node_user -->|"uses"| node_widget
node_widget -->|"reads settings"| node_data
node_widget -->|"reads state"| node_data
node_widget -->|"initializes"| node_audio
node_data -->|"reads and writes"| node_sharedfiles
node_data -->|"queries balance"| node_deepseek
node_widget -.->|"opens editor"| node_editor
node_editor -.->|"saves configuration"| node_data
node_widget -.->|"renders reminders"| node_card
node_widget -.->|"renders bubbles"| node_bubble
node_card -.->|"uses styles"| node_presets
node_card -.->|"uses colors"| node_colors
node_bubble -.->|"uses balloon"| node_svg
node_bubble -.->|"uses styles"| node_presets
node_bubble -.->|"uses colors"| node_colors

click node_widget "https://github.com/qingcheng3962/dsh-balance-desk-pet/blob/main/python/dsh_whale_pet.py"
click node_editor "https://github.com/qingcheng3962/dsh-balance-desk-pet/blob/main/python/whale_editor.py"
click node_data "https://github.com/qingcheng3962/dsh-balance-desk-pet/blob/main/python/whale_data.py"
click node_audio "https://github.com/qingcheng3962/dsh-balance-desk-pet/blob/main/python/whale_audio.py"
click node_card "https://github.com/qingcheng3962/dsh-balance-desk-pet/blob/main/python/whale_card.py"
click node_bubble "https://github.com/qingcheng3962/dsh-balance-desk-pet/blob/main/python/whale_bubble.py"
click node_svg "https://github.com/qingcheng3962/dsh-balance-desk-pet/blob/main/python/whale_svg.py"
click node_presets "https://github.com/qingcheng3962/dsh-balance-desk-pet/blob/main/python/whale_presets.py"
click node_colors "https://github.com/qingcheng3962/dsh-balance-desk-pet/blob/main/python/whale_colors.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_widget,node_user toneBlue
class node_data,node_sharedfiles,node_deepseek toneAmber
class node_editor,node_card,node_bubble,node_svg toneMint
class node_audio,node_presets,node_colors toneRose
```

## Components

### Widget runtime

- [Whale widget](https://github.com/qingcheng3962/dsh-balance-desk-pet/blob/main/python/dsh_whale_pet.py): `python/dsh_whale_pet.py`

### Balance and data

- [DSH data access](https://github.com/qingcheng3962/dsh-balance-desk-pet/blob/main/python/whale_data.py): `python/whale_data.py`
- **Shared DSH files**
- **DeepSeek API**

### Bubble presentation

- [Bubble editor](https://github.com/qingcheng3962/dsh-balance-desk-pet/blob/main/python/whale_editor.py): `python/whale_editor.py`
- [Card renderer](https://github.com/qingcheng3962/dsh-balance-desk-pet/blob/main/python/whale_card.py): `python/whale_card.py`
- [Bubble graphics](https://github.com/qingcheng3962/dsh-balance-desk-pet/blob/main/python/whale_bubble.py): `python/whale_bubble.py`
- [SVG balloon renderer](https://github.com/qingcheng3962/dsh-balance-desk-pet/blob/main/python/whale_svg.py): `python/whale_svg.py`

### Audio and styling

- [Audio playback](https://github.com/qingcheng3962/dsh-balance-desk-pet/blob/main/python/whale_audio.py): `python/whale_audio.py`
- [Bubble presets](https://github.com/qingcheng3962/dsh-balance-desk-pet/blob/main/python/whale_presets.py): `python/whale_presets.py`
- [Color schemes](https://github.com/qingcheng3962/dsh-balance-desk-pet/blob/main/python/whale_colors.py): `python/whale_colors.py`

### Other components

- **Desktop user**

## Connections

- Desktop user → Whale widget: uses (evidence: `python/dsh_whale_pet.py`)
- Whale widget → DSH data access: reads settings (evidence: `python/dsh_whale_pet.py`)
- Whale widget → DSH data access: reads state (evidence: `python/dsh_whale_pet.py`)
- Whale widget → Audio playback: initializes (evidence: `python/dsh_whale_pet.py`)
- DSH data access → Shared DSH files: reads and writes (evidence: `python/whale_data.py`)
- DSH data access → DeepSeek API: queries balance (evidence: `python/whale_data.py`)
- Whale widget → Bubble editor: opens editor (evidence: `python/dsh_whale_pet.py`)
- Bubble editor → DSH data access: saves configuration (evidence: `python/whale_editor.py`)
- Whale widget → Card renderer: renders reminders (evidence: `python/dsh_whale_pet.py`)
- Whale widget → Bubble graphics: renders bubbles (evidence: `python/dsh_whale_pet.py`)
- Card renderer → Bubble presets: uses styles (evidence: `python/whale_card.py`)
- Card renderer → Color schemes: uses colors (evidence: `python/whale_card.py`)
- Bubble graphics → SVG balloon renderer: uses balloon (evidence: `python/whale_bubble.py`)
- Bubble graphics → Bubble presets: uses styles (evidence: `python/whale_bubble.py`)
- Bubble graphics → Color schemes: uses colors (evidence: `python/whale_bubble.py`)
