Skip to content

007: Architecture

  • Type: Architecture
  • Status: Proposed
  • Date: 2026-10-03
  • Author(s) / Deciders: João V. Farias
  • Question: How is the system decomposed into components, data flows, and directory structures, and which diagrams document its design?

Context

Define the high-level system boundaries, technology stack, module layout under source/, and visual diagrams so contributors understand how data and control flow through the shell.

Required Visualizations

  1. UML Use-Case Diagram: Map actors to top-level system interactions.
  2. Data-Flow Diagram (DFD): Trace how inputs are ingested, transformed, stored, and emitted across boundaries.

Optional Visualizations (If Necessary)

  • Class Diagram: Include when complex domain hierarchies or interface contracts need explicit visualization.
  • Object Diagram: Include when runtime object graphs or ownership lifetimes require concrete snapshots.

Requirements and Restrictions

  • Tech Stack & Runtime:
  • Shell engine: Quickshell (QtQuick / QML)
  • Wayland compositor: Hyprland
  • Directory Layout: Organization of QML modules, services, and widgets inside source/ and test suites under tests/.
  • External Boundaries: Hyprland IPC sockets, D-Bus services (StatusNotifierItem, MPRIS, notifications, power management), and CLI helper processes.

Alternatives

  • Aylur's GTK Shell (AGS) / Astal: Used in the previous version of the shell; replaced by Quickshell for QtQuick scene-graph performance and reactive QML bindings.
  • Monolithic vs. Modular / Layered QML: Compare architectural styles considered for organizing shell services and UI surfaces.

Decision

  • Target Quickshell as the widget and shell runtime engine.
  • Target Hyprland as the Wayland compositor.
  • Describe the chosen module architecture under source/ and embed the Mermaid UML Use-Case and Data-Flow diagrams below.

Consequences

Positives

  • Visual diagrams and explicit module boundaries reduce onboarding time and prevent accidental coupling between UI panels and background services.

Negatives

  • Diagrams must be updated alongside structural refactors to prevent documentation drift.