# coffee7cup/app-drawer-rs architecture

> Architecture diagram of the GitHub repository coffee7cup/app-drawer-rs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/coffee7cup/app-drawer-rs
- Repository: https://github.com/coffee7cup/app-drawer-rs

## Overview

1. **What this repo is**
   - This is a Rust-based **Wayland layer-shell launcher/dock** for the **Niri** compositor.
   - It has two primary modes in the UI: an **app launcher dock** and a **window switcher / active-app dock**.

2. **Top-level runtime flow**
   - `src/main.rs` is the entrypoint and likely wires together configuration, app discovery, Niri state, and the GUI event loop.
   - The program runs locally on the Wayland session; there is no backend service. Its “backend” is the compositor and the local desktop-entry filesystem.

3. **GUI / presentation layer**
   - `src/app_launcher.rs` is the core presentation and interaction module.
   - It likely owns the layer-shell surface, rendering, animations, hover/enter behavior, scrolling behavior, and the switch between launcher vs active-app views.
   - The README indicates dynamic surface sizing and reactive padding are used to create the dock-like motion and the “pop up” effect.

4. **App discovery subsystem**
   - `src/apps.rs` is the app catalog layer.
   - It scans desktop entries from `/usr/share/applications` and `~/.local/share/applications`, resolves metadata, and loads icons from sources like `linicons` and `freedesktop_icons`.
   - This is the source of the launcher’s searchable app list and icon model.

5. **Launching apps**
   - `src/init_app.rs` appears to encapsulate the launch action for a selected app.
   - The actual spawn path goes through **Niri IPC** using `Action::SpawnSh`, so launching is delegated to the compositor rather than shelling out directly from UI code.
   - This keeps launch behavior tied to the Niri session and its command execution model.

6. **Active windows / switcher subsystem**
   - `src/current_apps.rs` likely queries the compositor for current windows and maps them into launcher-friendly items.
   - The README says it uses `niri_ipc::Request::Windows` to fetch active apps, so this module is the bridge from compositor window state into the UI list.

7. **Focus and workspace logic**
   - `src/workspaces.rs` probably organizes windows by workspace and/or determines which workspace should receive focus when an item is selected.
   - Focus behavior is implemented via **Niri IPC** using `Request::FocusWindow(id)`.
   - This is the boundary where the app switches from passive browsing to compositor control.

8. **Caching and ranking**
   - `src/config.rs` and the cache-related behavior described in the README suggest a local persistence layer for frequently used apps.
   - The app list is not just static enumeration; it is reordered so commonly used apps stay prominent, which affects the launcher’s first-screen ranking.
   - This is a local optimization path, not a networked or shared cache.

9. **Error handling and startup orchestration**
   - `src/error.rs` provides a project-wide error type for failures across filesystem scanning, icon loading, IPC calls, and UI setup.
   - `src/init_app.rs` and `src/config.rs` likely work together during startup to build the initial model before the GUI renders.

10. **Assets and presentation resources**
   - `assets/` contains demo media and likely icon or visual resources used by the app.
   - These are not part of the runtime logic, but they support the visual identity of the launcher and documentation.

11. **Main external dependencies that shape architecture**
   - **Wayland + layer-shell**: defines the app as an overlay-like surface rather than a normal window.
   - **guido**: the GUI framework used for rendering, interaction, and dynamic list behavior.
   - **niri_ipc**: the control plane for window queries, focus changes, and app spawning.
   - **freedesktop desktop entries / icon themes**: the source of app metadata and visuals.

12. **Overall data flow to diagram**
   - Desktop entries and icon metadata are read from the filesystem, normalized into app records, optionally ranked by cache/frequency, then rendered in the layer-shell UI.
   - User selection flows back through Niri IPC to either **spawn an app** or **focus an existing window**.
   - The active-window path is separate from the app-discovery path but reuses the same icon/app model to keep the UI consistent.

13. **Useful architectural boundary to draw**
   - A clean diagram would show three layers: **desktop data sources + Niri IPC**, **Rust domain modules (`apps`, `current_apps`, `workspaces`, `config`)**, and **the GUI surface (`app_launcher`)**.
   - The key integration points are the filesystem scan, the cache/ranking step, and the two compositor actions: spawn and focus.

