# axenide/ambxst architecture

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

- Interactive diagram: https://gitdiagram.com/axenide/ambxst
- Repository: https://github.com/axenide/ambxst

## Overview

1. This repository is a Wayland desktop shell called Ambxst, built primarily as a Quickshell/QML application. The top-level `shell.qml` is the entry point, and the runtime is oriented around rendering persistent shell surfaces and overlays rather than a traditional app window model.

2. The architecture is split into a small configuration core and a large set of QML modules. `config/Config.qml`, `config/defaults/*`, `config/ConfigValidator.js`, and `config/KeybindActions.js` define the validated settings model and the action map for user bindings; everything else consumes that configuration.

3. The main presentation layer lives under `modules/` and is organized by surface, not by business domain. Major shell surfaces include the bar, dock, desktop, lockscreen, notch, overview, sidebar, widgets/dashboard, notification UI, power menu, tools overlays, corners, and frame/panel effects.

4. `modules/services/` is the functional integration layer. These QML service objects wrap system capabilities such as audio, brightness, battery, Bluetooth, Wi‑Fi, power profiles, notifications, clipboard, screenshots, screen recording, compositor state, idle/lock behavior, weather, AI providers, and app/task management.

5. There is a clear separation between “stateful services” and “view components.” Services expose live state and commands, while the UI modules subscribe to those properties to update controls like sliders, toggles, popups, lists, and overlay windows. This is the primary data flow throughout the shell.

6. Compositor integration is a distinct boundary. The repo is designed around Hyprland today, with config generation under `assets/presets/*` and `modules/services/Compositor*` producing compositor settings/keybinds, while `install.sh` and `cli.sh` connect Ambxst to the user’s compositor startup configuration.

7. The theming pipeline is its own subsystem. `modules/theme/*` generates or exports theme data for multiple targets—GTK, Qt, Kitty, Discord, Pywal, NvChad, and color/icon models—using source palettes from `assets/colors/*` and preset-specific theme definitions.

8. Presets and assets are the content/configuration layer of the system. `assets/presets/*` bundles complete visual and behavioral profiles for different shell layouts, while `assets/wallpapers_example`, `assets/screenshots`, emoji/logo data, sound assets, and compositor metadata support the UI and bundled experiences.

9. Several features are implemented as auxiliary tools rather than embedded UI logic. The `scripts/` directory contains helpers for clipboard watching, OCR, QR scanning, color picking, weather, system monitoring, wallpaper/lockscreen behavior, recording, and similar tasks; these are invoked by services or tool widgets when native QML is not enough.

10. The dashboard/launcher widgets form a higher-level application area inside the shell. `modules/widgets/dashboard/*`, `modules/widgets/launcher/*`, `modules/widgets/overview/*`, and `modules/sidebar/*` provide the “control center” style experience: app launching, settings browsing, clipboard, notes, tmux sessions, metrics, wallpapers, and assistant panels.

11. Media and notification workflows are strongly integrated into the shell. Notification services feed the notification list/popup/notch views, while media control and widgets tie into MPRIS, audio mixers, EasyEffects, and lockscreen/full-player components for persistent playback control.

12. Packaging and deployment are handled separately from the runtime UI. `flake.nix`, `nix/`, and `install.sh` define how Ambxst is built and provisioned, while `assets/matugen` and related generators support downstream config generation for external tools.

13. Overall, the architecture is “shell UI on top of system integrations”: the QML layer renders surfaces and controls, services bind to OS/compositor features, scripts fill in imperative gaps, and presets/themes/assets provide the user-facing customization model. For an architecture diagram, the main boundaries are: configuration, UI surfaces, integration services, helper scripts, and external compositor/system dependencies.

