# cap153/stools architecture

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

- Interactive diagram: https://gitdiagram.com/cap153/stools
- Repository: https://github.com/cap153/stools

## Overview

stools is a lightweight desktop application launcher. The main workflow is platform-specific startup, application discovery and indexing, interactive fuzzy/pinyin search with MRU ranking, display in a Slint window, and launching the selected entry. Configuration, keybindings, themes, localization, and platform-specific Windows tray/hotkey behavior are supporting capabilities. Some subsystem links rely on README or SOURCE INDEX references rather than inspected implementation excerpts.

Main entry points: [`src/platform/windows.rs`](https://github.com/cap153/stools/blob/main/src/platform/windows.rs) (Windows tray runtime), [`src/platform/linux.rs`](https://github.com/cap153/stools/blob/main/src/platform/linux.rs) (Linux runtime), [`src/launcher.rs`](https://github.com/cap153/stools/blob/main/src/launcher.rs) (Row and icon helpers), [`src/core/search.rs`](https://github.com/cap153/stools/blob/main/src/core/search.rs) (Search worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Platform runtime"]
  node_main["Entry dispatch<br/>[main.rs]"]
  node_linux["Linux runtime<br/>[linux.rs]"]
  node_windows["Windows tray runtime<br/>[windows.rs]"]
end

subgraph group_catalog["App catalog"]
  node_entry_model["App entry model<br/>[model.rs]"]
  node_indexer["Index cache<br/>[indexer.rs]"]
  node_linux_scan["Linux app scan<br/>[linux.rs]"]
  node_windows_scan["Windows app scan<br/>[windows.rs]"]
  node_windows_icons["Shell icons<br/>[windows_icon.rs]"]
end

subgraph group_search["Search and launcher UI"]
  node_slint_ui["Launcher window<br/>[launcher.slint]"]
  node_launcher["Row and icon helpers<br/>[launcher.rs]"]
  node_search_worker["Search worker<br/>[search.rs]"]
  node_matcher["Fuzzy and pinyin matcher<br/>[matcher.rs]"]
end

subgraph group_settings["Preferences and state"]
  node_config["Configuration<br/>[config.rs]"]
  node_paths["Search paths<br/>[path_utils.rs]"]
  node_keybind["Keybindings<br/>[keybind.rs]"]
  node_theme["Theme rendering<br/>[theme.rs]"]
  node_i18n["Locale support<br/>[i18n.rs]"]
  node_history[("MRU history<br/>[history.rs]")]
end

node_user(("User"))
node_wm["Window manager"]
node_system["Operating system"]

node_user -->|"starts launcher"| node_main
node_wm -->|"binds launch key"| node_linux
node_main -->|"dispatches on Linux"| node_linux
node_main -->|"dispatches on Windows"| node_windows
node_linux -->|"loads settings"| node_config
node_windows -->|"loads settings"| node_config
node_config -->|"selects template"| node_i18n
node_linux -->|"resolves scan dirs"| node_paths
node_windows -->|"resolves scan dirs"| node_paths
node_linux -->|"scans applications"| node_linux_scan
node_windows -->|"scans applications"| node_windows_scan
node_linux_scan -->|"builds entries"| node_entry_model
node_windows_scan -->|"builds entries"| node_entry_model
node_linux -->|"loads index cache"| node_indexer
node_indexer -->|"stores entries"| node_entry_model
node_linux -->|"handles bindings"| node_keybind
node_windows -->|"handles bindings"| node_keybind
node_windows -->|"registers hotkey"| node_system
node_windows -->|"rescans in background"| node_windows_scan
node_linux -->|"creates search"| node_search_worker
node_windows -->|"creates search"| node_search_worker
node_search_worker -->|"ranks queries"| node_matcher
node_matcher -->|"ranks by recency"| node_history
node_search_worker -->|"updates results"| node_slint_ui
node_linux -->|"builds visible rows"| node_launcher
node_windows -->|"builds visible rows"| node_launcher
node_launcher -->|"provides row data"| node_slint_ui
node_launcher -->|"loads shell icons"| node_windows_icons
node_linux -->|"launches selection"| node_system
node_windows -->|"shell launches selection"| node_system
node_linux -->|"records launches"| node_history
node_windows -->|"records launches"| node_history
node_config -->|"supplies theme"| node_theme
node_linux -->|"applies appearance"| node_theme
node_windows -->|"applies appearance"| node_theme

click node_main "https://github.com/cap153/stools/blob/main/src/main.rs"
click node_linux "https://github.com/cap153/stools/blob/main/src/platform/linux.rs"
click node_windows "https://github.com/cap153/stools/blob/main/src/platform/windows.rs"
click node_slint_ui "https://github.com/cap153/stools/blob/main/ui/launcher.slint"
click node_launcher "https://github.com/cap153/stools/blob/main/src/launcher.rs"
click node_search_worker "https://github.com/cap153/stools/blob/main/src/core/search.rs"
click node_matcher "https://github.com/cap153/stools/blob/main/src/core/matcher.rs"
click node_entry_model "https://github.com/cap153/stools/blob/main/src/core/model.rs"
click node_indexer "https://github.com/cap153/stools/blob/main/src/core/indexer.rs"
click node_linux_scan "https://github.com/cap153/stools/blob/main/src/platform/linux.rs"
click node_windows_scan "https://github.com/cap153/stools/blob/main/src/platform/windows.rs"
click node_windows_icons "https://github.com/cap153/stools/blob/main/src/platform/windows_icon.rs"
click node_config "https://github.com/cap153/stools/blob/main/src/core/config.rs"
click node_paths "https://github.com/cap153/stools/blob/main/src/core/path_utils.rs"
click node_keybind "https://github.com/cap153/stools/blob/main/src/core/keybind.rs"
click node_theme "https://github.com/cap153/stools/blob/main/src/core/theme.rs"
click node_i18n "https://github.com/cap153/stools/blob/main/src/core/i18n.rs"
click node_history "https://github.com/cap153/stools/blob/main/src/core/history.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_main,node_linux,node_windows,node_user toneBlue
class node_entry_model,node_indexer,node_linux_scan,node_windows_scan,node_windows_icons toneAmber
class node_slint_ui,node_launcher,node_search_worker,node_matcher toneMint
class node_config,node_paths,node_keybind,node_theme,node_i18n,node_history toneRose
class node_wm,node_system toneIndigo
```

## Components

### Platform runtime

- [Entry dispatch](https://github.com/cap153/stools/blob/main/src/main.rs): `src/main.rs`
- [Linux runtime](https://github.com/cap153/stools/blob/main/src/platform/linux.rs): `src/platform/linux.rs`
- [Windows tray runtime](https://github.com/cap153/stools/blob/main/src/platform/windows.rs): `src/platform/windows.rs`

### App catalog

- [App entry model](https://github.com/cap153/stools/blob/main/src/core/model.rs): `src/core/model.rs`
- [Index cache](https://github.com/cap153/stools/blob/main/src/core/indexer.rs): `src/core/indexer.rs`
- [Linux app scan](https://github.com/cap153/stools/blob/main/src/platform/linux.rs): `src/platform/linux.rs`
- [Windows app scan](https://github.com/cap153/stools/blob/main/src/platform/windows.rs): `src/platform/windows.rs`
- [Shell icons](https://github.com/cap153/stools/blob/main/src/platform/windows_icon.rs): `src/platform/windows_icon.rs`

### Search and launcher UI

- [Launcher window](https://github.com/cap153/stools/blob/main/ui/launcher.slint): `ui/launcher.slint`
- [Row and icon helpers](https://github.com/cap153/stools/blob/main/src/launcher.rs): `src/launcher.rs`
- [Search worker](https://github.com/cap153/stools/blob/main/src/core/search.rs): `src/core/search.rs`
- [Fuzzy and pinyin matcher](https://github.com/cap153/stools/blob/main/src/core/matcher.rs): `src/core/matcher.rs`

### Preferences and state

- [Configuration](https://github.com/cap153/stools/blob/main/src/core/config.rs): `src/core/config.rs`
- [Search paths](https://github.com/cap153/stools/blob/main/src/core/path_utils.rs): `src/core/path_utils.rs`
- [Keybindings](https://github.com/cap153/stools/blob/main/src/core/keybind.rs): `src/core/keybind.rs`
- [Theme rendering](https://github.com/cap153/stools/blob/main/src/core/theme.rs): `src/core/theme.rs`
- [Locale support](https://github.com/cap153/stools/blob/main/src/core/i18n.rs): `src/core/i18n.rs`
- [MRU history](https://github.com/cap153/stools/blob/main/src/core/history.rs): `src/core/history.rs`

### Other components

- **User**
- **Window manager**
- **Operating system**

## Connections

- User → Entry dispatch: starts launcher (evidence: `README.md`)
- Window manager → Linux runtime: binds launch key (evidence: `README.md`)
- Entry dispatch → Linux runtime: dispatches on Linux (evidence: `src/main.rs`)
- Entry dispatch → Windows tray runtime: dispatches on Windows (evidence: `src/main.rs`)
- Linux runtime → Configuration: loads settings (evidence: `src/platform/linux.rs`)
- Windows tray runtime → Configuration: loads settings (evidence: `src/platform/windows.rs`)
- Configuration → Locale support: selects template (evidence: `src/core/config.rs`)
- Linux runtime → Search paths: resolves scan dirs (evidence: `src/platform/linux.rs`)
- Windows tray runtime → Search paths: resolves scan dirs (evidence: `src/platform/windows.rs`)
- Linux runtime → Linux app scan: scans applications (evidence: `README.md`)
- Windows tray runtime → Windows app scan: scans applications (evidence: `README.md`)
- Linux app scan → App entry model: builds entries (evidence: `src/platform/linux.rs`)
- Windows app scan → App entry model: builds entries (evidence: `src/platform/windows.rs`)
- Linux runtime → Index cache: loads index cache (evidence: `README.md`)
- Index cache → App entry model: stores entries (evidence: `src/core/indexer.rs`)
- Linux runtime → Keybindings: handles bindings (evidence: `src/platform/linux.rs`)
- Windows tray runtime → Keybindings: handles bindings (evidence: `src/platform/windows.rs`)
- Windows tray runtime → Operating system: registers hotkey (evidence: `README.md`)
- Windows tray runtime → Windows app scan: rescans in background (evidence: `src/platform/windows.rs`)
- Linux runtime → Search worker: creates search (evidence: `src/platform/linux.rs`)
- Windows tray runtime → Search worker: creates search (evidence: `src/platform/windows.rs`)
- Search worker → Fuzzy and pinyin matcher: ranks queries (evidence: `src/core/search.rs`)
- Fuzzy and pinyin matcher → MRU history: ranks by recency (evidence: `src/core/matcher.rs`)
- Search worker → Launcher window: updates results (evidence: `src/core/search.rs`)
- Linux runtime → Row and icon helpers: builds visible rows (evidence: `src/platform/linux.rs`)
- Windows tray runtime → Row and icon helpers: builds visible rows (evidence: `src/platform/windows.rs`)
- Row and icon helpers → Launcher window: provides row data (evidence: `src/launcher.rs`)
- Row and icon helpers → Shell icons: loads shell icons (evidence: `src/launcher.rs`)
- Linux runtime → Operating system: launches selection (evidence: `README.md`)
- Windows tray runtime → Operating system: shell launches selection (evidence: `README.md`)
- Linux runtime → MRU history: records launches (evidence: `README.md`)
- Windows tray runtime → MRU history: records launches (evidence: `README.md`)
- Configuration → Theme rendering: supplies theme (evidence: `src/core/theme.rs`)
- Linux runtime → Theme rendering: applies appearance (evidence: `src/platform/linux.rs`)
- Windows tray runtime → Theme rendering: applies appearance (evidence: `src/platform/windows.rs`)