# vladelaina/bongocat architecture

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

## Overview

BongoCat is a desktop companion that displays animated Live2D pets and reacts to mouse, keyboard, and gamepad activity. The main workflow is startup and configuration, model selection/loading, event processing, model animation, and rendering in a transparent desktop window. Users can also import models and configure behavior through preferences; audio, tray, multi-pet support, and update checking broaden the runtime. The map uses the README and sampled source; some subsystem connections are omitted where the available excerpts do not establish their wiring.

Main entry points: [`src/runtime/lifecycle/app_loop.c`](https://github.com/vladelaina/bongocat/blob/main/src/runtime/lifecycle/app_loop.c) (Main loop), [`src/runtime/lifecycle/app.c`](https://github.com/vladelaina/bongocat/blob/main/src/runtime/lifecycle/app.c) (App startup), [`src/ui/preferences/preferences.c`](https://github.com/vladelaina/bongocat/blob/main/src/ui/preferences/preferences.c) (Preferences UI), [`src/runtime/shell/window.c`](https://github.com/vladelaina/bongocat/blob/main/src/runtime/shell/window.c) (Desktop window)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_lifecycle["App lifecycle"]
  node_app["App startup<br/>[app.c]"]
  node_loop["Main loop<br/>[app_loop.c]"]
  node_storage["Storage paths<br/>[storage_paths.c]"]
  node_config["Config store<br/>[config_store.c]"]
end

subgraph group_models["Models and import"]
  node_import["Model import<br/>[model_import_app.c]"]
  node_import_worker["Import worker"]
  node_catalog["Model catalog"]
  node_storage_models["Model storage<br/>[model_storage.c]"]
end

subgraph group_interaction["Input and rendering"]
  node_window["Desktop window<br/>[window.c]"]
  node_platform["Platform input<br/>[linux.c]"]
  node_mouse["Mouse mapping<br/>[mouse_pipeline.c]"]
  node_shortcuts["Shortcuts<br/>[shortcuts.c]"]
  node_live2d["Live2D runtime"]
  node_overlay["Overlay renderer<br/>[overlay.c]"]
end

subgraph group_settings["Settings and UI"]
  node_ui["Preferences UI<br/>[preferences.c]"]
end

subgraph group_services["Runtime services"]
  node_audio["Audio playback<br/>[audio_playback.c]"]
  node_tray["System tray<br/>[tray.c]"]
  node_multi_pet["Multi-pet runtime<br/>[multi_pet.c]"]
  node_update["Update service<br/>[update_service.c]"]
end

node_user(("Desktop user"))

node_user -->|"interacts with"| node_window
node_user -->|"configures"| node_ui
node_app -->|"prepares paths"| node_storage
node_app -->|"loads settings"| node_config
node_app -->|"creates"| node_window
node_app -->|"selects model"| node_catalog
node_app -->|"runs"| node_loop
node_platform -->|"reports events"| node_loop
node_loop -->|"applies pointer"| node_mouse
node_mouse -->|"sets parameters"| node_live2d
node_loop -->|"updates model"| node_live2d
node_loop -->|"renders frame"| node_overlay
node_overlay -->|"draws into"| node_window
node_ui -->|"saves settings"| node_config
node_ui -->|"starts import"| node_import_worker
node_import_worker -->|"installs sources"| node_import
node_import -->|"writes model files"| node_storage_models
node_catalog -->|"uses model files"| node_storage_models
node_loop -->|"processes shortcuts"| node_shortcuts
node_loop -->|"plays sounds"| node_audio
node_loop -->|"updates tray"| node_tray
node_loop -->|"coordinates pets"| node_multi_pet
node_loop -->|"checks updates"| node_update

click node_app "https://github.com/vladelaina/bongocat/blob/main/src/runtime/lifecycle/app.c"
click node_loop "https://github.com/vladelaina/bongocat/blob/main/src/runtime/lifecycle/app_loop.c"
click node_storage "https://github.com/vladelaina/bongocat/blob/main/src/runtime/lifecycle/storage_paths.c"
click node_config "https://github.com/vladelaina/bongocat/blob/main/src/runtime/lifecycle/config_store.c"
click node_window "https://github.com/vladelaina/bongocat/blob/main/src/runtime/shell/window.c"
click node_platform "https://github.com/vladelaina/bongocat/blob/main/src/platform/linux/linux.c"
click node_mouse "https://github.com/vladelaina/bongocat/blob/main/src/runtime/input/mouse_pipeline.c"
click node_shortcuts "https://github.com/vladelaina/bongocat/blob/main/src/runtime/input/shortcuts.c"
click node_live2d "https://github.com/vladelaina/bongocat/blob/main/src/live2d/cubism_model_update.cpp"
click node_overlay "https://github.com/vladelaina/bongocat/blob/main/src/render/overlay.c"
click node_ui "https://github.com/vladelaina/bongocat/blob/main/src/ui/preferences/preferences.c"
click node_import "https://github.com/vladelaina/bongocat/blob/main/src/runtime/model/import/model_import_app.c"
click node_import_worker "https://github.com/vladelaina/bongocat/blob/main/src/ui/preferences/preferences_import_worker.c"
click node_catalog "https://github.com/vladelaina/bongocat/blob/main/src/runtime/model/model_catalog_runtime.c"
click node_storage_models "https://github.com/vladelaina/bongocat/blob/main/src/runtime/model/model_storage.c"
click node_audio "https://github.com/vladelaina/bongocat/blob/main/src/media/audio/audio_playback.c"
click node_tray "https://github.com/vladelaina/bongocat/blob/main/src/runtime/shell/tray.c"
click node_multi_pet "https://github.com/vladelaina/bongocat/blob/main/src/runtime/model/multi_pet.c"
click node_update "https://github.com/vladelaina/bongocat/blob/main/src/runtime/update/update_service.c"

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_loop,node_storage,node_config,node_user toneBlue
class node_import,node_import_worker,node_catalog,node_storage_models toneAmber
class node_window,node_platform,node_mouse,node_shortcuts,node_live2d,node_overlay toneMint
class node_ui toneRose
class node_audio,node_tray,node_multi_pet,node_update toneIndigo
```

## Components

### App lifecycle

- [App startup](https://github.com/vladelaina/bongocat/blob/main/src/runtime/lifecycle/app.c): `src/runtime/lifecycle/app.c`
- [Main loop](https://github.com/vladelaina/bongocat/blob/main/src/runtime/lifecycle/app_loop.c): `src/runtime/lifecycle/app_loop.c`
- [Storage paths](https://github.com/vladelaina/bongocat/blob/main/src/runtime/lifecycle/storage_paths.c): `src/runtime/lifecycle/storage_paths.c`
- [Config store](https://github.com/vladelaina/bongocat/blob/main/src/runtime/lifecycle/config_store.c): `src/runtime/lifecycle/config_store.c`

### Models and import

- [Model import](https://github.com/vladelaina/bongocat/blob/main/src/runtime/model/import/model_import_app.c): `src/runtime/model/import/model_import_app.c`
- [Import worker](https://github.com/vladelaina/bongocat/blob/main/src/ui/preferences/preferences_import_worker.c): `src/ui/preferences/preferences_import_worker.c`
- [Model catalog](https://github.com/vladelaina/bongocat/blob/main/src/runtime/model/model_catalog_runtime.c): `src/runtime/model/model_catalog_runtime.c`
- [Model storage](https://github.com/vladelaina/bongocat/blob/main/src/runtime/model/model_storage.c): `src/runtime/model/model_storage.c`

### Input and rendering

- [Desktop window](https://github.com/vladelaina/bongocat/blob/main/src/runtime/shell/window.c): `src/runtime/shell/window.c`
- [Platform input](https://github.com/vladelaina/bongocat/blob/main/src/platform/linux/linux.c): `src/platform/linux/linux.c`
- [Mouse mapping](https://github.com/vladelaina/bongocat/blob/main/src/runtime/input/mouse_pipeline.c): `src/runtime/input/mouse_pipeline.c`
- [Shortcuts](https://github.com/vladelaina/bongocat/blob/main/src/runtime/input/shortcuts.c): `src/runtime/input/shortcuts.c`
- [Live2D runtime](https://github.com/vladelaina/bongocat/blob/main/src/live2d/cubism_model_update.cpp): `src/live2d/cubism_model_update.cpp`
- [Overlay renderer](https://github.com/vladelaina/bongocat/blob/main/src/render/overlay.c): `src/render/overlay.c`

### Settings and UI

- [Preferences UI](https://github.com/vladelaina/bongocat/blob/main/src/ui/preferences/preferences.c): `src/ui/preferences/preferences.c`

### Runtime services

- [Audio playback](https://github.com/vladelaina/bongocat/blob/main/src/media/audio/audio_playback.c): `src/media/audio/audio_playback.c`
- [System tray](https://github.com/vladelaina/bongocat/blob/main/src/runtime/shell/tray.c): `src/runtime/shell/tray.c`
- [Multi-pet runtime](https://github.com/vladelaina/bongocat/blob/main/src/runtime/model/multi_pet.c): `src/runtime/model/multi_pet.c`
- [Update service](https://github.com/vladelaina/bongocat/blob/main/src/runtime/update/update_service.c): `src/runtime/update/update_service.c`

### Other components

- **Desktop user**

## Connections

- Desktop user → Desktop window: interacts with
- Desktop user → Preferences UI: configures
- App startup → Storage paths: prepares paths
- App startup → Config store: loads settings
- App startup → Desktop window: creates
- App startup → Model catalog: selects model
- App startup → Main loop: runs
- Platform input → Main loop: reports events
- Main loop → Mouse mapping: applies pointer
- Mouse mapping → Live2D runtime: sets parameters
- Main loop → Live2D runtime: updates model
- Main loop → Overlay renderer: renders frame
- Overlay renderer → Desktop window: draws into
- Preferences UI → Config store: saves settings
- Preferences UI → Import worker: starts import
- Import worker → Model import: installs sources
- Model import → Model storage: writes model files
- Model catalog → Model storage: uses model files
- Main loop → Shortcuts: processes shortcuts
- Main loop → Audio playback: plays sounds
- Main loop → System tray: updates tray
- Main loop → Multi-pet runtime: coordinates pets
- Main loop → Update service: checks updates