# hstagg/critter-overlay architecture

> Architecture diagram of the GitHub repository hstagg/critter-overlay, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hstagg/critter-overlay
- Repository: https://github.com/hstagg/critter-overlay

## Overview

Critter Overlay is a desktop pet simulation: the user launches the tray app, which starts a transparent overlay; timed or user-requested spawns create moving critters that react, render, and play sounds. Settings configure the simulation and custom critters can be imported, stored, shared, and loaded into the spawn pool. Edges reflect the shown imports/calls or README-documented behavior; some subsystem internals were not sampled, so uncertain links are omitted.

Main entry points: [`src/main.py`](https://github.com/hstagg/critter-overlay/blob/main/src/main.py) (App and tray), [`src/spawn_manager.py`](https://github.com/hstagg/critter-overlay/blob/main/src/spawn_manager.py) (Spawn manager), [`src/settings_window.py`](https://github.com/hstagg/critter-overlay/blob/main/src/settings_window.py) (Settings UI), [`src/overlay.py`](https://github.com/hstagg/critter-overlay/blob/main/src/overlay.py) (Desktop overlay)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["App runtime"]
  node_main["App and tray<br/>[main.py]"]
  node_overlay["Desktop overlay<br/>[overlay.py]"]
  node_events["Event dispatch<br/>[events.py]"]
  node_sounds["Sound manager<br/>[sounds.py]"]
  node_updater["App updater<br/>[updater.py]"]
end

subgraph group_world["Critter simulation"]
  node_spawn["Spawn manager<br/>[spawn_manager.py]"]
  node_animals["Built-in animals<br/>[animals.py]"]
  node_behaviour["Behaviours<br/>[behaviours.py]"]
  node_locomotion["Locomotion profiles<br/>[locomotion.py]"]
  node_daynight["Day-night activity<br/>[time_of_day.py]"]
  node_rarity["Rarity tiers<br/>[rarity.py]"]
  node_auras["Rarity auras<br/>[auras.py]"]
end

subgraph group_custom["Custom critters"]
  node_custom_animal["Custom animal<br/>[animals_custom.py]"]
  node_import["Import pipeline<br/>[import_pipeline.py]"]
  node_sharing["Package sharing<br/>[sharing.py]"]
  node_registry["Critter registry<br/>[registry.py]"]
  node_bg["Background removal<br/>[bg_removal.py]"]
  node_masks["Mask generation<br/>[masks.py]"]
  node_palette["Palette extraction<br/>[palette.py]"]
  node_procedural["Walk-cycle generation<br/>[procedural.py]"]
end

subgraph group_control["Controls and settings"]
  node_settings["Settings UI<br/>[settings_window.py]"]
  node_previews["Animal previews<br/>[animal_previews.py]"]
  node_preview_render["Preview renderer"]
end

subgraph group_state["Persistent state"]
  node_config["Configuration<br/>[config.py]"]
  node_custom_store[("Critter files<br/>[storage.py]")]
end

node_user(("User"))

node_user -->|"launches"| node_main
node_main -->|"loads"| node_config
node_main -->|"starts"| node_overlay
node_main -->|"opens"| node_settings
node_main -->|"dispatches"| node_events
node_main -->|"loads"| node_registry
node_main -->|"initializes"| node_sounds
node_main -->|"uses"| node_updater
node_overlay -->|"requests spawns"| node_spawn
node_overlay -->|"renders and updates"| node_animals
node_overlay -->|"renders"| node_auras
node_overlay -->|"plays"| node_sounds
node_overlay -->|"reads"| node_config
node_overlay -->|"handles"| node_events
node_spawn -->|"creates"| node_animals
node_spawn -->|"creates"| node_custom_animal
node_spawn -->|"queries"| node_registry
node_spawn -->|"rolls tiers"| node_rarity
node_spawn -->|"triggers"| node_behaviour
node_spawn -->|"scales activity"| node_daynight
node_spawn -->|"reads settings"| node_config
node_animals -->|"uses profiles"| node_locomotion
node_behaviour -->|"applies behaviours"| node_animals
node_auras -->|"uses tiers"| node_rarity
node_settings -->|"updates"| node_config
node_settings -->|"imports critters"| node_import
node_settings -->|"exports and imports"| node_sharing
node_settings -->|"refreshes"| node_registry
node_settings -->|"shows"| node_previews
node_settings -->|"renders previews"| node_preview_render
node_settings -->|"previews sounds"| node_sounds
node_import -->|"removes backgrounds"| node_bg
node_import -->|"generates masks"| node_masks
node_import -->|"extracts palette"| node_palette
node_import -->|"generates animation"| node_procedural
node_import -->|"writes critter data"| node_custom_store
node_sharing -->|"reads and writes"| node_custom_store
node_registry -->|"loads critter files"| node_custom_store
node_custom_animal -->|"uses records"| node_registry
node_preview_render -->|"renders"| node_animals

click node_main "https://github.com/hstagg/critter-overlay/blob/main/src/main.py"
click node_overlay "https://github.com/hstagg/critter-overlay/blob/main/src/overlay.py"
click node_events "https://github.com/hstagg/critter-overlay/blob/main/src/events.py"
click node_settings "https://github.com/hstagg/critter-overlay/blob/main/src/settings_window.py"
click node_config "https://github.com/hstagg/critter-overlay/blob/main/src/config.py"
click node_spawn "https://github.com/hstagg/critter-overlay/blob/main/src/spawn_manager.py"
click node_animals "https://github.com/hstagg/critter-overlay/blob/main/src/animals.py"
click node_custom_animal "https://github.com/hstagg/critter-overlay/blob/main/src/animals_custom.py"
click node_behaviour "https://github.com/hstagg/critter-overlay/blob/main/src/behaviours.py"
click node_locomotion "https://github.com/hstagg/critter-overlay/blob/main/src/locomotion.py"
click node_daynight "https://github.com/hstagg/critter-overlay/blob/main/src/time_of_day.py"
click node_rarity "https://github.com/hstagg/critter-overlay/blob/main/src/rarity.py"
click node_auras "https://github.com/hstagg/critter-overlay/blob/main/src/auras.py"
click node_sounds "https://github.com/hstagg/critter-overlay/blob/main/src/sounds.py"
click node_previews "https://github.com/hstagg/critter-overlay/blob/main/src/animal_previews.py"
click node_preview_render "https://github.com/hstagg/critter-overlay/blob/main/src/preview_renderer.py"
click node_import "https://github.com/hstagg/critter-overlay/blob/main/src/custom_critters/import_pipeline.py"
click node_sharing "https://github.com/hstagg/critter-overlay/blob/main/src/custom_critters/sharing.py"
click node_registry "https://github.com/hstagg/critter-overlay/blob/main/src/custom_critters/registry.py"
click node_custom_store "https://github.com/hstagg/critter-overlay/blob/main/src/custom_critters/storage.py"
click node_bg "https://github.com/hstagg/critter-overlay/blob/main/src/custom_critters/bg_removal.py"
click node_masks "https://github.com/hstagg/critter-overlay/blob/main/src/custom_critters/masks.py"
click node_palette "https://github.com/hstagg/critter-overlay/blob/main/src/custom_critters/palette.py"
click node_procedural "https://github.com/hstagg/critter-overlay/blob/main/src/custom_critters/procedural.py"
click node_updater "https://github.com/hstagg/critter-overlay/blob/main/src/updater.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_main,node_overlay,node_events,node_sounds,node_updater,node_user toneBlue
class node_spawn,node_animals,node_behaviour,node_locomotion,node_daynight,node_rarity,node_auras toneAmber
class node_custom_animal,node_import,node_sharing,node_registry,node_bg,node_masks,node_palette,node_procedural toneMint
class node_settings,node_previews,node_preview_render toneRose
class node_config,node_custom_store toneIndigo
```

## Components

### App runtime

- [App and tray](https://github.com/hstagg/critter-overlay/blob/main/src/main.py): `src/main.py`
- [Desktop overlay](https://github.com/hstagg/critter-overlay/blob/main/src/overlay.py): `src/overlay.py`
- [Event dispatch](https://github.com/hstagg/critter-overlay/blob/main/src/events.py): `src/events.py`
- [Sound manager](https://github.com/hstagg/critter-overlay/blob/main/src/sounds.py): `src/sounds.py`
- [App updater](https://github.com/hstagg/critter-overlay/blob/main/src/updater.py): `src/updater.py`

### Critter simulation

- [Spawn manager](https://github.com/hstagg/critter-overlay/blob/main/src/spawn_manager.py): `src/spawn_manager.py`
- [Built-in animals](https://github.com/hstagg/critter-overlay/blob/main/src/animals.py): `src/animals.py`
- [Behaviours](https://github.com/hstagg/critter-overlay/blob/main/src/behaviours.py): `src/behaviours.py`
- [Locomotion profiles](https://github.com/hstagg/critter-overlay/blob/main/src/locomotion.py): `src/locomotion.py`
- [Day-night activity](https://github.com/hstagg/critter-overlay/blob/main/src/time_of_day.py): `src/time_of_day.py`
- [Rarity tiers](https://github.com/hstagg/critter-overlay/blob/main/src/rarity.py): `src/rarity.py`
- [Rarity auras](https://github.com/hstagg/critter-overlay/blob/main/src/auras.py): `src/auras.py`

### Custom critters

- [Custom animal](https://github.com/hstagg/critter-overlay/blob/main/src/animals_custom.py): `src/animals_custom.py`
- [Import pipeline](https://github.com/hstagg/critter-overlay/blob/main/src/custom_critters/import_pipeline.py): `src/custom_critters/import_pipeline.py`
- [Package sharing](https://github.com/hstagg/critter-overlay/blob/main/src/custom_critters/sharing.py): `src/custom_critters/sharing.py`
- [Critter registry](https://github.com/hstagg/critter-overlay/blob/main/src/custom_critters/registry.py): `src/custom_critters/registry.py`
- [Background removal](https://github.com/hstagg/critter-overlay/blob/main/src/custom_critters/bg_removal.py): `src/custom_critters/bg_removal.py`
- [Mask generation](https://github.com/hstagg/critter-overlay/blob/main/src/custom_critters/masks.py): `src/custom_critters/masks.py`
- [Palette extraction](https://github.com/hstagg/critter-overlay/blob/main/src/custom_critters/palette.py): `src/custom_critters/palette.py`
- [Walk-cycle generation](https://github.com/hstagg/critter-overlay/blob/main/src/custom_critters/procedural.py): `src/custom_critters/procedural.py`

### Controls and settings

- [Settings UI](https://github.com/hstagg/critter-overlay/blob/main/src/settings_window.py): `src/settings_window.py`
- [Animal previews](https://github.com/hstagg/critter-overlay/blob/main/src/animal_previews.py): `src/animal_previews.py`
- [Preview renderer](https://github.com/hstagg/critter-overlay/blob/main/src/preview_renderer.py): `src/preview_renderer.py`

### Persistent state

- [Configuration](https://github.com/hstagg/critter-overlay/blob/main/src/config.py): `src/config.py`
- [Critter files](https://github.com/hstagg/critter-overlay/blob/main/src/custom_critters/storage.py): `src/custom_critters/storage.py`

### Other components

- **User**

## Connections

- User → App and tray: launches (evidence: `README.md`)
- App and tray → Configuration: loads (evidence: `src/main.py`)
- App and tray → Desktop overlay: starts (evidence: `src/main.py`)
- App and tray → Settings UI: opens (evidence: `src/main.py`)
- App and tray → Event dispatch: dispatches (evidence: `src/main.py`)
- App and tray → Critter registry: loads (evidence: `src/main.py`)
- App and tray → Sound manager: initializes (evidence: `src/main.py`)
- App and tray → App updater: uses (evidence: `src/main.py`)
- Desktop overlay → Spawn manager: requests spawns (evidence: `src/overlay.py`)
- Desktop overlay → Built-in animals: renders and updates (evidence: `src/overlay.py`)
- Desktop overlay → Rarity auras: renders (evidence: `src/overlay.py`)
- Desktop overlay → Sound manager: plays (evidence: `src/overlay.py`)
- Desktop overlay → Configuration: reads (evidence: `src/overlay.py`)
- Desktop overlay → Event dispatch: handles (evidence: `src/overlay.py`)
- Spawn manager → Built-in animals: creates (evidence: `src/spawn_manager.py`)
- Spawn manager → Custom animal: creates (evidence: `src/spawn_manager.py`)
- Spawn manager → Critter registry: queries (evidence: `src/spawn_manager.py`)
- Spawn manager → Rarity tiers: rolls tiers (evidence: `src/spawn_manager.py`)
- Spawn manager → Behaviours: triggers (evidence: `src/spawn_manager.py`)
- Spawn manager → Day-night activity: scales activity (evidence: `src/spawn_manager.py`)
- Spawn manager → Configuration: reads settings (evidence: `src/spawn_manager.py`)
- Built-in animals → Locomotion profiles: uses profiles (evidence: `src/animals.py`)
- Behaviours → Built-in animals: applies behaviours (evidence: `src/behaviours.py`)
- Rarity auras → Rarity tiers: uses tiers (evidence: `src/auras.py`)
- Settings UI → Configuration: updates (evidence: `src/settings_window.py`)
- Settings UI → Import pipeline: imports critters (evidence: `src/settings_window.py`)
- Settings UI → Package sharing: exports and imports (evidence: `src/settings_window.py`)
- Settings UI → Critter registry: refreshes (evidence: `src/settings_window.py`)
- Settings UI → Animal previews: shows (evidence: `src/settings_window.py`)
- Settings UI → Preview renderer: renders previews (evidence: `src/settings_window.py`)
- Settings UI → Sound manager: previews sounds (evidence: `src/settings_window.py`)
- Import pipeline → Background removal: removes backgrounds (evidence: `src/custom_critters/import_pipeline.py`)
- Import pipeline → Mask generation: generates masks (evidence: `src/custom_critters/import_pipeline.py`)
- Import pipeline → Palette extraction: extracts palette (evidence: `src/custom_critters/import_pipeline.py`)
- Import pipeline → Walk-cycle generation: generates animation (evidence: `src/custom_critters/import_pipeline.py`)
- Import pipeline → Critter files: writes critter data (evidence: `src/custom_critters/import_pipeline.py`)
- Package sharing → Critter files: reads and writes (evidence: `src/custom_critters/sharing.py`)
- Critter registry → Critter files: loads critter files (evidence: `src/custom_critters/registry.py`)
- Custom animal → Critter registry: uses records (evidence: `src/animals_custom.py`)
- Preview renderer → Built-in animals: renders (evidence: `src/preview_renderer.py`)
