How mannuvilasara/xenon-shell works
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 shell.qml · Ipc.qml IPC · OsService.qml Services · Icon.qml Widgets
Components 18
Runtime
Composition root, shared state, services, and UI surfaces.
- shell.qml · Top-level shell composition that assembles the desktop experience.
shell.qml - Core · Shared context, config, state, logging, icons, animations, and IPC.
Core/Context.qml - IPC · External control surface for opening modules and triggering shell actions.
Core/Ipc.qml - Theme · Centralized colors, icons, SVGs, and animation primitives.
Core/Colors.qml - Services · Live adapters for battery, audio, network, media, wallpaper, time, and system info.
Services/OsService.qml - Compositor · Compositor-specific integration layer under services.
Services/Compositor/Compositor.qml
UI
Desktop shell modules and reusable widgets.
- Background · Wallpaper and background presentation.
Modules/Background/Background.qml - Bar · Top-level shell bar and its window container.
Modules/Bar/Bar.qml - Launcher · App launching surface.
Modules/Launcher/AppLauncher.qml - Lock Screen · Lock screen stack including authentication and alternate views.
Modules/Lock/Lock.qml - Panels · Slide-out info, control, power, and wallpaper panels.
Modules/Panels/SidePanel.qml - Notifications · Notification toasts and notification list views.
Modules/Notifications/NotificationToast.qml - Settings · Settings window and configuration pages.
Modules/Settings/SettingsWindow.qml - Overlays · Transient overlays layered above the desktop.
Modules/Overlays/Overlays.qml - Corners · Rounded screen corners and shell chrome.
Modules/Corners/ScreenCorners.qml - Widgets · Reusable UI primitives shared across bar, panels, lock screen, and settings.
Widgets/Icon.qml
Connections 27
- 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.