# mannuvilasara/xenon-shell architecture

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

- Interactive diagram: https://gitdiagram.com/mannuvilasara/xenon-shell
- Repository: https://github.com/mannuvilasara/xenon-shell

## Overview

1. **Overall shape**
   - This is a **QuickShell/QML desktop shell** for Linux, not a traditional app.
   - The root entrypoint is `shell.qml`, which likely composes the full desktop experience by loading the major modules: background, bar, lock screen, panels, launcher, notifications, settings, overlays, and screen corners.

2. **Layering**
   - The repo is organized into three main layers:
     - `Core/` for shared application state, configuration, colors, icons, logging, IPC, and utility plumbing.
     - `Services/` for live system data and control surfaces.
     - `Modules/` and `Widgets/` for the actual UI surfaces and reusable components.
   - `Assets/` contains theme templates and static resources used by the shell.

3. **Core as the shared backbone**
   - `Core/Context.qml`, `GlobalState.qml`, and `Config.qml` appear to define the shared runtime context and user/config state.
   - `Core/Colors.qml`, `Icons.qml`, `SvgIcons.qml`, and `Animations.qml` centralize look-and-feel so the UI stays consistent across modules.
   - `Core/Ipc.qml` is the bridge for external control via `qs ipc`, and `Core/Logger.qml` plus `NotificationManager.qml` provide cross-cutting runtime services.

4. **Services as the data plane**
   - `Services/` contains the live system adapters: battery, brightness, volume, network, Bluetooth, disk, memory, CPU, time, timezone, weather, distro/system info, wallpaper, MPRIS media, and CAVA audio visualization.
   - These are the sources of truth for the UI; widgets and panels bind to them to display status and to trigger actions.
   - `Services/Compositor/Compositor.qml` suggests shell/compositor-specific integration that sits below the UI features.

5. **Primary desktop surfaces**
   - `Modules/Bar/` implements the top/bottom status bar and its widgets: workspaces, tray, clock, media, battery, network, volume, power, and Arch logo.
   - `Modules/Background/` handles wallpaper rendering and desktop background presentation.
   - `Modules/Corners/` draws rounded screen corners as a visual shell layer.
   - `Modules/Overlays/Overlays.qml` likely stacks transient overlay UI above the desktop.

6. **User interaction panels**
   - `Modules/Panels/` contains the slide-out or popover-style surfaces:
     - `InfoPanel.qml` for system/info content,
     - `SidePanel.qml` for controls and status,
     - `PowerMenu.qml` for shutdown/reboot/logout actions,
     - `WallpaperPanel.qml` for wallpaper selection.
   - The `Modules/Panels/Views/` subtree breaks these panels into functional views such as calendar, weather, music, system, home, Bluetooth, Wi‑Fi, sliders, toggles, and notification content.

7. **Launchers, clipboard, notifications, and settings**
   - `Modules/Launcher/AppLauncher.qml` provides app launching.
   - `Modules/Clipboard/Clipboard.qml` exposes clipboard history or clipboard UI.
   - `Modules/Notifications/` renders toast notifications and notification views.
   - `Modules/Settings/SettingsWindow.qml` is the configuration UI, with pages for general settings, interface, bar, background, lock screen, services, updates, and about.

8. **Lock screen subsystem**
   - `Modules/Lock/` is a self-contained lock screen stack with:
     - the lock screen itself,
     - authentication via `PamAuth.qml`,
     - multiple “card” components for clock, music, notifications, password, profile, quotes, system info/stats, and weather,
     - alternate lock screen views such as default and music-focused layouts.
   - This is one of the more complex subsystems and likely consumes many `Services/` providers plus global state.

9. **Reusable UI components**
   - `Widgets/` and `Modules/*/Components` contain shared presentational primitives like sliders, toggles, tray menus, dividers, progress rings, bento cards, and notification items.
   - These components are reused across bar, panels, lock screen, and settings to keep behavior and styling consistent.

10. **Theming and assets pipeline**
   - `Assets/Templates/xenon_colors.json` and `Scripts/template-processor.py` suggest a template-driven theme generation flow.
   - `Scripts/generate_previews.py` and the Python library under `Scripts/lib/` handle color extraction, palette generation, rendering, and preview creation.
   - `imagemagick` is required because wallpaper thumbnails/previews are generated outside the QML runtime.