Main entry points: [`modules`](https://github.com/axenide/ambxst/tree/main/modules) (Shell surfaces), [`modules/services`](https://github.com/axenide/ambxst/tree/main/modules/services) (State services), [`config/Config.qml`](https://github.com/axenide/ambxst/blob/main/config/Config.qml) (Config), [`shell.qml`](https://github.com/axenide/ambxst/blob/main/shell.qml) (shell.qml)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_runtime["Runtime shell"]
  node_shell_entry["shell.qml<br/>entrypoint<br/>[shell.qml]"]
  node_shell_panel["Shell panel<br/>shell surface"]
  node_osd["OSD<br/>overlay<br/>[OSD.qml]"]
  node_ui_surfaces["Shell surfaces<br/>presentation layer"]
end

subgraph group_grp_config["Config core"]
  node_config_model["Config<br/>settings model<br/>[Config.qml]"]
  node_config_defaults["Defaults"]
  node_config_validator["Validator<br/>validation<br/>[ConfigValidator.js]"]
  node_keybind_actions["Keybind actions<br/>action map<br/>[KeybindActions.js]"]
end

subgraph group_grp_services["Services"]
  node_service_core[("State services<br/>integration layer")]
  node_compositor_bridge["Compositor bridge<br/>hyprland integration"]
  node_media_io["Media I/O<br/>device control<br/>[Audio.qml]"]
  node_system_io["System services<br/>system state<br/>[Battery.qml]"]
  node_ai_services["AI services<br/>provider layer<br/>[AiModel.qml]"]
end

subgraph group_grp_widgets["Widgets"]
  node_dashboard["Dashboard<br/>control center<br/>[Dashboard.qml]"]
  node_launcher["Launcher<br/>[LauncherView.qml]"]
  node_overview["Overview<br/>workspace view<br/>[Overview.qml]"]
  node_sidebar["Sidebar<br/>assistant panel"]
end

subgraph group_grp_theme["Theme system"]
  node_theme_pipeline["Theme pipeline<br/>theme generation<br/>[Styling.qml]"]
end

subgraph group_grp_assets["Assets"]
  node_presets_content["Presets<br/>profile assets"]
  node_color_palettes["Color palettes<br/>palette source"]
end

subgraph group_grp_tools["Tools"]
  node_tool_scripts["Scripts<br/>helper tools"]
end

subgraph group_grp_packaging["Packaging"]
  node_packaging["Packaging<br/>build/deploy<br/>[flake.nix]"]
end

node_external_system(("OS / compositor<br/>external deps"))

node_shell_entry -->|"loads"| node_config_model
node_config_model -->|"validates"| node_config_validator
node_config_model -->|"defaults"| node_config_defaults
node_config_model -->|"binds"| node_keybind_actions
node_shell_entry -->|"renders"| node_ui_surfaces
node_ui_surfaces -->|"shares"| node_shell_panel
node_ui_surfaces -->|"overlays"| node_osd
node_ui_surfaces -->|"subscribes"| node_service_core
node_service_core -->|"controls"| node_media_io
node_service_core -->|"coordinates"| node_system_io
node_service_core -->|"selects"| node_ai_services
node_service_core -->|"bridges"| node_compositor_bridge
node_service_core -->|"invokes"| node_tool_scripts
node_ui_surfaces -->|"opens"| node_dashboard
node_ui_surfaces -->|"opens"| node_launcher
node_ui_surfaces -->|"opens"| node_overview
node_ui_surfaces -->|"opens"| node_sidebar
node_dashboard -->|"drives"| node_service_core
node_theme_pipeline -->|"sources"| node_color_palettes
node_theme_pipeline -->|"targets"| node_presets_content
node_packaging -->|"provisions"| node_external_system
node_compositor_bridge -->|"configures"| node_external_system
node_tool_scripts -->|"uses"| node_external_system

click node_shell_entry "https://github.com/axenide/ambxst/blob/main/shell.qml"
click node_shell_panel "https://github.com/axenide/ambxst/blob/main/modules/shell/UnifiedShellPanel.qml"
click node_osd "https://github.com/axenide/ambxst/blob/main/modules/shell/osd/OSD.qml"
click node_config_model "https://github.com/axenide/ambxst/blob/main/config/Config.qml"
click node_config_defaults "https://github.com/axenide/ambxst/tree/main/config/defaults"
click node_config_validator "https://github.com/axenide/ambxst/blob/main/config/ConfigValidator.js"
click node_keybind_actions "https://github.com/axenide/ambxst/blob/main/config/KeybindActions.js"
click node_service_core "https://github.com/axenide/ambxst/tree/main/modules/services"
click node_compositor_bridge "https://github.com/axenide/ambxst/blob/main/modules/services/CompositorConfig.qml"
click node_media_io "https://github.com/axenide/ambxst/blob/main/modules/services/Audio.qml"
click node_system_io "https://github.com/axenide/ambxst/blob/main/modules/services/Battery.qml"
click node_ai_services "https://github.com/axenide/ambxst/blob/main/modules/services/ai/AiModel.qml"
click node_theme_pipeline "https://github.com/axenide/ambxst/blob/main/modules/theme/Styling.qml"
click node_presets_content "https://github.com/axenide/ambxst/tree/main/assets/presets"
click node_color_palettes "https://github.com/axenide/ambxst/tree/main/assets/colors"
click node_ui_surfaces "https://github.com/axenide/ambxst/tree/main/modules"
click node_dashboard "https://github.com/axenide/ambxst/blob/main/modules/widgets/dashboard/Dashboard.qml"
click node_launcher "https://github.com/axenide/ambxst/blob/main/modules/widgets/launcher/LauncherView.qml"
click node_overview "https://github.com/axenide/ambxst/blob/main/modules/widgets/overview/Overview.qml"
click node_sidebar "https://github.com/axenide/ambxst/blob/main/modules/sidebar/AssistantSidebar.qml"
click node_tool_scripts "https://github.com/axenide/ambxst/tree/main/scripts"
click node_packaging "https://github.com/axenide/ambxst/blob/main/flake.nix"

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_entry,node_shell_panel,node_osd,node_ui_surfaces,node_tool_scripts toneBlue
class node_config_model,node_config_defaults,node_config_validator,node_keybind_actions,node_packaging toneAmber
class node_service_core,node_compositor_bridge,node_media_io,node_system_io,node_ai_services toneMint
class node_dashboard,node_launcher,node_overview,node_sidebar toneRose
class node_theme_pipeline toneIndigo
class node_presets_content,node_color_palettes toneTeal
class node_external_system toneNeutral
```

## Components

### Runtime shell

Top-level QML shell surfaces and presentation layers.

- [shell.qml](https://github.com/axenide/ambxst/blob/main/shell.qml): entrypoint · Quickshell entry that boots the persistent shell UI. · `shell.qml`
- [Shell panel](https://github.com/axenide/ambxst/blob/main/modules/shell/UnifiedShellPanel.qml): shell surface · Shared shell panel/reservation layer used by multiple surfaces. · `modules/shell/UnifiedShellPanel.qml`
- [OSD](https://github.com/axenide/ambxst/blob/main/modules/shell/osd/OSD.qml): overlay · Transient on-screen display for shell feedback. · `modules/shell/osd/OSD.qml`
- [Shell surfaces](https://github.com/axenide/ambxst/tree/main/modules): presentation layer · Bar, dock, desktop, lockscreen, notch, overview, sidebar, notifications, tools, and corner effects. · `modules`

### Config core

Validated settings model, defaults, and binding actions.

- [Config](https://github.com/axenide/ambxst/blob/main/config/Config.qml): settings model · Validated configuration object consumed by the shell. · `config/Config.qml`
- [Defaults](https://github.com/axenide/ambxst/tree/main/config/defaults): defaults set · Per-feature default settings for shell modules and services. · `config/defaults`
- [Validator](https://github.com/axenide/ambxst/blob/main/config/ConfigValidator.js): validation · Checks and normalizes configuration data. · `config/ConfigValidator.js`
- [Keybind actions](https://github.com/axenide/ambxst/blob/main/config/KeybindActions.js): action map · Named actions invoked by user bindings and compositor setup. · `config/KeybindActions.js`

### Services

Stateful integrations that expose OS/compositor capabilities to the UI.

- [State services](https://github.com/axenide/ambxst/tree/main/modules/services): integration layer · Live state and commands for shell-facing system features. · `modules/services`
- [Compositor bridge](https://github.com/axenide/ambxst/blob/main/modules/services/CompositorConfig.qml): hyprland integration · Builds compositor config, keybinds, and runtime connectivity. · `modules/services/CompositorConfig.qml`
- [Media I/O](https://github.com/axenide/ambxst/blob/main/modules/services/Audio.qml): device control · Audio, Bluetooth, brightness, power, and related controls. · `modules/services/Audio.qml`
- [System services](https://github.com/axenide/ambxst/blob/main/modules/services/Battery.qml): system state · Battery, network, idle, notifications, screenshots, recorder, and task state. · `modules/services/Battery.qml`
- [AI services](https://github.com/axenide/ambxst/blob/main/modules/services/ai/AiModel.qml): provider layer · Provider strategies and shared AI model selection. · `modules/services/ai/AiModel.qml`

### Widgets

Dashboard, launcher, overview, sidebar, and control-center style experiences.

- [Dashboard](https://github.com/axenide/ambxst/blob/main/modules/widgets/dashboard/Dashboard.qml): control center · Multi-tab dashboard for settings, controls, clipboard, notes, metrics, and wallpapers. · `modules/widgets/dashboard/Dashboard.qml`
- [Launcher](https://github.com/axenide/ambxst/blob/main/modules/widgets/launcher/LauncherView.qml): app launcher · Search-and-launch surface for applications and actions. · `modules/widgets/launcher/LauncherView.qml`
- [Overview](https://github.com/axenide/ambxst/blob/main/modules/widgets/overview/Overview.qml): workspace view · Workspace and window overview surface. · `modules/widgets/overview/Overview.qml`
- [Sidebar](https://github.com/axenide/ambxst/blob/main/modules/sidebar/AssistantSidebar.qml): assistant panel · Assistant-oriented sidebar and model selection UI. · `modules/sidebar/AssistantSidebar.qml`

### Theme system

Theme generation, color palettes, and export targets.

- [Theme pipeline](https://github.com/axenide/ambxst/blob/main/modules/theme/Styling.qml): theme generation · Generates target-specific themes and icon/color styling. · `modules/theme/Styling.qml`

### Assets

Presets, palettes, wallpapers, sounds, and bundled content.

- [Presets](https://github.com/axenide/ambxst/tree/main/assets/presets): profile assets · Preset bundles for shell layouts, behavior, theme, and compositor settings. · `assets/presets`
- [Color palettes](https://github.com/axenide/ambxst/tree/main/assets/colors): palette source · Named palette definitions used by the theme system. · `assets/colors`

### Tools

Imperative helpers and shell-adjacent scripts.

- [Scripts](https://github.com/axenide/ambxst/tree/main/scripts): helper tools · Imperative helpers for clipboard, OCR, scanning, monitoring, weather, and capture tasks. · `scripts`

### Packaging

Build, install, and compositor integration entry points.

- [Packaging](https://github.com/axenide/ambxst/blob/main/flake.nix): build/deploy · Nix flake, install script, and CLI glue for provisioning the shell. · `flake.nix`

### Other components

- **OS / compositor**: external deps · Wayland compositor and host system features that Ambxst integrates with.

## Connections

- shell.qml → Config: loads · Bootstraps the shell with validated settings.
- Config → Validator: validates · Configuration is normalized before use.
- Config → Defaults: defaults · Defaults seed feature-specific settings.
- Config → Keybind actions: binds · Keybind names map to shell and compositor actions.
- shell.qml → Shell surfaces: renders · Entrypoint drives the persistent shell surfaces.
- Shell surfaces → Shell panel: shares · Many surfaces reuse the common shell panel layer.
- Shell surfaces → OSD: overlays · Shell surfaces trigger transient OSD feedback.
- Shell surfaces → State services: subscribes · UI components bind to live service state.
- State services → Media I/O: controls · Audio, brightness, Bluetooth, and power devices.
- State services → System services: coordinates · Battery, network, notifications, idle, screenshots, recorder, and tasks.
- State services → AI services: selects · AI provider strategies are exposed through shared services.
- State services → Compositor bridge: bridges · Compositor config and keybind generation flow through this boundary.
- State services → Scripts: invokes · Services call out to helper scripts when imperative work is needed.
- Shell surfaces → Dashboard: opens · Dashboard acts as the central control-center experience.
- Shell surfaces → Launcher: opens · Launcher provides app and action search.
- Shell surfaces → Overview: opens · Overview provides workspace/window navigation.
- Shell surfaces → Sidebar: opens · Sidebar hosts assistant and related panels.
- Dashboard → State services: drives · Dashboard tabs manipulate system state through services.
- Theme pipeline → Color palettes: sources · Theme generation starts from palette definitions.
- Theme pipeline → Presets: targets · Preset-specific theme data determines exported output.
- Packaging → OS / compositor: provisions · Install and startup glue connect Ambxst to the compositor and host system.
- Compositor bridge → OS / compositor: configures · Generated settings and keybinds configure the compositor.
- Scripts → OS / compositor: uses · Scripts shell out to system utilities and device tools.