# khaledtf19/popmax architecture

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

- Interactive diagram: https://gitdiagram.com/khaledtf19/popmax
- Repository: https://github.com/khaledtf19/popmax

## Overview

PopMax is a Windows desktop launcher: a global hotkey reveals a searchable app list, where users launch Start Menu apps or open bang searches in a browser; favorites and tray controls support repeat use. The graph also shows scanning, icon extraction, and persistence. Some implementation is only partially excerpted, so uncertain internal wiring is omitted; documented capabilities such as themes and single-instance behavior are retained.

Main entry points: [`src/launcher.rs`](https://github.com/khaledtf19/popmax/blob/main/src/launcher.rs) (Launcher window), [`src/main.rs`](https://github.com/khaledtf19/popmax/blob/main/src/main.rs) (App startup), [`src/scanner.rs`](https://github.com/khaledtf19/popmax/blob/main/src/scanner.rs) (App scanner), [`src/components/fav.rs`](https://github.com/khaledtf19/popmax/blob/main/src/components/fav.rs) (Favorites bar)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App experience"]
  node_main["App startup<br/>[main.rs]"]
  node_launcher["Launcher window<br/>[launcher.rs]"]
  node_search["Fuzzy search<br/>[search.rs]"]
  node_results["Results list<br/>[list.rs]"]
  node_bangs["Bang shortcuts<br/>[bangs.rs]"]
  node_themes["Theme loader<br/>[load_themes.rs]"]
  node_themefiles["Theme definitions"]
  node_favbar["Favorites bar<br/>[fav.rs]"]
end

subgraph group_catalog["App catalog"]
  node_scanner["App scanner<br/>[scanner.rs]"]
  node_iconextract["Icon extraction<br/>[windows_icons.rs]"]
end

subgraph group_state["User state"]
  node_scancache[("Scan cache<br/>[scanner.rs]")]
  node_iconcache[("Icon cache<br/>[windows_icons.rs]")]
  node_favorites[("Favorites<br/>[fav.rs]")]
end

subgraph group_windows["Windows integration"]
  node_hotkey["Global hotkey<br/>[hotkey.rs]"]
  node_tray["System tray<br/>[tray.rs]"]
  node_autostart["Startup setting<br/>[autostart.rs]"]
end

node_user(("User"))
node_browser["Default browser"]
node_startmenu["Start Menu"]
node_registry[("Uninstall registry")]
node_appprocess["Installed apps"]
node_windows["Windows"]

node_user -->|"presses toggle"| node_hotkey
node_main -->|"starts listener"| node_hotkey
node_hotkey -->|"signals toggle"| node_launcher
node_main -->|"starts tray"| node_tray
node_tray -->|"reads and toggles"| node_autostart
node_autostart -->|"configures startup"| node_windows
node_main -->|"opens window"| node_launcher
node_main -->|"initializes"| node_themes
node_themes -->|"loads"| node_themefiles
node_user -->|"types and confirms"| node_launcher
node_launcher -->|"requests app scan"| node_scanner
node_scanner -->|"reads shortcuts"| node_startmenu
node_scanner -->|"reads entries"| node_registry
node_scanner -->|"reads and writes"| node_scancache
node_scanner -->|"provides app items"| node_results
node_results -->|"indexes and filters"| node_search
node_launcher -->|"requests icons"| node_iconextract
node_iconextract -->|"reads and writes"| node_iconcache
node_iconextract -->|"extracts system icons"| node_windows
node_launcher -->|"updates icons"| node_results
node_user -->|"selects result"| node_results
node_launcher -->|"launches selected app"| node_appprocess
node_launcher -->|"parses bang query"| node_bangs
node_launcher -->|"opens search URL"| node_browser
node_launcher -->|"updates favorites"| node_favbar
node_favbar -->|"loads and saves"| node_favorites
node_user -->|"pins or launches"| node_favbar
node_favbar -->|"launches favorite"| node_appprocess
node_main -->|"guards single instance"| node_windows

click node_main "https://github.com/khaledtf19/popmax/blob/main/src/main.rs"
click node_launcher "https://github.com/khaledtf19/popmax/blob/main/src/launcher.rs"
click node_search "https://github.com/khaledtf19/popmax/blob/main/src/components/search.rs"
click node_results "https://github.com/khaledtf19/popmax/blob/main/src/components/list.rs"
click node_bangs "https://github.com/khaledtf19/popmax/blob/main/src/bangs.rs"
click node_themes "https://github.com/khaledtf19/popmax/blob/main/src/load_themes.rs"
click node_themefiles "https://github.com/khaledtf19/popmax/tree/main/src/themes"
click node_scanner "https://github.com/khaledtf19/popmax/blob/main/src/scanner.rs"
click node_scancache "https://github.com/khaledtf19/popmax/blob/main/src/scanner.rs"
click node_iconextract "https://github.com/khaledtf19/popmax/blob/main/src/windows_icons.rs"
click node_iconcache "https://github.com/khaledtf19/popmax/blob/main/src/windows_icons.rs"
click node_favorites "https://github.com/khaledtf19/popmax/blob/main/src/components/fav.rs"
click node_favbar "https://github.com/khaledtf19/popmax/blob/main/src/components/fav.rs"
click node_hotkey "https://github.com/khaledtf19/popmax/blob/main/src/hotkey.rs"
click node_tray "https://github.com/khaledtf19/popmax/blob/main/src/tray.rs"
click node_autostart "https://github.com/khaledtf19/popmax/blob/main/src/autostart.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_launcher,node_search,node_results,node_bangs,node_themes,node_themefiles,node_favbar,node_user,node_browser toneBlue
class node_scanner,node_iconextract,node_registry toneAmber
class node_scancache,node_iconcache,node_favorites toneMint
class node_hotkey,node_tray,node_autostart toneRose
class node_startmenu,node_appprocess,node_windows toneIndigo
```

## Components

### App experience

- [App startup](https://github.com/khaledtf19/popmax/blob/main/src/main.rs): `src/main.rs`
- [Launcher window](https://github.com/khaledtf19/popmax/blob/main/src/launcher.rs): `src/launcher.rs`
- [Fuzzy search](https://github.com/khaledtf19/popmax/blob/main/src/components/search.rs): `src/components/search.rs`
- [Results list](https://github.com/khaledtf19/popmax/blob/main/src/components/list.rs): `src/components/list.rs`
- [Bang shortcuts](https://github.com/khaledtf19/popmax/blob/main/src/bangs.rs): `src/bangs.rs`
- [Theme loader](https://github.com/khaledtf19/popmax/blob/main/src/load_themes.rs): `src/load_themes.rs`
- [Theme definitions](https://github.com/khaledtf19/popmax/tree/main/src/themes): `src/themes`
- [Favorites bar](https://github.com/khaledtf19/popmax/blob/main/src/components/fav.rs): `src/components/fav.rs`

### App catalog

- [App scanner](https://github.com/khaledtf19/popmax/blob/main/src/scanner.rs): `src/scanner.rs`
- [Icon extraction](https://github.com/khaledtf19/popmax/blob/main/src/windows_icons.rs): `src/windows_icons.rs`

### User state

- [Scan cache](https://github.com/khaledtf19/popmax/blob/main/src/scanner.rs): `src/scanner.rs`
- [Icon cache](https://github.com/khaledtf19/popmax/blob/main/src/windows_icons.rs): `src/windows_icons.rs`
- [Favorites](https://github.com/khaledtf19/popmax/blob/main/src/components/fav.rs): `src/components/fav.rs`

### Windows integration

- [Global hotkey](https://github.com/khaledtf19/popmax/blob/main/src/hotkey.rs): `src/hotkey.rs`
- [System tray](https://github.com/khaledtf19/popmax/blob/main/src/tray.rs): `src/tray.rs`
- [Startup setting](https://github.com/khaledtf19/popmax/blob/main/src/autostart.rs): `src/autostart.rs`

### Other components

- **User**
- **Default browser**
- **Start Menu**
- **Uninstall registry**
- **Installed apps**
- **Windows**

## Connections

- User → Global hotkey: presses toggle
- App startup → Global hotkey: starts listener
- Global hotkey → Launcher window: signals toggle
- App startup → System tray: starts tray
- System tray → Startup setting: reads and toggles
- Startup setting → Windows: configures startup
- App startup → Launcher window: opens window
- App startup → Theme loader: initializes
- Theme loader → Theme definitions: loads
- User → Launcher window: types and confirms
- Launcher window → App scanner: requests app scan
- App scanner → Start Menu: reads shortcuts
- App scanner → Uninstall registry: reads entries
- App scanner → Scan cache: reads and writes
- App scanner → Results list: provides app items
- Results list → Fuzzy search: indexes and filters
- Launcher window → Icon extraction: requests icons
- Icon extraction → Icon cache: reads and writes
- Icon extraction → Windows: extracts system icons
- Launcher window → Results list: updates icons
- User → Results list: selects result
- Launcher window → Installed apps: launches selected app
- Launcher window → Bang shortcuts: parses bang query
- Launcher window → Default browser: opens search URL
- Launcher window → Favorites bar: updates favorites
- Favorites bar → Favorites: loads and saves
- User → Favorites bar: pins or launches
- Favorites bar → Installed apps: launches favorite
- App startup → Windows: guards single instance