axenide/ambxst

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.