# caelestia-dots/shell architecture

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

- Interactive diagram: https://gitdiagram.com/caelestia-dots/shell
- Repository: https://github.com/caelestia-dots/shell

## Overview

#### Purpose and startup

Caelestia Shell is a Linux desktop shell implemented in QML for Quickshell and designed around the Hyprland compositor. The Quickshell configuration entry point is `shell.qml`; it composes persistent shell surfaces, services, and interaction modules. Users start it through the external `caelestia` CLI or Quickshell (`qs -c caelestia`).

Core build/install integration is CMake-based: `CMakeLists.txt` builds the native QML plugin and installs the QML configuration; Nix and Home Manager packaging live in `flake.nix` and `nix/hm-module.nix`.

#### Root composition, state, and shared UI

`shell.qml` is the root coordinator. It loads shared services and feature modules; module wrappers own their windows/surfaces and expose open/close state.

Shared QML primitives separate visual consistency from feature logic:
- `components/ScreenState.qml` and `components/StateLayer.qml` support per-screen/stateful composition.
- `components/containers/StyledWindow.qml` provides common window behavior.
- `components/Anim.qml` and `components/StyledText.qml` centralize animated Material-style presentation.

`services/ShellState.qml` is the likely cross-module shell-state boundary, while `modules/Shortcuts.qml` maps Hyprland global-shortcut/IPC-triggered actions into shell behavior.

#### Configuration and native QML API

The C++ plugin is the bridge between declarative QML and system/native capabilities. Its module root is `plugin/src/Caelestia/CMakeLists.txt`; domain APIs are exposed from submodules.

Configuration is typed and layered rather than read ad hoc by UI:
- `plugin/src/Caelestia/Config/rootnodes.cpp`
- `plugin/src/Caelestia/Config/configattached.cpp`
- `plugin/src/Caelestia/Settings/settingsfile.cpp`

It models defaults plus user files at `~/.config/caelestia/shell.json`, token overrides, and monitor-specific overrides. QML should consume attached config/tokens APIs, preserving this boundary between persisted settings and rendering.

#### System-service integration

QML service facades orchestrate desktop integrations, while native services gather lower-level data:
- `services/Hypr.qml`, `services/Audio.qml`, `services/Nmcli.qml`
- `plugin/src/Caelestia/Services/service.cpp`
- `plugin/src/Caelestia/Services/audioprovider.cpp`
- `plugin/src/Caelestia/Services/hyprdevices.cpp`

Material dependencies include Hyprland, NetworkManager/nmcli, PipeWire, brightnessctl/DDC, lm_sensors, power-profiles-daemon, libcava, aubio, and libqalculate. Notifications, media players, wallpapers, weather, idle inhibition, recording, and display state are represented by QML services under `services/`.

#### Desktop surfaces and interactive modules

The main desktop-facing surfaces are independently wrapped modules:
- Background/wallpaper/visualizer: `modules/background/Background.qml`, `modules/background/Wallpaper.qml`
- Top bar and contextual popouts: `modules/bar/BarWrapper.qml`, `modules/bar/popouts/Wrapper.qml`
- Dashboard: `modules/dashboard/Wrapper.qml`, `modules/dashboard/Content.qml`
- Launcher: `modules/launcher/Wrapper.qml`, `modules/launcher/services/Apps.qml`
- Settings (“Nexus”): `modules/nexus/Nexus.qml`, `modules/nexus/PageRegistry.qml`
- Notifications/sidebar/OSD: `modules/notifications/Wrapper.qml`, `modules/sidebar/Wrapper.qml`, `modules/osd/Wrapper.qml`

Control flow is event-driven: shortcuts, compositor/system-service updates, and user actions mutate service/state objects; wrappers reactively show surfaces; content components bind to configuration and service models.

#### Security and session boundaries

Locking and session controls are isolated:
- `modules/lock/Lock.qml`
- `modules/lock/Pam.qml`
- `modules/session/Wrapper.qml`

