# quickshell-mirror/quickshell architecture

> Architecture diagram of the GitHub repository quickshell-mirror/quickshell, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/quickshell-mirror/quickshell
- Repository: https://github.com/quickshell-mirror/quickshell

## Overview

##### Project Type and Purpose
- Quickshell is an open-source, modular, Qt/QML-based “shell” framework for Wayland (and X11) compositors.
- It provides a core engine, plugin system, adapters for Wayland/X11, D-Bus services, I/O, crash handling, UI widgets, and scripting via QML.

##### File Structure Analysis
- src/launch & main.cpp: entry point & command-line parsing
- src/core: core engine, plugin loader, object model, QML integration
- src/dbus, src/ipc, src/io, src/crash: infrastructure modules
- src/services/*: individual D-Bus service plugins (greetd, mpris, notifications, pam, pipewire, status_notifier, upower)
- src/wayland, src/x11: compositor protocol adapters
- src/ui & src/widgets: QML UI components and helper widgets
- src/window: window management interfaces
- CMakeLists, shell.nix, flake.nix: build & CI configuration

##### README Insights
- Minimal description; emphasizes external website for docs
- Contribution guidelines and licensing (LGPL v3)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Launcher
    Launcher["Launcher (CLI)"]:::infra
    Launcher -->|"initializes"| CoreEngine

    %% Core Engine & Plugin Manager
    CoreEngine["Core Engine\n& Plugin Manager"]:::core

    %% Plugins Subgraph
    subgraph "Plugins / Modules"
        direction TB
        CrashHandler["Crash Handler"]:::infra
        DBusAdapter["D-Bus Adapter"]:::infra
        IPC["IPC Module"]:::infra
        IO["I/O Module"]:::infra
        WaylandAdapter["Wayland Adapter"]:::adapter
        X11Adapter["X11 Adapter"]:::adapter
        subgraph "D-Bus Service Plugins"
            direction TB
            Greetd["greetd"]:::service
            MPRIS["mpris"]:::service
            Notifications["notifications"]:::service
            PAM["pam"]:::service
            PipeWire["pipewire"]:::service
            StatusNotifier["status_notifier"]:::service
            UPower["upower"]:::service
        end
        UILayer["UI Layer\n(QML + Widgets)"]:::ui
        WindowMgmt["Window Management"]:::core
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        WaylandExt["Wayland Compositor"]:::external
        X11Ext["X11 Server"]:::external
        DBusExt["D-Bus Daemon"]:::external
        PAMServ["PAM Service"]:::external
        PipeWireServ["PipeWire Service"]:::external
        MPRIServ["MPRIS Service"]:::external
    end

    %% Core to Plugins
    CoreEngine -->|"loads"| CrashHandler
    CoreEngine -->|"loads"| DBusAdapter
    CoreEngine -->|"loads"| IPC
    CoreEngine -->|"loads"| IO
    CoreEngine -->|"loads"| WaylandAdapter
    CoreEngine -->|"loads"| X11Adapter
    CoreEngine -->|"loads"| Greetd
    CoreEngine -->|"loads"| MPRIS
    CoreEngine -->|"loads"| Notifications
    CoreEngine -->|"loads"| PAM
    CoreEngine -->|"loads"| PipeWire
    CoreEngine -->|"loads"| StatusNotifier
    CoreEngine -->|"loads"| UPower
    CoreEngine -->|"loads"| UILayer
    CoreEngine -->|"loads"| WindowMgmt

    %% UI interaction
    CoreEngine <-->|"QML context / signals"| UILayer

    %% Adapters to External
    WaylandAdapter <-->|"protocol messages"| WaylandExt
    X11Adapter <-->|"protocol messages"| X11Ext

    %% D-Bus communication
    DBusAdapter <-->|"method calls / signals"| DBusExt
    Greetd <-->|"Service calls"| DBusExt
    MPRIS <-->|"Service calls"| DBusExt
    Notifications <-->|"Service calls"| DBusExt
    PAM <-->|"Service calls"| DBusExt
    PipeWire <-->|"Service calls"| DBusExt
    StatusNotifier <-->|"Service calls"| DBusExt
    UPower <-->|"Service calls"| DBusExt

    %% IPC / I/O to external processes
    IPC -->|"sockets"| External
    IO -->|"file / socket I/O"| External

    %% Window management interactions
    WindowMgmt -->|"window APIs"| WaylandAdapter
    WindowMgmt -->|"window APIs"| X11Adapter

    %% Click Events
    click Launcher "https://github.com/quickshell-mirror/quickshell/blob/master/src/main.cpp"
    click CoreEngine "https://github.com/quickshell-mirror/quickshell/tree/master/src/core/"
    click CrashHandler "https://github.com/quickshell-mirror/quickshell/tree/master/src/crash/"
    click DBusAdapter "https://github.com/quickshell-mirror/quickshell/tree/master/src/dbus/"
    click IPC "https://github.com/quickshell-mirror/quickshell/tree/master/src/ipc/"
    click IO "https://github.com/quickshell-mirror/quickshell/tree/master/src/io/"
    click UILayer "https://github.com/quickshell-mirror/quickshell/tree/master/src/ui/"
    click WaylandAdapter "https://github.com/quickshell-mirror/quickshell/tree/master/src/wayland/"
    click X11Adapter "https://github.com/quickshell-mirror/quickshell/tree/master/src/x11/"
    click WindowMgmt "https://github.com/quickshell-mirror/quickshell/tree/master/src/window/"
    click Greetd "https://github.com/quickshell-mirror/quickshell/tree/master/src/services/greetd/"
    click MPRIS "https://github.com/quickshell-mirror/quickshell/tree/master/src/services/mpris/"
    click Notifications "https://github.com/quickshell-mirror/quickshell/tree/master/src/services/notifications/"
    click PAM "https://github.com/quickshell-mirror/quickshell/tree/master/src/services/pam/"
    click PipeWire "https://github.com/quickshell-mirror/quickshell/tree/master/src/services/pipewire/"
    click StatusNotifier "https://github.com/quickshell-mirror/quickshell/tree/master/src/services/status_notifier/"
    click UPower "https://github.com/quickshell-mirror/quickshell/tree/master/src/services/upower/"

    %% Styles
    classDef core fill:#bfdffd,stroke:#333,stroke-width:1px;
    classDef infra fill:#b3e5fc,stroke:#333,stroke-width:1px;
    classDef adapter fill:#ffd8b1,stroke:#333,stroke-width:1px;
    classDef ui fill:#c2f0c2,stroke:#333,stroke-width:1px;
    classDef service fill:#e1bee7,stroke:#333,stroke-width:1px;
    classDef external fill:#cccccc,stroke:#333,stroke-width:1px;
```