Main entry points: [`src/app_launcher.rs`](https://github.com/coffee7cup/app-drawer-rs/blob/main/src/app_launcher.rs) (App launcher), [`src/apps.rs`](https://github.com/coffee7cup/app-drawer-rs/blob/main/src/apps.rs) (Apps), [`src/main.rs`](https://github.com/coffee7cup/app-drawer-rs/blob/main/src/main.rs) (Main), [`src/current_apps.rs`](https://github.com/coffee7cup/app-drawer-rs/blob/main/src/current_apps.rs) (Current apps)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_runtime["Runtime"]
  node_main["Main<br/>entrypoint<br/>[main.rs]"]
  node_app_launcher["App launcher<br/>ui shell<br/>[app_launcher.rs]"]
end

subgraph group_group_domain["Domain"]
  node_apps[("Apps<br/>catalog<br/>[apps.rs]")]
  node_current_apps[("Current apps<br/>window list<br/>[current_apps.rs]")]
  node_workspaces["Workspaces<br/>focus routing<br/>[workspaces.rs]"]
  node_config[("Config<br/>settings cache<br/>[config.rs]")]
  node_init_app["Init app<br/>launch action<br/>[init_app.rs]"]
  node_error{{"Errors<br/>error model<br/>[error.rs]"}}
end

subgraph group_group_system["System"]
  node_desktop_entries["Desktop entries<br/>filesystem source"]
  node_icon_themes["Icons<br/>icon source"]
  node_niri_ipc{{"Niri IPC<br/>compositor API"}}
  node_wayland_layer_shell{{"Layer shell<br/>surface backend"}}
  node_guido["GUI framework"]
  node_assets_dir["Assets<br/>resource pack"]
end

node_main -->|"starts"| node_app_launcher
node_main -->|"loads"| node_apps
node_main -->|"loads"| node_current_apps
node_main -->|"reads"| node_config
node_main -.->|"uses"| node_error
node_app_launcher -->|"renders"| node_guido
node_app_launcher -->|"hosts on"| node_wayland_layer_shell
node_app_launcher -->|"shows"| node_apps
node_app_launcher -->|"shows"| node_current_apps
node_app_launcher -->|"routes focus"| node_workspaces
node_app_launcher -->|"launches"| node_init_app
node_app_launcher -->|"applies"| node_config
node_app_launcher -.->|"uses"| node_assets_dir
node_apps -->|"scans"| node_desktop_entries
node_apps -->|"resolves"| node_icon_themes
node_apps -->|"ranks"| node_config
node_apps -.->|"fails with"| node_error
node_current_apps -->|"queries"| node_niri_ipc
node_current_apps -->|"organizes"| node_workspaces
node_current_apps -.->|"fails with"| node_error
node_workspaces -->|"focuses"| node_niri_ipc
node_init_app -->|"spawns"| node_niri_ipc
node_config -.->|"fails with"| node_error

click node_main "https://github.com/coffee7cup/app-drawer-rs/blob/main/src/main.rs"
click node_app_launcher "https://github.com/coffee7cup/app-drawer-rs/blob/main/src/app_launcher.rs"
click node_apps "https://github.com/coffee7cup/app-drawer-rs/blob/main/src/apps.rs"
click node_current_apps "https://github.com/coffee7cup/app-drawer-rs/blob/main/src/current_apps.rs"
click node_workspaces "https://github.com/coffee7cup/app-drawer-rs/blob/main/src/workspaces.rs"
click node_config "https://github.com/coffee7cup/app-drawer-rs/blob/main/src/config.rs"
click node_init_app "https://github.com/coffee7cup/app-drawer-rs/blob/main/src/init_app.rs"
click node_error "https://github.com/coffee7cup/app-drawer-rs/blob/main/src/error.rs"
click node_assets_dir "https://github.com/coffee7cup/app-drawer-rs/tree/main/assets"

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_app_launcher toneBlue
class node_apps,node_current_apps,node_workspaces,node_config,node_init_app,node_error toneAmber
class node_desktop_entries,node_icon_themes,node_niri_ipc,node_wayland_layer_shell,node_guido,node_assets_dir toneMint
```

## Components

### Runtime

Entry point and user-facing Wayland layer-shell UI.

- [Main](https://github.com/coffee7cup/app-drawer-rs/blob/main/src/main.rs): entrypoint · Starts the app and wires the runtime. · `src/main.rs`
- [App launcher](https://github.com/coffee7cup/app-drawer-rs/blob/main/src/app_launcher.rs): ui shell · Layer-shell surface, interaction, and view switching. · `src/app_launcher.rs`

### Domain

App catalog, window state, ranking, and selection logic.

- [Apps](https://github.com/coffee7cup/app-drawer-rs/blob/main/src/apps.rs): catalog · Discovers desktop apps and icons. · `src/apps.rs`
- [Current apps](https://github.com/coffee7cup/app-drawer-rs/blob/main/src/current_apps.rs): window list · Reads compositor window state into launcher items. · `src/current_apps.rs`
- [Workspaces](https://github.com/coffee7cup/app-drawer-rs/blob/main/src/workspaces.rs): focus routing · Groups windows and resolves workspace focus behavior. · `src/workspaces.rs`
- [Config](https://github.com/coffee7cup/app-drawer-rs/blob/main/src/config.rs): settings cache · Stores local preferences and ranking state. · `src/config.rs`
- [Init app](https://github.com/coffee7cup/app-drawer-rs/blob/main/src/init_app.rs): launch action · Turns a selection into a compositor spawn request. · `src/init_app.rs`
- [Errors](https://github.com/coffee7cup/app-drawer-rs/blob/main/src/error.rs): error model · Shared repository error type. · `src/error.rs`

### System

Filesystem, compositor IPC, and visual assets that feed the app.

- **Desktop entries**: filesystem source · System and user application metadata.
- **Icons**: icon source · Freedesktop and local icon lookup sources.
- **Niri IPC**: compositor API · Queries windows and sends spawn or focus actions.
- **Layer shell**: surface backend · Wayland overlay surface used for dock-like presentation.
- **GUI framework**: ui framework · Rendering and interaction framework for the surface.
- [Assets](https://github.com/coffee7cup/app-drawer-rs/tree/main/assets): resource pack · Visual assets and demo media. · `assets`

## Connections

- Main → App launcher: starts · Main initializes the launcher runtime and enters the UI loop.
- Main → Apps: loads · Startup builds the initial app model from the catalog.
- Main → Current apps: loads · Startup reads current compositor windows for active-app mode.
- Main → Config: reads · Startup loads local settings and ranking state.
- Main → Errors: uses · Entry path propagates setup and runtime failures.
- App launcher → GUI framework: renders · Presentation and interaction are driven by the GUI framework.
- App launcher → Layer shell: hosts on · The UI is presented as a layer-shell surface.
- App launcher → Apps: shows · Launcher view consumes the discovered app catalog.
- App launcher → Current apps: shows · Switcher view consumes current window items.
- App launcher → Workspaces: routes focus · Selection can be routed by workspace or window grouping.
- App launcher → Init app: launches · User selection can trigger app launch actions.
- App launcher → Config: applies · Uses configuration and ranking data for behavior and ordering.
- App launcher → Assets: uses · Visual assets support presentation and documentation.
- Apps → Desktop entries: scans · Reads system and user desktop-entry files.
- Apps → Icons: resolves · Maps apps to icons from theme sources.
- Apps → Config: ranks · Uses local preference/cache data to reorder apps.
- Apps → Errors: fails with · Catalog building can surface filesystem and icon errors.
- Current apps → Niri IPC: queries · Fetches active windows from the compositor.
- Current apps → Workspaces: organizes · Window state is organized into workspace-aware items.
- Current apps → Errors: fails with · IPC or mapping errors propagate through the shared error type.
- Workspaces → Niri IPC: focuses · Workspace selection can emit focus-window requests.
- Init app → Niri IPC: spawns · Launches the selected app through compositor execution.
- Config → Errors: fails with · Settings and cache I/O errors use the shared error type.