# pop-os/launcher architecture

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

- Interactive diagram: https://gitdiagram.com/pop-os/launcher
- Repository: https://github.com/pop-os/launcher

## Overview

Pop Launcher is a modular desktop-launcher service: a compatible frontend sends JSON IPC requests, the service dispatches searches and actions to on-demand plugins, and plugin responses become frontend results or launch actions. The graph preserves the documented plugin capabilities and the service’s result-prioritization and recent-use stages. Some plugin implementations and service wiring were not sampled; their nodes reflect the repository tree and README, and edges are limited to documented or indexed relationships.

Main entry points: [`service/src/plugins/mod.rs`](https://github.com/pop-os/launcher/blob/master/service/src/plugins/mod.rs) (Plugin registry), [`service/src/lib.rs`](https://github.com/pop-os/launcher/blob/master/service/src/lib.rs) (Request orchestration), [`src/codec.rs`](https://github.com/pop-os/launcher/blob/master/src/codec.rs) (JSON message types), [`service/src/client.rs`](https://github.com/pop-os/launcher/blob/master/service/src/client.rs) (IPC client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ipc["Frontend and IPC"]
  node_binary["Launcher process<br/>[main.rs]"]
  node_client["IPC client<br/>[client.rs]"]
end

subgraph group_service["Launcher service"]
  node_service_main["Request orchestration<br/>[lib.rs]"]
  node_plugin_registry["Plugin registry<br/>[mod.rs]"]
  node_priority["Result prioritization<br/>[priority.rs]"]
  node_recent[("Recent-use history<br/>[recent.rs]")]
end

subgraph group_plugins["Built-in plugins"]
  node_help_plugin["Help plugin<br/>[help.rs]"]
  node_calc["Calculator search<br/>[mod.rs]"]
  node_desktop_entries["Desktop applications<br/>[mod.rs]"]
  node_files["File search<br/>[mod.rs]"]
  node_find["Find search<br/>[mod.rs]"]
  node_shell_plugins["Shell integrations<br/>[mod.rs]"]
  node_cosmic["COSMIC windows<br/>[mod.rs]"]
  node_cosmic_handler["Window management"]
  node_pulse["Audio controls<br/>[mod.rs]"]
  node_recent_plugin["Recent items<br/>[mod.rs]"]
  node_scripts["User scripts<br/>[mod.rs]"]
  node_terminal["Terminal commands<br/>[mod.rs]"]
  node_web["Web searches<br/>[mod.rs]"]
  node_web_config["Web configuration<br/>[config.rs]"]
end

subgraph group_extensions["Plugin runtime"]
  node_external_plugin["External plugin process<br/>[mod.rs]"]
  node_plugin_config["Plugin configuration<br/>[config.rs]"]
  node_plugin_loader["Plugin discovery<br/>[load.rs]"]
end

subgraph group_shared["Shared interfaces"]
  node_codec["JSON message types<br/>[codec.rs]"]
  node_plugin_toolkit["Plugin toolkit<br/>[plugin_trait.rs]"]
  node_protocol["Protocol and config<br/>[lib.rs]"]
end

node_frontend(("Launcher frontend"))

node_frontend -->|"starts"| node_binary
node_frontend -->|"sends IPC"| node_binary
node_binary -.->|"runs service"| node_service_main
node_frontend -.->|"may use"| node_client
node_client -->|"spawns process"| node_binary
node_client -->|"encodes requests"| node_codec
node_service_main -->|"reads and writes"| node_codec
node_service_main -->|"dispatches to"| node_plugin_registry
node_service_main -->|"uses IPC"| node_client
node_service_main -->|"ranks results"| node_priority
node_service_main -->|"scores history"| node_recent
node_plugin_registry -->|"manages"| node_external_plugin
node_plugin_registry -.->|"registers"| node_help_plugin
node_plugin_registry -->|"uses config"| node_plugin_config
node_plugin_config -->|"configures discovery"| node_plugin_loader
node_plugin_registry -.->|"dispatches queries"| node_calc
node_plugin_registry -.->|"dispatches queries"| node_desktop_entries
node_plugin_registry -.->|"dispatches queries"| node_files
node_plugin_registry -.->|"dispatches queries"| node_find
node_plugin_registry -.->|"dispatches queries"| node_shell_plugins
node_plugin_registry -.->|"dispatches queries"| node_cosmic
node_cosmic -->|"uses handler"| node_cosmic_handler
node_plugin_registry -.->|"dispatches queries"| node_pulse
node_plugin_registry -.->|"dispatches queries"| node_recent_plugin
node_plugin_registry -.->|"dispatches queries"| node_scripts
node_plugin_registry -.->|"dispatches queries"| node_terminal
node_plugin_registry -.->|"dispatches queries"| node_web
node_web -->|"reads settings"| node_web_config
node_plugin_toolkit -->|"uses messages"| node_protocol
node_external_plugin -->|"exchanges JSON"| node_codec
node_desktop_entries -->|"returns launch actions"| node_codec
node_web -->|"returns search results"| node_codec
node_service_main -->|"returns results"| node_frontend

click node_binary "https://github.com/pop-os/launcher/blob/master/bin/src/main.rs"
click node_codec "https://github.com/pop-os/launcher/blob/master/src/codec.rs"
click node_client "https://github.com/pop-os/launcher/blob/master/service/src/client.rs"
click node_service_main "https://github.com/pop-os/launcher/blob/master/service/src/lib.rs"
click node_plugin_registry "https://github.com/pop-os/launcher/blob/master/service/src/plugins/mod.rs"
click node_external_plugin "https://github.com/pop-os/launcher/blob/master/service/src/plugins/external/mod.rs"
click node_plugin_config "https://github.com/pop-os/launcher/blob/master/service/src/plugins/config.rs"
click node_plugin_loader "https://github.com/pop-os/launcher/blob/master/service/src/plugins/external/load.rs"
click node_help_plugin "https://github.com/pop-os/launcher/blob/master/service/src/plugins/help.rs"
click node_priority "https://github.com/pop-os/launcher/blob/master/service/src/priority.rs"
click node_recent "https://github.com/pop-os/launcher/blob/master/service/src/recent.rs"
click node_calc "https://github.com/pop-os/launcher/blob/master/plugins/src/calc/mod.rs"
click node_desktop_entries "https://github.com/pop-os/launcher/blob/master/plugins/src/desktop_entries/mod.rs"
click node_files "https://github.com/pop-os/launcher/blob/master/plugins/src/files/mod.rs"
click node_find "https://github.com/pop-os/launcher/blob/master/plugins/src/find/mod.rs"
click node_shell_plugins "https://github.com/pop-os/launcher/blob/master/plugins/src/pop_shell/mod.rs"
click node_cosmic "https://github.com/pop-os/launcher/blob/master/plugins/src/cosmic_toplevel/mod.rs"
click node_cosmic_handler "https://github.com/pop-os/launcher/blob/master/plugins/src/cosmic_toplevel/toplevel_handler.rs"
click node_pulse "https://github.com/pop-os/launcher/blob/master/plugins/src/pulse/mod.rs"
click node_recent_plugin "https://github.com/pop-os/launcher/blob/master/plugins/src/recent/mod.rs"
click node_scripts "https://github.com/pop-os/launcher/blob/master/plugins/src/scripts/mod.rs"
click node_terminal "https://github.com/pop-os/launcher/blob/master/plugins/src/terminal/mod.rs"
click node_web "https://github.com/pop-os/launcher/blob/master/plugins/src/web/mod.rs"
click node_web_config "https://github.com/pop-os/launcher/blob/master/plugins/src/web/config.rs"
click node_plugin_toolkit "https://github.com/pop-os/launcher/blob/master/toolkit/src/plugin_trait.rs"
click node_protocol "https://github.com/pop-os/launcher/blob/master/src/lib.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_binary,node_client,node_frontend toneBlue
class node_service_main,node_plugin_registry,node_priority,node_recent toneAmber
class node_help_plugin,node_calc,node_desktop_entries,node_files,node_find,node_shell_plugins,node_cosmic,node_cosmic_handler,node_pulse,node_recent_plugin,node_scripts,node_terminal,node_web,node_web_config toneMint
class node_external_plugin,node_plugin_config,node_plugin_loader toneRose
class node_codec,node_plugin_toolkit,node_protocol toneIndigo
```

## Components

### Frontend and IPC

- [Launcher process](https://github.com/pop-os/launcher/blob/master/bin/src/main.rs): `bin/src/main.rs`
- [IPC client](https://github.com/pop-os/launcher/blob/master/service/src/client.rs): `service/src/client.rs`

### Launcher service

- [Request orchestration](https://github.com/pop-os/launcher/blob/master/service/src/lib.rs): `service/src/lib.rs`
- [Plugin registry](https://github.com/pop-os/launcher/blob/master/service/src/plugins/mod.rs): `service/src/plugins/mod.rs`
- [Result prioritization](https://github.com/pop-os/launcher/blob/master/service/src/priority.rs): `service/src/priority.rs`
- [Recent-use history](https://github.com/pop-os/launcher/blob/master/service/src/recent.rs): `service/src/recent.rs`

### Built-in plugins

- [Help plugin](https://github.com/pop-os/launcher/blob/master/service/src/plugins/help.rs): `service/src/plugins/help.rs`
- [Calculator search](https://github.com/pop-os/launcher/blob/master/plugins/src/calc/mod.rs): `plugins/src/calc/mod.rs`
- [Desktop applications](https://github.com/pop-os/launcher/blob/master/plugins/src/desktop_entries/mod.rs): `plugins/src/desktop_entries/mod.rs`
- [File search](https://github.com/pop-os/launcher/blob/master/plugins/src/files/mod.rs): `plugins/src/files/mod.rs`
- [Find search](https://github.com/pop-os/launcher/blob/master/plugins/src/find/mod.rs): `plugins/src/find/mod.rs`
- [Shell integrations](https://github.com/pop-os/launcher/blob/master/plugins/src/pop_shell/mod.rs): `plugins/src/pop_shell/mod.rs`
- [COSMIC windows](https://github.com/pop-os/launcher/blob/master/plugins/src/cosmic_toplevel/mod.rs): `plugins/src/cosmic_toplevel/mod.rs`
- [Window management](https://github.com/pop-os/launcher/blob/master/plugins/src/cosmic_toplevel/toplevel_handler.rs): `plugins/src/cosmic_toplevel/toplevel_handler.rs`
- [Audio controls](https://github.com/pop-os/launcher/blob/master/plugins/src/pulse/mod.rs): `plugins/src/pulse/mod.rs`
- [Recent items](https://github.com/pop-os/launcher/blob/master/plugins/src/recent/mod.rs): `plugins/src/recent/mod.rs`
- [User scripts](https://github.com/pop-os/launcher/blob/master/plugins/src/scripts/mod.rs): `plugins/src/scripts/mod.rs`
- [Terminal commands](https://github.com/pop-os/launcher/blob/master/plugins/src/terminal/mod.rs): `plugins/src/terminal/mod.rs`
- [Web searches](https://github.com/pop-os/launcher/blob/master/plugins/src/web/mod.rs): `plugins/src/web/mod.rs`
- [Web configuration](https://github.com/pop-os/launcher/blob/master/plugins/src/web/config.rs): `plugins/src/web/config.rs`

### Plugin runtime

- [External plugin process](https://github.com/pop-os/launcher/blob/master/service/src/plugins/external/mod.rs): `service/src/plugins/external/mod.rs`
- [Plugin configuration](https://github.com/pop-os/launcher/blob/master/service/src/plugins/config.rs): `service/src/plugins/config.rs`
- [Plugin discovery](https://github.com/pop-os/launcher/blob/master/service/src/plugins/external/load.rs): `service/src/plugins/external/load.rs`

### Shared interfaces

- [JSON message types](https://github.com/pop-os/launcher/blob/master/src/codec.rs): `src/codec.rs`
- [Plugin toolkit](https://github.com/pop-os/launcher/blob/master/toolkit/src/plugin_trait.rs): `toolkit/src/plugin_trait.rs`
- [Protocol and config](https://github.com/pop-os/launcher/blob/master/src/lib.rs): `src/lib.rs`

### Other components

- **Launcher frontend**

## Connections

- Launcher frontend → Launcher process: starts (evidence: `README.md`)
- Launcher frontend → Launcher process: sends IPC (evidence: `README.md`)
- Launcher process → Request orchestration: runs service
- Launcher frontend → IPC client: may use
- IPC client → Launcher process: spawns process (evidence: `service/src/client.rs`)
- IPC client → JSON message types: encodes requests (evidence: `service/src/client.rs`)
- Request orchestration → JSON message types: reads and writes (evidence: `README.md`)
- Request orchestration → Plugin registry: dispatches to (evidence: `service/src/lib.rs`)
- Request orchestration → IPC client: uses IPC (evidence: `service/src/lib.rs`)
- Request orchestration → Result prioritization: ranks results (evidence: `service/src/lib.rs`)
- Request orchestration → Recent-use history: scores history (evidence: `service/src/lib.rs`)
- Plugin registry → External plugin process: manages (evidence: `service/src/plugins/mod.rs`)
- Plugin registry → Help plugin: registers (evidence: `service/src/plugins/mod.rs`)
- Plugin registry → Plugin configuration: uses config (evidence: `service/src/plugins/mod.rs`)
- Plugin configuration → Plugin discovery: configures discovery (evidence: `service/src/plugins/external/load.rs`)
- Plugin registry → Calculator search: dispatches queries
- Plugin registry → Desktop applications: dispatches queries
- Plugin registry → File search: dispatches queries
- Plugin registry → Find search: dispatches queries
- Plugin registry → Shell integrations: dispatches queries
- Plugin registry → COSMIC windows: dispatches queries
- COSMIC windows → Window management: uses handler (evidence: `plugins/src/cosmic_toplevel/mod.rs`)
- Plugin registry → Audio controls: dispatches queries
- Plugin registry → Recent items: dispatches queries
- Plugin registry → User scripts: dispatches queries
- Plugin registry → Terminal commands: dispatches queries
- Plugin registry → Web searches: dispatches queries
- Web searches → Web configuration: reads settings (evidence: `plugins/src/web/mod.rs`)
- Plugin toolkit → Protocol and config: uses messages (evidence: `toolkit/src/plugin_trait.rs`)
- External plugin process → JSON message types: exchanges JSON (evidence: `service/src/plugins/external/mod.rs`)
- Desktop applications → JSON message types: returns launch actions (evidence: `plugins/src/desktop_entries/mod.rs`)
- Web searches → JSON message types: returns search results (evidence: `plugins/src/web/mod.rs`)
- Request orchestration → Launcher frontend: returns results (evidence: `README.md`)