# witherwithwinter/deepseek-balance-whale-widget-bowl architecture

> Architecture diagram of the GitHub repository witherwithwinter/deepseek-balance-whale-widget-bowl, 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/witherwithwinter/deepseek-balance-whale-widget-bowl
- Repository: https://github.com/witherwithwinter/deepseek-balance-whale-widget-bowl

## Overview

DSH Whale Widget is a DSH Web plugin that displays account balance and usage in a persistent, customizable whale widget. Users interact with the widget and its menus; the browser requests data and settings from the host-side plugin, which combines balance APIs and session usage into displays, records, alerts, and per-turn notices. The README documents substantial bubble, resource, pricing, and Codex capabilities. The sampled source is partial, so links between those subsystems are shown only where documented or evidenced; implementation details of unsampled features are not inferred.

Main entry points: [`lib/index.js`](https://github.com/witherwithwinter/deepseek-balance-whale-widget-bowl/blob/main/lib/index.js) (Plugin routes), [`assets/whale-widget.js`](https://github.com/witherwithwinter/deepseek-balance-whale-widget-bowl/blob/main/assets/whale-widget.js) (Whale widget), [`assets`](https://github.com/witherwithwinter/deepseek-balance-whale-widget-bowl/tree/main/assets) (Bundled media)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Widget interface"]
  node_widget["Whale widget<br/>[whale-widget.js]"]
  node_menus["Menus and editors<br/>[whale-widget.js]"]
  node_bubble["Bubble renderer<br/>[whale-widget.js]"]
end

subgraph group_accounting["Usage accounting"]
  node_turns["Turn aggregation<br/>[index.js]"]
  node_ledger[("Usage ledger<br/>[index.js]")]
  node_archive[("Usage archive<br/>[index.js]")]
  node_alerts["Usage alerts and quota<br/>[index.js]"]
  node_pricing["Usage pricing<br/>[index.js]"]
end

subgraph group_providers["API and session data"]
  node_api_models["Provider models<br/>[index.js]"]
  node_provider_api["Balance providers"]
  node_codex[("Codex session logs")]
end

subgraph group_resources["Customization and media"]
  node_bubble_config[("Bubble configuration<br/>[index.js]")]
  node_settings[("Widget settings<br/>[index.js]")]
  node_media["Roles and audio<br/>[index.js]"]
  node_assets["Bundled media"]
end

subgraph group_host["DSH runtime"]
  node_browser["DSH Web UI"]
  node_plugin["Plugin routes<br/>[index.js]"]
  node_credentials["DSH credentials"]
  node_session_events["DSH session events"]
end

node_user(("User"))

node_user -->|"interacts"| node_widget
node_widget -->|"requests data"| node_plugin
node_menus -->|"saves settings"| node_plugin
node_widget -->|"renders bubbles"| node_bubble
node_plugin -->|"handles events"| node_turns
node_session_events -->|"dispatches events"| node_turns
node_turns -->|"prices usage"| node_pricing
node_turns -->|"records turns"| node_ledger
node_plugin -->|"reads and writes"| node_ledger
node_plugin -->|"archives history"| node_archive
node_plugin -->|"manages models"| node_api_models
node_api_models -->|"resolves keys"| node_credentials
node_api_models -->|"queries providers"| node_provider_api
node_plugin -.->|"reads local usage"| node_codex
node_plugin -->|"evaluates thresholds"| node_alerts
node_alerts -->|"supplies notices"| node_widget
node_plugin -->|"reads and writes"| node_bubble_config
node_plugin -->|"reads and writes"| node_settings
node_plugin -->|"serves resources"| node_media
node_media -->|"loads presets"| node_assets
node_browser -->|"hosts"| node_widget

click node_widget "https://github.com/witherwithwinter/deepseek-balance-whale-widget-bowl/blob/main/assets/whale-widget.js"
click node_menus "https://github.com/witherwithwinter/deepseek-balance-whale-widget-bowl/blob/main/assets/whale-widget.js"
click node_bubble "https://github.com/witherwithwinter/deepseek-balance-whale-widget-bowl/blob/main/assets/whale-widget.js"
click node_plugin "https://github.com/witherwithwinter/deepseek-balance-whale-widget-bowl/blob/main/lib/index.js"
click node_turns "https://github.com/witherwithwinter/deepseek-balance-whale-widget-bowl/blob/main/lib/index.js"
click node_ledger "https://github.com/witherwithwinter/deepseek-balance-whale-widget-bowl/blob/main/lib/index.js"
click node_archive "https://github.com/witherwithwinter/deepseek-balance-whale-widget-bowl/blob/main/lib/index.js"
click node_api_models "https://github.com/witherwithwinter/deepseek-balance-whale-widget-bowl/blob/main/lib/index.js"
click node_bubble_config "https://github.com/witherwithwinter/deepseek-balance-whale-widget-bowl/blob/main/lib/index.js"
click node_settings "https://github.com/witherwithwinter/deepseek-balance-whale-widget-bowl/blob/main/lib/index.js"
click node_media "https://github.com/witherwithwinter/deepseek-balance-whale-widget-bowl/blob/main/lib/index.js"
click node_assets "https://github.com/witherwithwinter/deepseek-balance-whale-widget-bowl/tree/main/assets"
click node_alerts "https://github.com/witherwithwinter/deepseek-balance-whale-widget-bowl/blob/main/lib/index.js"
click node_pricing "https://github.com/witherwithwinter/deepseek-balance-whale-widget-bowl/blob/main/lib/index.js"

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_menus,node_bubble,node_user toneBlue
class node_turns,node_ledger,node_archive,node_alerts,node_pricing toneAmber
class node_api_models,node_provider_api,node_codex toneMint
class node_bubble_config,node_settings,node_media,node_assets toneRose
class node_browser,node_plugin,node_credentials,node_session_events toneIndigo
```

## Components

### Widget interface

- [Whale widget](https://github.com/witherwithwinter/deepseek-balance-whale-widget-bowl/blob/main/assets/whale-widget.js): `assets/whale-widget.js`
- [Menus and editors](https://github.com/witherwithwinter/deepseek-balance-whale-widget-bowl/blob/main/assets/whale-widget.js): `assets/whale-widget.js`
- [Bubble renderer](https://github.com/witherwithwinter/deepseek-balance-whale-widget-bowl/blob/main/assets/whale-widget.js): `assets/whale-widget.js`

### Usage accounting

- [Turn aggregation](https://github.com/witherwithwinter/deepseek-balance-whale-widget-bowl/blob/main/lib/index.js): `lib/index.js`
- [Usage ledger](https://github.com/witherwithwinter/deepseek-balance-whale-widget-bowl/blob/main/lib/index.js): `lib/index.js`
- [Usage archive](https://github.com/witherwithwinter/deepseek-balance-whale-widget-bowl/blob/main/lib/index.js): `lib/index.js`
- [Usage alerts and quota](https://github.com/witherwithwinter/deepseek-balance-whale-widget-bowl/blob/main/lib/index.js): `lib/index.js`
- [Usage pricing](https://github.com/witherwithwinter/deepseek-balance-whale-widget-bowl/blob/main/lib/index.js): `lib/index.js`

### API and session data

- [Provider models](https://github.com/witherwithwinter/deepseek-balance-whale-widget-bowl/blob/main/lib/index.js): `lib/index.js`
- **Balance providers**
- **Codex session logs**

### Customization and media

- [Bubble configuration](https://github.com/witherwithwinter/deepseek-balance-whale-widget-bowl/blob/main/lib/index.js): `lib/index.js`
- [Widget settings](https://github.com/witherwithwinter/deepseek-balance-whale-widget-bowl/blob/main/lib/index.js): `lib/index.js`
- [Roles and audio](https://github.com/witherwithwinter/deepseek-balance-whale-widget-bowl/blob/main/lib/index.js): `lib/index.js`
- [Bundled media](https://github.com/witherwithwinter/deepseek-balance-whale-widget-bowl/tree/main/assets): `assets`

### DSH runtime

- **DSH Web UI**
- [Plugin routes](https://github.com/witherwithwinter/deepseek-balance-whale-widget-bowl/blob/main/lib/index.js): `lib/index.js`
- **DSH credentials**
- **DSH session events**

### Other components

- **User**

## Connections

- User → Whale widget: interacts
- Whale widget → Plugin routes: requests data
- Menus and editors → Plugin routes: saves settings
- Whale widget → Bubble renderer: renders bubbles
- Plugin routes → Turn aggregation: handles events
- DSH session events → Turn aggregation: dispatches events
- Turn aggregation → Usage pricing: prices usage
- Turn aggregation → Usage ledger: records turns
- Plugin routes → Usage ledger: reads and writes
- Plugin routes → Usage archive: archives history
- Plugin routes → Provider models: manages models
- Provider models → DSH credentials: resolves keys
- Provider models → Balance providers: queries providers
- Plugin routes → Codex session logs: reads local usage
- Plugin routes → Usage alerts and quota: evaluates thresholds
- Usage alerts and quota → Whale widget: supplies notices
- Plugin routes → Bubble configuration: reads and writes
- Plugin routes → Widget settings: reads and writes
- Plugin routes → Roles and audio: serves resources
- Roles and audio → Bundled media: loads presets
- DSH Web UI → Whale widget: hosts