PAM integration is supported by installed service definitions in `assets/pam.d/fprint` and `assets/pam.d/howdy`, enabling password, fingerprint, and Howdy authentication paths. Session actions invoke configured logout, poweroff, reboot, or hibernate commands; these are a privileged external-command boundary.

#### Data-heavy capabilities

Native models/providers avoid putting filesystem, image, sensor, and media processing in QML:
- App/file discovery: `plugin/src/Caelestia/Models/appdb.cpp`, `plugin/src/Caelestia/Models/filesystemmodel.cpp`
- Image cache/analysis: `plugin/src/Caelestia/Images/imagecacher.cpp`, `plugin/src/Caelestia/Images/imageanalyser.cpp`
- Metrics/audio/lyrics: `plugin/src/Caelestia/Services/cpu.cpp`, `plugin/src/Caelestia/Services/lyrics.cpp`, `plugin/src/Caelestia/Services/cavaprovider.cpp`

These feed launcher results, wallpaper/file dialogs, dashboard performance cards, media visualization, and lock/dashboard media displays without coupling those UIs directly to OS APIs.

Main entry points: [`shell.qml`](https://github.com/caelestia-dots/shell/blob/main/shell.qml) (Shell root), [`plugin/src/Caelestia/CMakeLists.txt`](https://github.com/caelestia-dots/shell/blob/main/plugin/src/Caelestia/CMakeLists.txt) (Caelestia plugin), [`modules/bar/BarWrapper.qml`](https://github.com/caelestia-dots/shell/blob/main/modules/bar/BarWrapper.qml) (Desktop surfaces), [`plugin/src/Caelestia/Models/appdb.cpp`](https://github.com/caelestia-dots/shell/blob/main/plugin/src/Caelestia/Models/appdb.cpp) (Native data models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_qml["QML Shell"]
  node_shell["Shell root<br/>QML coordinator<br/>[shell.qml]"]
  node_shellstate["Shell state<br/>shared state<br/>[ShellState.qml]"]
  node_primitives["Shared UI primitives<br/>QML components<br/>[ScreenState.qml]"]
  node_shortcuts["Shortcuts<br/>action router<br/>[Shortcuts.qml]"]
  node_qmlservices["QML service facades<br/>QML services<br/>[Hypr.qml]"]
  node_surfaces["Desktop surfaces<br/>QML modules<br/>[BarWrapper.qml]"]
  node_launcher["Launcher<br/>QML module<br/>[Wrapper.qml]"]
  node_nexus["Nexus settings<br/>QML module<br/>[Nexus.qml]"]
  node_lock["Lock screen<br/>security module<br/>[Lock.qml]"]
  node_session["Session controls<br/>QML module<br/>[Wrapper.qml]"]
end

subgraph group_native["Native QML Plugin"]
  node_plugin{{"Caelestia plugin<br/>C++ QML plugin<br/>[CMakeLists.txt]"}}
  node_config["Typed configuration<br/>native config API<br/>[rootnodes.cpp]"]
  node_native_services["Native system services<br/>providers<br/>[service.cpp]"]
  node_native_models["Native data models<br/>models/providers<br/>[appdb.cpp]"]
end

subgraph group_external["System Boundaries"]
  node_user_config["User settings files<br/>persisted config"]
  node_hyprland["Hyprland compositor<br/>external compositor"]
  node_desktop_services["Desktop service stack<br/>external services"]
  node_pam["PAM authentication<br/>authentication boundary<br/>[fprint]"]
  node_privileged_commands["Session commands<br/>privileged boundary"]
end

node_build["Build &amp; packaging<br/>CMake/Nix<br/>[CMakeLists.txt]"]

node_build -->|"builds"| node_plugin
node_build -->|"installs"| node_shell
node_shell -->|"loads"| node_shellstate
node_shell -->|"uses"| node_primitives
node_shell -->|"loads"| node_shortcuts
node_shell -->|"loads"| node_qmlservices
node_shell -->|"composes"| node_surfaces
node_shell -->|"composes"| node_launcher
node_shell -->|"composes"| node_nexus
node_shell -->|"composes"| node_lock
node_shell -->|"composes"| node_session
node_shortcuts -->|"mutates"| node_shellstate
node_hyprland -->|"triggers"| node_shortcuts
node_hyprland -->|"IPC updates"| node_qmlservices
node_qmlservices -->|"uses native API"| node_plugin
node_plugin -->|"exposes"| node_config
node_plugin -->|"exposes"| node_native_services
node_plugin -->|"exposes"| node_native_models
node_user_config -->|"layers into"| node_config
node_desktop_services -->|"system data"| node_native_services
node_config -->|"tokens and settings"| node_surfaces
node_native_services -->|"reactive models"| node_surfaces
node_native_models -->|"app results"| node_launcher
node_native_models -->|"media and metrics"| node_surfaces
node_lock -->|"authenticates via"| node_pam
node_session -->|"invokes"| node_privileged_commands

click node_build "https://github.com/caelestia-dots/shell/blob/main/CMakeLists.txt"
click node_shell "https://github.com/caelestia-dots/shell/blob/main/shell.qml"
click node_shellstate "https://github.com/caelestia-dots/shell/blob/main/services/ShellState.qml"
click node_primitives "https://github.com/caelestia-dots/shell/blob/main/components/ScreenState.qml"
click node_shortcuts "https://github.com/caelestia-dots/shell/blob/main/modules/Shortcuts.qml"
click node_qmlservices "https://github.com/caelestia-dots/shell/blob/main/services/Hypr.qml"
click node_surfaces "https://github.com/caelestia-dots/shell/blob/main/modules/bar/BarWrapper.qml"
click node_launcher "https://github.com/caelestia-dots/shell/blob/main/modules/launcher/Wrapper.qml"
click node_nexus "https://github.com/caelestia-dots/shell/blob/main/modules/nexus/Nexus.qml"
click node_lock "https://github.com/caelestia-dots/shell/blob/main/modules/lock/Lock.qml"
click node_session "https://github.com/caelestia-dots/shell/blob/main/modules/session/Wrapper.qml"
click node_plugin "https://github.com/caelestia-dots/shell/blob/main/plugin/src/Caelestia/CMakeLists.txt"
click node_config "https://github.com/caelestia-dots/shell/blob/main/plugin/src/Caelestia/Config/rootnodes.cpp"
click node_native_services "https://github.com/caelestia-dots/shell/blob/main/plugin/src/Caelestia/Services/service.cpp"
click node_native_models "https://github.com/caelestia-dots/shell/blob/main/plugin/src/Caelestia/Models/appdb.cpp"
click node_pam "https://github.com/caelestia-dots/shell/blob/main/assets/pam.d/fprint"

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_shell,node_shellstate,node_primitives,node_shortcuts,node_qmlservices,node_surfaces,node_launcher,node_nexus,node_lock,node_session toneBlue
class node_plugin,node_config,node_native_services,node_native_models toneAmber
class node_user_config,node_hyprland,node_desktop_services,node_pam,node_privileged_commands toneMint
class node_build toneNeutral
```

## Components

### QML Shell

Quickshell composition and desktop surfaces.

- [Shell root](https://github.com/caelestia-dots/shell/blob/main/shell.qml): QML coordinator · Composes persistent services and feature modules. · `shell.qml`
- [Shell state](https://github.com/caelestia-dots/shell/blob/main/services/ShellState.qml): shared state · Cross-module state boundary. · `services/ShellState.qml`
- [Shared UI primitives](https://github.com/caelestia-dots/shell/blob/main/components/ScreenState.qml): QML components · Per-screen state, window behavior, animation, and text styling. · `components/ScreenState.qml`
- [Shortcuts](https://github.com/caelestia-dots/shell/blob/main/modules/Shortcuts.qml): action router · Maps Hyprland-triggered actions into shell behavior. · `modules/Shortcuts.qml`
- [QML service facades](https://github.com/caelestia-dots/shell/blob/main/services/Hypr.qml): QML services · Reactive desktop-integration facades for Hyprland, audio, and network. · `services/Hypr.qml`
- [Desktop surfaces](https://github.com/caelestia-dots/shell/blob/main/modules/bar/BarWrapper.qml): QML modules · Background, bar/popouts, dashboard, notifications, sidebar, and OSD. · `modules/bar/BarWrapper.qml`
- [Launcher](https://github.com/caelestia-dots/shell/blob/main/modules/launcher/Wrapper.qml): QML module · Shows application discovery results. · `modules/launcher/Wrapper.qml`
- [Nexus settings](https://github.com/caelestia-dots/shell/blob/main/modules/nexus/Nexus.qml): QML module · Settings UI driven by a page registry. · `modules/nexus/Nexus.qml`
- [Lock screen](https://github.com/caelestia-dots/shell/blob/main/modules/lock/Lock.qml): security module · Isolated authentication surface. · `modules/lock/Lock.qml`
- [Session controls](https://github.com/caelestia-dots/shell/blob/main/modules/session/Wrapper.qml): QML module · Issues configured logout and power commands. · `modules/session/Wrapper.qml`

### Native QML Plugin

C++ APIs, models, and system providers.

- [Caelestia plugin](https://github.com/caelestia-dots/shell/blob/main/plugin/src/Caelestia/CMakeLists.txt): C++ QML plugin · Declarative bridge to native capabilities. · `plugin/src/Caelestia/CMakeLists.txt`
- [Typed configuration](https://github.com/caelestia-dots/shell/blob/main/plugin/src/Caelestia/Config/rootnodes.cpp): native config API · Layers defaults, user settings, tokens, and monitor overrides. · `plugin/src/Caelestia/Config/rootnodes.cpp`
- [Native system services](https://github.com/caelestia-dots/shell/blob/main/plugin/src/Caelestia/Services/service.cpp): providers · Provides low-level audio, Hyprland, and desktop data. · `plugin/src/Caelestia/Services/service.cpp`
- [Native data models](https://github.com/caelestia-dots/shell/blob/main/plugin/src/Caelestia/Models/appdb.cpp): models/providers · Handles app/files, images, metrics, lyrics, and visualization data. · `plugin/src/Caelestia/Models/appdb.cpp`

### System Boundaries

Compositor, desktop services, and privileged session controls.

- **User settings files**: persisted config · shell.json plus token and monitor-specific overrides.
- **Hyprland compositor**: external compositor · Supplies IPC, global shortcuts, and display context.
- **Desktop service stack**: external services · Network, PipeWire, sensors, brightness, media, and related system tools.
- [PAM authentication](https://github.com/caelestia-dots/shell/blob/main/assets/pam.d/fprint): authentication boundary · Supports password, fingerprint, and Howdy paths. · `assets/pam.d/fprint`
- **Session commands**: privileged boundary · Logout, poweroff, reboot, and hibernate commands.

### Other components

- [Build & packaging](https://github.com/caelestia-dots/shell/blob/main/CMakeLists.txt): CMake/Nix · Builds the plugin and installs the shell configuration. · `CMakeLists.txt`

## Connections

- Build & packaging → Caelestia plugin: builds
- Build & packaging → Shell root: installs
- Shell root → Shell state: loads
- Shell root → Shared UI primitives: uses
- Shell root → Shortcuts: loads
- Shell root → QML service facades: loads
- Shell root → Desktop surfaces: composes
- Shell root → Launcher: composes
- Shell root → Nexus settings: composes
- Shell root → Lock screen: composes
- Shell root → Session controls: composes
- Shortcuts → Shell state: mutates
- Hyprland compositor → Shortcuts: triggers
- Hyprland compositor → QML service facades: IPC updates
- QML service facades → Caelestia plugin: uses native API
- Caelestia plugin → Typed configuration: exposes
- Caelestia plugin → Native system services: exposes
- Caelestia plugin → Native data models: exposes
- User settings files → Typed configuration: layers into
- Desktop service stack → Native system services: system data
- Typed configuration → Desktop surfaces: tokens and settings
- Native system services → Desktop surfaces: reactive models
- Native data models → Launcher: app results
- Native data models → Desktop surfaces: media and metrics
- Lock screen → PAM authentication: authenticates via
- Session controls → Session commands: invokes
