# murtaza0053/desk-charms architecture

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

- Interactive diagram: https://gitdiagram.com/murtaza0053/desk-charms
- Repository: https://github.com/murtaza0053/desk-charms

## Overview

Desk Charms is a GNOME desktop charm overlay. Its main workflow loads preferences and a selected charm, builds one or more interactive hanging windows, simulates sway and drag physics, draws the charm, and plays effects. Settings persistence/UI, charm definitions and sprite rendering are distinct supporting stages. The excerpts establish the main calls among core modules; assets and some window/rendering internals are described by the README, so uncertain connections are omitted.

Main entry points: [`desk_charms.py`](https://github.com/murtaza0053/desk-charms/blob/main/desk_charms.py) (Application runtime), [`sounds.py`](https://github.com/murtaza0053/desk-charms/blob/main/sounds.py) (Sound synthesis and playback), [`objects.py`](https://github.com/murtaza0053/desk-charms/blob/main/objects.py) (Charm definitions), [`settings.py`](https://github.com/murtaza0053/desk-charms/blob/main/settings.py) (Settings UI and store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Overlay Runtime"]
  node_app["Application runtime<br/>[desk_charms.py]"]
  node_dangle["Interactive dangle<br/>[desk_charms.py]"]
end

subgraph group_charm["Charm Modeling"]
  node_kinds["Charm definitions<br/>[objects.py]"]
  node_cutout["Photo cutout tool<br/>[cutout.py]"]
end

subgraph group_preferences["Settings"]
  node_settings["Settings UI and store<br/>[settings.py]"]
  node_prefsfile["Saved preferences"]
end

subgraph group_media["Visuals and Sound"]
  node_sprites["Sprite rendering<br/>[sprites.py]"]
  node_assets["Charm photos"]
  node_sounds["Sound synthesis and playback<br/>[sounds.py]"]
  node_soundcache[("Cached WAV effects")]
end

node_user(("Desktop user"))
node_gtk["GNOME desktop"]
node_paplay["paplay audio service"]

node_user -->|"starts or configures"| node_app
node_app -->|"loads and opens"| node_settings
node_settings -->|"reads and writes"| node_prefsfile
node_settings -->|"lists charm choices"| node_kinds
node_app -->|"selects charm"| node_kinds
node_app -->|"builds windows"| node_dangle
node_dangle -.->|"shows overlay"| node_gtk
node_dangle -->|"updates and lays out"| node_kinds
node_dangle -->|"plays effects"| node_sounds
node_app -->|"prepares effects"| node_sounds
node_kinds -->|"creates sprites"| node_sprites
node_sprites -.->|"loads photos"| node_assets
node_sounds -->|"writes and reads WAV"| node_soundcache
node_sounds -->|"plays audio"| node_paplay
node_cutout -->|"creates cutouts"| node_assets

click node_app "https://github.com/murtaza0053/desk-charms/blob/main/desk_charms.py"
click node_dangle "https://github.com/murtaza0053/desk-charms/blob/main/desk_charms.py"
click node_settings "https://github.com/murtaza0053/desk-charms/blob/main/settings.py"
click node_kinds "https://github.com/murtaza0053/desk-charms/blob/main/objects.py"
click node_sprites "https://github.com/murtaza0053/desk-charms/blob/main/sprites.py"
click node_assets "https://github.com/murtaza0053/desk-charms/tree/main/assets"
click node_sounds "https://github.com/murtaza0053/desk-charms/blob/main/sounds.py"
click node_cutout "https://github.com/murtaza0053/desk-charms/blob/main/tools/cutout.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_dangle,node_user toneBlue
class node_kinds,node_cutout toneAmber
class node_settings,node_prefsfile toneMint
class node_sprites,node_assets,node_sounds,node_soundcache toneRose
class node_gtk,node_paplay toneIndigo
```

## Components

### Overlay Runtime

- [Application runtime](https://github.com/murtaza0053/desk-charms/blob/main/desk_charms.py): `desk_charms.py`
- [Interactive dangle](https://github.com/murtaza0053/desk-charms/blob/main/desk_charms.py): `desk_charms.py`

### Charm Modeling

- [Charm definitions](https://github.com/murtaza0053/desk-charms/blob/main/objects.py): `objects.py`
- [Photo cutout tool](https://github.com/murtaza0053/desk-charms/blob/main/tools/cutout.py): `tools/cutout.py`

### Settings

- [Settings UI and store](https://github.com/murtaza0053/desk-charms/blob/main/settings.py): `settings.py`
- **Saved preferences**

### Visuals and Sound

- [Sprite rendering](https://github.com/murtaza0053/desk-charms/blob/main/sprites.py): `sprites.py`
- [Charm photos](https://github.com/murtaza0053/desk-charms/tree/main/assets): `assets`
- [Sound synthesis and playback](https://github.com/murtaza0053/desk-charms/blob/main/sounds.py): `sounds.py`
- **Cached WAV effects**

### Other components

- **Desktop user**
- **GNOME desktop**
- **paplay audio service**

## Connections

- Desktop user → Application runtime: starts or configures (evidence: `README.md`)
- Application runtime → Settings UI and store: loads and opens (evidence: `desk_charms.py`)
- Settings UI and store → Saved preferences: reads and writes (evidence: `settings.py`)
- Settings UI and store → Charm definitions: lists charm choices (evidence: `settings.py`)
- Application runtime → Charm definitions: selects charm (evidence: `desk_charms.py`)
- Application runtime → Interactive dangle: builds windows (evidence: `desk_charms.py`)
- Interactive dangle → GNOME desktop: shows overlay
- Interactive dangle → Charm definitions: updates and lays out (evidence: `desk_charms.py`)
- Interactive dangle → Sound synthesis and playback: plays effects (evidence: `desk_charms.py`)
- Application runtime → Sound synthesis and playback: prepares effects (evidence: `desk_charms.py`)
- Charm definitions → Sprite rendering: creates sprites (evidence: `objects.py`)
- Sprite rendering → Charm photos: loads photos
- Sound synthesis and playback → Cached WAV effects: writes and reads WAV (evidence: `sounds.py`)
- Sound synthesis and playback → paplay audio service: plays audio (evidence: `sounds.py`)
- Photo cutout tool → Charm photos: creates cutouts (evidence: `README.md`)