11. **External interaction model**
   - The shell is controlled both internally and externally through **QuickShell IPC**; the README lists commands to toggle launcher, clipboard, panels, settings, wallpaper selection, and locking.
   - That means the architecture has a command surface separate from the visual surface: external scripts or tools can open/close UI modules or set wallpaper.

12. **Typical data flow**
   - Live system state enters through `Services/*` and is exposed to QML bindings.
   - Shared state and theme values come through `Core/*`.
   - UI surfaces in `Modules/*` and `Widgets/*` bind to those services/state and emit user actions.
   - Actions flow back through service adapters or IPC to change system state, update wallpaper, control media/audio, or lock the session.

13. **How to draw the diagram**
   - Place `shell.qml` at the top as the composition root.
   - Under it, draw three major boxes: `Core`, `Services`, and `Modules/Widgets`.
   - Show `Services` feeding data into the UI modules, and `Core/Ipc` providing an external command path into module-level toggles and actions.
   - Add a separate tooling box for `Scripts` and `Assets` because they shape theme generation and preview artifacts rather than the runtime UI itself.

Main entry points: [`shell.qml`](https://github.com/mannuvilasara/xenon-shell/blob/main/shell.qml) (shell.qml), [`Core/Ipc.qml`](https://github.com/mannuvilasara/xenon-shell/blob/main/Core/Ipc.qml) (IPC), [`Services/OsService.qml`](https://github.com/mannuvilasara/xenon-shell/blob/main/Services/OsService.qml) (Services), [`Widgets/Icon.qml`](https://github.com/mannuvilasara/xenon-shell/blob/main/Widgets/Icon.qml) (Widgets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_shell["shell.qml<br/>composition root<br/>[shell.qml]"]
  node_core_context["Core<br/>shared runtime<br/>[Context.qml]"]
  node_core_ipc["IPC<br/>command bridge<br/>[Ipc.qml]"]
  node_core_theme["Theme<br/>look & feel<br/>[Colors.qml]"]
  node_services_base[("Services<br/>system data<br/>[OsService.qml]")]
  node_services_compositor["Compositor<br/>shell integration<br/>[Compositor.qml]"]
end

subgraph group_ui["UI"]
  node_background["Background<br/>desktop surface<br/>[Background.qml]"]
  node_bar["Bar<br/>[Bar.qml]"]
  node_launcher["Launcher<br/>[AppLauncher.qml]"]
  node_lock["Lock Screen<br/>auth surface<br/>[Lock.qml]"]
  node_panels["Panels<br/>[SidePanel.qml]"]
  node_notifications["Notifications<br/>toast center"]
  node_settings["Settings<br/>preferences UI<br/>[SettingsWindow.qml]"]
  node_overlays["Overlays<br/>overlay stack<br/>[Overlays.qml]"]
  node_corners["Corners<br/>chrome layer<br/>[ScreenCorners.qml]"]
  node_widgets["Widgets<br/>shared components<br/>[Icon.qml]"]
end

subgraph group_tooling["Tooling"]
  node_assets["Assets<br/>[xenon_colors.json]"]
  node_scripts["Scripts<br/>theme tooling"]
end

node_shell -->|"shared state"| node_core_context
node_shell -->|"binds"| node_services_base
node_shell -->|"loads"| node_background
node_shell -->|"loads"| node_bar
node_shell -->|"loads"| node_launcher
node_shell -->|"loads"| node_lock
node_shell -->|"loads"| node_panels
node_shell -->|"loads"| node_notifications
node_shell -->|"loads"| node_settings
node_shell -->|"loads"| node_overlays
node_core_context -->|"exposes"| node_core_ipc
node_core_context -->|"shares theme"| node_core_theme
node_services_base -->|"feeds status"| node_bar
node_services_base -->|"feeds controls"| node_panels
node_services_base -->|"feeds lock"| node_lock
node_services_base -->|"feeds events"| node_notifications
node_services_compositor -->|"integrates"| node_shell
node_widgets -->|"reused by"| node_bar
node_widgets -->|"reused by"| node_panels
node_widgets -->|"reused by"| node_lock
node_widgets -->|"reused by"| node_settings
node_assets -->|"templates"| node_scripts
node_scripts -->|"generates"| node_core_theme
node_core_ipc -->|"toggles"| node_launcher
node_core_ipc -->|"toggles"| node_panels
node_core_ipc -->|"toggles"| node_settings
node_core_ipc -->|"locks"| node_lock

click node_shell "https://github.com/mannuvilasara/xenon-shell/blob/main/shell.qml"
click node_core_context "https://github.com/mannuvilasara/xenon-shell/blob/main/Core/Context.qml"
click node_core_ipc "https://github.com/mannuvilasara/xenon-shell/blob/main/Core/Ipc.qml"
click node_core_theme "https://github.com/mannuvilasara/xenon-shell/blob/main/Core/Colors.qml"
click node_services_base "https://github.com/mannuvilasara/xenon-shell/blob/main/Services/OsService.qml"
click node_services_compositor "https://github.com/mannuvilasara/xenon-shell/blob/main/Services/Compositor/Compositor.qml"
click node_background "https://github.com/mannuvilasara/xenon-shell/blob/main/Modules/Background/Background.qml"
click node_bar "https://github.com/mannuvilasara/xenon-shell/blob/main/Modules/Bar/Bar.qml"
click node_launcher "https://github.com/mannuvilasara/xenon-shell/blob/main/Modules/Launcher/AppLauncher.qml"
click node_lock "https://github.com/mannuvilasara/xenon-shell/blob/main/Modules/Lock/Lock.qml"
click node_panels "https://github.com/mannuvilasara/xenon-shell/blob/main/Modules/Panels/SidePanel.qml"
click node_notifications "https://github.com/mannuvilasara/xenon-shell/blob/main/Modules/Notifications/NotificationToast.qml"
click node_settings "https://github.com/mannuvilasara/xenon-shell/blob/main/Modules/Settings/SettingsWindow.qml"
click node_overlays "https://github.com/mannuvilasara/xenon-shell/blob/main/Modules/Overlays/Overlays.qml"
click node_corners "https://github.com/mannuvilasara/xenon-shell/blob/main/Modules/Corners/ScreenCorners.qml"
click node_widgets "https://github.com/mannuvilasara/xenon-shell/blob/main/Widgets/Icon.qml"
click node_assets "https://github.com/mannuvilasara/xenon-shell/blob/main/Assets/Templates/xenon_colors.json"
click node_scripts "https://github.com/mannuvilasara/xenon-shell/blob/main/Scripts/template-processor.py"

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_core_context,node_core_ipc,node_core_theme,node_services_base,node_services_compositor toneBlue
class node_background,node_bar,node_launcher,node_lock,node_panels,node_notifications,node_settings,node_overlays,node_corners,node_widgets toneAmber
class node_assets,node_scripts toneMint
```

## Components

### Runtime

Composition root, shared state, services, and UI surfaces.

- [shell.qml](https://github.com/mannuvilasara/xenon-shell/blob/main/shell.qml): composition root · Top-level shell composition that assembles the desktop experience. · `shell.qml`
- [Core](https://github.com/mannuvilasara/xenon-shell/blob/main/Core/Context.qml): shared runtime · Shared context, config, state, logging, icons, animations, and IPC. · `Core/Context.qml`
- [IPC](https://github.com/mannuvilasara/xenon-shell/blob/main/Core/Ipc.qml): command bridge · External control surface for opening modules and triggering shell actions. · `Core/Ipc.qml`
- [Theme](https://github.com/mannuvilasara/xenon-shell/blob/main/Core/Colors.qml): look & feel · Centralized colors, icons, SVGs, and animation primitives. · `Core/Colors.qml`
- [Services](https://github.com/mannuvilasara/xenon-shell/blob/main/Services/OsService.qml): system data · Live adapters for battery, audio, network, media, wallpaper, time, and system info. · `Services/OsService.qml`
- [Compositor](https://github.com/mannuvilasara/xenon-shell/blob/main/Services/Compositor/Compositor.qml): shell integration · Compositor-specific integration layer under services. · `Services/Compositor/Compositor.qml`

### UI

Desktop shell modules and reusable widgets.

- [Background](https://github.com/mannuvilasara/xenon-shell/blob/main/Modules/Background/Background.qml): desktop surface · Wallpaper and background presentation. · `Modules/Background/Background.qml`
- [Bar](https://github.com/mannuvilasara/xenon-shell/blob/main/Modules/Bar/Bar.qml): status bar · Top-level shell bar and its window container. · `Modules/Bar/Bar.qml`
- [Launcher](https://github.com/mannuvilasara/xenon-shell/blob/main/Modules/Launcher/AppLauncher.qml): app launcher · App launching surface. · `Modules/Launcher/AppLauncher.qml`
- [Lock Screen](https://github.com/mannuvilasara/xenon-shell/blob/main/Modules/Lock/Lock.qml): auth surface · Lock screen stack including authentication and alternate views. · `Modules/Lock/Lock.qml`
- [Panels](https://github.com/mannuvilasara/xenon-shell/blob/main/Modules/Panels/SidePanel.qml): side panels · Slide-out info, control, power, and wallpaper panels. · `Modules/Panels/SidePanel.qml`
- [Notifications](https://github.com/mannuvilasara/xenon-shell/blob/main/Modules/Notifications/NotificationToast.qml): toast center · Notification toasts and notification list views. · `Modules/Notifications/NotificationToast.qml`
- [Settings](https://github.com/mannuvilasara/xenon-shell/blob/main/Modules/Settings/SettingsWindow.qml): preferences UI · Settings window and configuration pages. · `Modules/Settings/SettingsWindow.qml`
- [Overlays](https://github.com/mannuvilasara/xenon-shell/blob/main/Modules/Overlays/Overlays.qml): overlay stack · Transient overlays layered above the desktop. · `Modules/Overlays/Overlays.qml`
- [Corners](https://github.com/mannuvilasara/xenon-shell/blob/main/Modules/Corners/ScreenCorners.qml): chrome layer · Rounded screen corners and shell chrome. · `Modules/Corners/ScreenCorners.qml`
- [Widgets](https://github.com/mannuvilasara/xenon-shell/blob/main/Widgets/Icon.qml): shared components · Reusable UI primitives shared across bar, panels, lock screen, and settings. · `Widgets/Icon.qml`

### Tooling

Theme generation and preview scripts.

- [Assets](https://github.com/mannuvilasara/xenon-shell/blob/main/Assets/Templates/xenon_colors.json): theme assets · Template inputs and static asset resources used by the shell. · `Assets/Templates/xenon_colors.json`
- [Scripts](https://github.com/mannuvilasara/xenon-shell/blob/main/Scripts/template-processor.py): theme tooling · Theme generation, palette extraction, rendering, and preview tooling. · `Scripts/template-processor.py`

## Connections

- shell.qml → Core: shared state · Shell composition depends on shared runtime context and configuration.
- shell.qml → Services: binds · Shell surfaces consume live system data and control adapters.
- shell.qml → Background: loads · Shell composes the background layer.
- shell.qml → Bar: loads · Shell composes the top-level bar.
- shell.qml → Launcher: loads · Shell exposes the application launcher.
- shell.qml → Lock Screen: loads · Shell includes the lock screen subsystem.
- shell.qml → Panels: loads · Shell includes side panels and popover surfaces.
- shell.qml → Notifications: loads · Shell includes notification presentation.
- shell.qml → Settings: loads · Shell includes the settings window.
- shell.qml → Overlays: loads · Shell stacks transient overlays above the desktop.
- Core → IPC: exposes · Core provides the IPC command bridge for external control.
- Core → Theme: shares theme · Core centralizes colors, icons, SVGs, and animations.
- Services → Bar: feeds status · System services drive bar indicators and widgets.
- Services → Panels: feeds controls · Services provide data and actions for control panels.
- Services → Lock Screen: feeds lock · Lock screen cards consume system and media services.
- Services → Notifications: feeds events · Notifications are surfaced from shared runtime events.
- Compositor → shell.qml: integrates · Compositor hooks sit below the UI composition root.
- Widgets → Bar: reused by · Bar is built from shared widget primitives.
- Widgets → Panels: reused by · Panels reuse common sliders, toggles, dividers, and trays.
- Widgets → Lock Screen: reused by · Lock screen cards rely on shared visual primitives.
- Widgets → Settings: reused by · Settings pages use shared form and toggle components.
- Assets → Scripts: templates · Theme templates are processed by the scripting pipeline.
- Scripts → Theme: generates · Scripts produce palettes and preview artifacts consumed by the shell theme.
- IPC → Launcher: toggles · External IPC can open or close the launcher.
- IPC → Panels: toggles · External IPC can show or hide panels.
- IPC → Settings: toggles · External IPC can open the settings window.
- IPC → Lock Screen: locks · External IPC can trigger lock actions.
