# lostxxi/nekowall architecture

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

- Interactive diagram: https://gitdiagram.com/lostxxi/nekowall
- Repository: https://github.com/lostxxi/nekowall

## Overview

NekoWall is a desktop wallpaper manager for KDE Plasma and MATE. Users browse or import images and videos, choose a display, and apply a wallpaper through the GUI or terminal; the quick selector and multi-monitor controls are part of that workflow. The Rust CLI connects the Qt/QML interface to the library, orchestration service, and desktop-specific backends. The README also documents automatic folder updates, thumbnails, video handling, and playback power-saving. Some QML and Rust implementation details were not sampled, so those relationships are included only where documentation or excerpts support them.

Main entry points: [`crates/nekowall-cli/src/main.rs`](https://github.com/lostxxi/nekowall/blob/main/crates/nekowall-cli/src/main.rs) (CLI commands), [`crates/nekowall-core/src/lib.rs`](https://github.com/lostxxi/nekowall/blob/main/crates/nekowall-core/src/lib.rs) (Wallpaper service), [`app/src/Bridge.cpp`](https://github.com/lostxxi/nekowall/blob/main/app/src/Bridge.cpp) (UI bridge), [`crates/nekowall-mate/src/lib.rs`](https://github.com/lostxxi/nekowall/blob/main/crates/nekowall-mate/src/lib.rs) (MATE backend)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Desktop interface"]
  node_gui["GUI entry<br/>[main.cpp]"]
  node_bridge["UI bridge<br/>[Bridge.cpp]"]
  node_library_page["Wallpaper library<br/>[LibraryPage.qml]"]
  node_hud["Quick selector<br/>[Hud.qml]"]
  node_settings["Settings<br/>[SettingsPage.qml]"]
end

subgraph group_workflow["Wallpaper workflow"]
  node_cli["CLI commands<br/>[main.rs]"]
  node_service["Wallpaper service<br/>[lib.rs]"]
  node_contract["Backend contract<br/>[lib.rs]"]
end

subgraph group_library["Library and media"]
  node_library_api["Library index<br/>[lib.rs]"]
  node_sqlite[("SQLite catalog<br/>[lib.rs]")]
  node_video_tools["Video analysis<br/>[media.rs]"]
end

subgraph group_desktop["Desktop backends"]
  node_plasma["Plasma backend<br/>[lib.rs]"]
  node_mate["MATE backend<br/>[lib.rs]"]
  node_mate_video["MATE video playback<br/>[video.rs]"]
  node_desktop_services["Desktop services"]
end

node_user(("User"))

node_user -->|"opens"| node_gui
node_user -->|"runs commands"| node_cli
node_gui -->|"creates"| node_bridge
node_bridge -->|"invokes asynchronously"| node_cli
node_library_page -->|"browses and applies"| node_bridge
node_hud -->|"selects wallpaper"| node_bridge
node_settings -.->|"configures"| node_bridge
node_cli -->|"orchestrates"| node_service
node_cli -->|"queries and updates"| node_library_api
node_cli -->|"probes and converts"| node_video_tools
node_cli -->|"dispatches playback commands"| node_mate_video
node_service -->|"reads and imports"| node_library_api
node_service -->|"applies through"| node_contract
node_library_api -->|"stores catalog state"| node_sqlite
node_service -.->|"uses when detected"| node_plasma
node_service -.->|"uses when detected"| node_mate
node_mate -->|"manages video playback"| node_mate_video
node_plasma -->|"controls wallpapers"| node_desktop_services
node_mate -->|"sets desktop backgrounds"| node_desktop_services
node_mate_video -->|"runs mpv via xwinwrap"| node_desktop_services

click node_gui "https://github.com/lostxxi/nekowall/blob/main/app/src/main.cpp"
click node_bridge "https://github.com/lostxxi/nekowall/blob/main/app/src/Bridge.cpp"
click node_library_page "https://github.com/lostxxi/nekowall/blob/main/app/qml/LibraryPage.qml"
click node_hud "https://github.com/lostxxi/nekowall/blob/main/app/qml/Hud.qml"
click node_settings "https://github.com/lostxxi/nekowall/blob/main/app/qml/SettingsPage.qml"
click node_cli "https://github.com/lostxxi/nekowall/blob/main/crates/nekowall-cli/src/main.rs"
click node_service "https://github.com/lostxxi/nekowall/blob/main/crates/nekowall-core/src/lib.rs"
click node_contract "https://github.com/lostxxi/nekowall/blob/main/crates/nekowall-backend/src/lib.rs"
click node_library_api "https://github.com/lostxxi/nekowall/blob/main/crates/nekowall-library/src/lib.rs"
click node_sqlite "https://github.com/lostxxi/nekowall/blob/main/crates/nekowall-library/src/lib.rs"
click node_video_tools "https://github.com/lostxxi/nekowall/blob/main/crates/nekowall-cli/src/media.rs"
click node_plasma "https://github.com/lostxxi/nekowall/blob/main/crates/nekowall-plasma/src/lib.rs"
click node_mate "https://github.com/lostxxi/nekowall/blob/main/crates/nekowall-mate/src/lib.rs"
click node_mate_video "https://github.com/lostxxi/nekowall/blob/main/crates/nekowall-mate/src/video.rs"

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_gui,node_bridge,node_library_page,node_hud,node_settings,node_user toneBlue
class node_cli,node_service,node_contract toneAmber
class node_library_api,node_sqlite,node_video_tools toneMint
class node_plasma,node_mate,node_mate_video,node_desktop_services toneRose
```

## Components

### Desktop interface

- [GUI entry](https://github.com/lostxxi/nekowall/blob/main/app/src/main.cpp): `app/src/main.cpp`
- [UI bridge](https://github.com/lostxxi/nekowall/blob/main/app/src/Bridge.cpp): `app/src/Bridge.cpp`
- [Wallpaper library](https://github.com/lostxxi/nekowall/blob/main/app/qml/LibraryPage.qml): `app/qml/LibraryPage.qml`
- [Quick selector](https://github.com/lostxxi/nekowall/blob/main/app/qml/Hud.qml): `app/qml/Hud.qml`
- [Settings](https://github.com/lostxxi/nekowall/blob/main/app/qml/SettingsPage.qml): `app/qml/SettingsPage.qml`

### Wallpaper workflow

- [CLI commands](https://github.com/lostxxi/nekowall/blob/main/crates/nekowall-cli/src/main.rs): `crates/nekowall-cli/src/main.rs`
- [Wallpaper service](https://github.com/lostxxi/nekowall/blob/main/crates/nekowall-core/src/lib.rs): `crates/nekowall-core/src/lib.rs`
- [Backend contract](https://github.com/lostxxi/nekowall/blob/main/crates/nekowall-backend/src/lib.rs): `crates/nekowall-backend/src/lib.rs`

### Library and media

- [Library index](https://github.com/lostxxi/nekowall/blob/main/crates/nekowall-library/src/lib.rs): `crates/nekowall-library/src/lib.rs`
- [SQLite catalog](https://github.com/lostxxi/nekowall/blob/main/crates/nekowall-library/src/lib.rs): `crates/nekowall-library/src/lib.rs`
- [Video analysis](https://github.com/lostxxi/nekowall/blob/main/crates/nekowall-cli/src/media.rs): `crates/nekowall-cli/src/media.rs`

### Desktop backends

- [Plasma backend](https://github.com/lostxxi/nekowall/blob/main/crates/nekowall-plasma/src/lib.rs): `crates/nekowall-plasma/src/lib.rs`
- [MATE backend](https://github.com/lostxxi/nekowall/blob/main/crates/nekowall-mate/src/lib.rs): `crates/nekowall-mate/src/lib.rs`
- [MATE video playback](https://github.com/lostxxi/nekowall/blob/main/crates/nekowall-mate/src/video.rs): `crates/nekowall-mate/src/video.rs`
- **Desktop services**

### Other components

- **User**

## Connections

- User → GUI entry: opens (evidence: `README.md`)
- User → CLI commands: runs commands (evidence: `README.md`)
- GUI entry → UI bridge: creates (evidence: `app/src/main.cpp`)
- UI bridge → CLI commands: invokes asynchronously
- Wallpaper library → UI bridge: browses and applies (evidence: `README.md`)
- Quick selector → UI bridge: selects wallpaper (evidence: `README.md`)
- Settings → UI bridge: configures
- CLI commands → Wallpaper service: orchestrates (evidence: `crates/nekowall-cli/src/main.rs`)
- CLI commands → Library index: queries and updates (evidence: `crates/nekowall-cli/src/main.rs`)
- CLI commands → Video analysis: probes and converts (evidence: `crates/nekowall-cli/src/main.rs`)
- CLI commands → MATE video playback: dispatches playback commands (evidence: `crates/nekowall-cli/src/main.rs`)
- Wallpaper service → Library index: reads and imports (evidence: `crates/nekowall-core/src/lib.rs`)
- Wallpaper service → Backend contract: applies through (evidence: `crates/nekowall-core/src/lib.rs`)
- Library index → SQLite catalog: stores catalog state (evidence: `crates/nekowall-library/src/lib.rs`)
- Wallpaper service → Plasma backend: uses when detected
- Wallpaper service → MATE backend: uses when detected
- MATE backend → MATE video playback: manages video playback (evidence: `crates/nekowall-mate/src/lib.rs`)
- Plasma backend → Desktop services: controls wallpapers (evidence: `README.md`)
- MATE backend → Desktop services: sets desktop backgrounds (evidence: `README.md`)
- MATE video playback → Desktop services: runs mpv via xwinwrap (evidence: `crates/nekowall-mate/src/video.rs`)
