# alexays/waybar architecture

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

- Interactive diagram: https://gitdiagram.com/alexays/waybar
- Repository: https://github.com/alexays/waybar

## Overview

##### Project Type and Purpose
- Type: Native desktop application (not a web service), with a plugin-style modular architecture.
- Purpose: Display status information (workspaces, battery, network, media, custom scripts, etc.) in a Wayland bar.

a. Core Application (src/main.cpp, AModule/IModule, factory, bar, client, group)
b. Configuration Loader (config.cpp + resources/config.jsonc)
c. Module Plugins (src/modules + include/modules):
– Compositor modules (sway, river, hyprland, dwl, niri, wlr) via IPC/protocols (protocol/*.xml)
– System modules (battery, cpu, memory, network, pulseaudio, mpd, etc.)
– Custom modules (user scripts, CFFI)
d. Rendering Layer (GTK layer shell via gtkmm3, CSS styling in resources/style.css, waybar_icons.gresource.xml)
e. IPC/Protocol Layer (DBus-menu, Status-Notifier, compositor IPC)
f. Utility Libraries (util/*: JSON, threading, signal handling, backends)
g. External Services & System Interfaces:
– Wayland compositor (Sway, River, Hyprland, etc.)
– DBus (UPower, NetworkManager, PulseAudio, SystemD, etc.)
– MPD, sndio, WirePlumber, evdev, pipewire

1. On startup, Core reads config → Configuration Loader
2. Core passes config to Factory → instantiates requested Module Plugins
3. Each Module:
– Registers with Core’s Bar/Group for layout
– Uses Utility Libraries to fetch data (JSON parser, Backend APIs)
– Listens/subscribes via IPC (DBus, compositor socket) or polls system APIs
4. Module emits updates → Core pushes to Rendering Layer (GTK) → displayed on screen
5. User events (clicks, scrolls) captured by Rendering Layer → routed back to Module or Core → possibly send commands via compositor IPC or DBus

##### Architectural Patterns and Principles
- Plugin-style modularity: IModule/AModule interface, Factory pattern for instantiation
- Separation of concerns:
– Core (lifecycle, layout) vs. Modules (data acquisition) vs. Renderer (UI)
– Util layer isolates common code (JSON, signals, threads)
– Protocol definitions in XML under protocol/ kept separate from code
- Build & Deployment: Meson subprojects for third-party libs; Dockerfiles and Nix flake for reproducible builds

##### Technologies & Frameworks
- C++17, gtkmm3 (UI), JSONCpp (config & data), libsigc++ (signals), fmt/spdlog (logging), Wayland protocols
- IPC: DBus-menu / Status-Notifier, compositor-specific sockets (Sway IPC, River IPC, etc.)
- Build: Meson, Ninja, scdoc (man pages), Docker, Nix

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Application
    subgraph "Core Application"
        direction TB
        CoreMain["main.cpp"]:::core
        IModule["IModule/AModule Interfaces"]:::core
        Factory["Factory"]:::core
        Bar["Bar/Layout Manager"]:::core
        Client["Client"]:::core
        Group["Group"]:::core
    end

    %% Configuration Loader
    ConfigLoader["Configuration Loader"]:::config
    ConfigLoader -->|reads config| ConfigFile["config.jsonc"]:::config

    %% Module Plugins
    subgraph "Module Plugins"
        direction TB
        subgraph "Compositor Modules"
            direction TB
            Sway["Sway Module"]:::module
            Hyprland["Hyprland Module"]:::module
            River["River Module"]:::module
            Dwl["dwl Module"]:::module
            Niri["Niri Module"]:::module
            WLR["WLR Module"]:::module
        end
        subgraph "System Modules"
            direction TB
            Battery["Battery Module"]:::module
            CPU["CPU Module"]:::module
            Memory["Memory Module"]:::module
            Network["Network Module"]:::module
            Pulseaudio["PulseAudio Module"]:::module
            MPD["MPD Module"]:::module
        end
        subgraph "Custom Modules"
            direction TB
            CFFI["CFFI Module"]:::module
            CustomScripts["Custom Scripts"]:::module
        end
    end

    %% Rendering Layer
    subgraph "Rendering Layer"
        direction TB
        GTKShell["GTK Layer Shell"]:::render
        AAppIconLabel["AAppIconLabel/Labels/Sliders"]:::render
        Style["style.css & icons"]:::render
    end

    %% IPC/Protocol Layer
    IPC["IPC/Protocol Definitions"]:::ipc

    %% Utility Libraries
    Util["Utility Libraries"]:::util

    %% External Services & System Interfaces
    subgraph "External Services"
        direction TB
        Compositor["Wayland Compositor"]:::external
        DBus["DBus Services"]:::external
        MPDService["MPD/Sound Services"]:::external
    end

    %% Startup Flow
    ConfigLoader -->|provides config| CoreMain
    CoreMain -->|initializes| IModule
    CoreMain --> Factory
    Factory -->|instantiates| Sway & Hyprland & River & Dwl & Niri & WLR & Battery & CPU & Memory & Network & Pulseaudio & MPD & CFFI & CustomScripts

    %% Module Interactions
    Sway & Hyprland & River & Dwl & Niri & WLR --> IPC
    Battery & CPU & Memory & Network & Pulseaudio & MPD --> Util
    CFFI & CustomScripts --> Util

    %% Rendering Flow
    Sway & Hyprland & River & Dwl & Niri & WLR & Battery & CPU & Memory & Network & Pulseaudio & MPD & CFFI & CustomScripts -->|updates| CoreMain
    CoreMain -->|pushes| GTKShell
    GTKShell --> AAppIconLabel
    AAppIconLabel --> Style

    %% User Input
    UserInput["User Events (click/scroll)"]:::external
    UserInput --> GTKShell
    GTKShell --> CoreMain
    GTKShell --> Sway & Hyprland & River & Dwl & Niri & WLR

    %% IPC to External
    IPC --> Compositor
    Util --> DBus
    Util --> MPDService

    %% Click Events
    click CoreMain "https://github.com/alexays/waybar/blob/master/src/main.cpp"
    click IModule "https://github.com/alexays/waybar/blob/master/include/IModule.hpp"
    click IModule "https://github.com/alexays/waybar/blob/master/include/AModule.hpp"
    click Factory "https://github.com/alexays/waybar/blob/master/include/factory.hpp"
    click Factory "https://github.com/alexays/waybar/blob/master/src/factory.cpp"
    click Bar "https://github.com/alexays/waybar/blob/master/include/bar.hpp"
    click Bar "https://github.com/alexays/waybar/blob/master/src/bar.cpp"
    click Client "https://github.com/alexays/waybar/blob/master/include/client.hpp"
    click Client "https://github.com/alexays/waybar/blob/master/src/client.cpp"
    click Group "https://github.com/alexays/waybar/blob/master/include/group.hpp"
    click Group "https://github.com/alexays/waybar/blob/master/src/group.cpp"
    click ConfigLoader "https://github.com/alexays/waybar/blob/master/src/config.cpp"
    click ConfigFile "https://github.com/alexays/waybar/blob/master/resources/config.jsonc"
    click Sway "https://github.com/alexays/waybar/tree/master/include/modules/sway"
    click Sway "https://github.com/alexays/waybar/tree/master/src/modules/sway"
    click Hyprland "https://github.com/alexays/waybar/tree/master/include/modules/hyprland"
    click Hyprland "https://github.com/alexays/waybar/tree/master/src/modules/hyprland"
    click River "https://github.com/alexays/waybar/tree/master/include/modules/river"
    click River "https://github.com/alexays/waybar/tree/master/src/modules/river"
    click Dwl "https://github.com/alexays/waybar/tree/master/include/modules/dwl"
    click Dwl "https://github.com/alexays/waybar/tree/master/src/modules/dwl"
    click Niri "https://github.com/alexays/waybar/tree/master/include/modules/niri"
    click Niri "https://github.com/alexays/waybar/tree/master/src/modules/niri"
    click WLR "https://github.com/alexays/waybar/tree/master/include/modules/wlr"
    click WLR "https://github.com/alexays/waybar/tree/master/src/modules/wlr"
    click Battery "https://github.com/alexays/waybar/blob/master/include/modules/battery.hpp"
    click Battery "https://github.com/alexays/waybar/blob/master/src/modules/battery.cpp"
    click CPU "https://github.com/alexays/waybar/blob/master/include/modules/cpu.hpp"
    click CPU "https://github.com/alexays/waybar/blob/master/src/modules/cpu.cpp"
    click Memory "https://github.com/alexays/waybar/blob/master/include/modules/memory.hpp"
    click Memory "https://github.com/alexays/waybar/tree/master/src/modules/memory"
    click Network "https://github.com/alexays/waybar/blob/master/include/modules/network.hpp"
    click Network "https://github.com/alexays/waybar/blob/master/src/modules/network.cpp"
    click Pulseaudio "https://github.com/alexays/waybar/blob/master/include/modules/pulseaudio.hpp"
    click Pulseaudio "https://github.com/alexays/waybar/blob/master/src/modules/pulseaudio.cpp"
    click MPD "https://github.com/alexays/waybar/tree/master/include/modules/mpd"
    click MPD "https://github.com/alexays/waybar/tree/master/src/modules/mpd"
    click CFFI "https://github.com/alexays/waybar/blob/master/include/modules/cffi.hpp"
    click CFFI "https://github.com/alexays/waybar/blob/master/src/modules/cffi.cpp"
    click CustomScripts "https://github.com/alexays/waybar/tree/master/resources/custom_modules"
    click GTKShell "https://github.com/alexays/waybar/blob/master/subprojects/gtk-layer-shell.wrap"
    click AAppIconLabel "https://github.com/alexays/waybar/blob/master/include/AAppIconLabel.hpp"
    click AAppIconLabel "https://github.com/alexays/waybar/blob/master/src/AAppIconLabel.cpp"
    click AAppIconLabel "https://github.com/alexays/waybar/blob/master/include/AIconLabel.hpp"
    click AAppIconLabel "https://github.com/alexays/waybar/blob/master/src/AIconLabel.cpp"
    click AAppIconLabel "https://github.com/alexays/waybar/blob/master/include/ALabel.hpp"
    click AAppIconLabel "https://github.com/alexays/waybar/blob/master/src/ALabel.cpp"
    click AAppIconLabel "https://github.com/alexays/waybar/blob/master/include/ASlider.hpp"
    click AAppIconLabel "https://github.com/alexays/waybar/blob/master/src/ASlider.cpp"
    click Style "https://github.com/alexays/waybar/blob/master/resources/style.css"
    click Style "https://github.com/alexays/waybar/blob/master/resources/icons/waybar_icons.gresource.xml"
    click IPC "https://github.com/alexays/waybar/tree/master/protocol"
    click Util "https://github.com/alexays/waybar/tree/master/include/util"
    click Util "https://github.com/alexays/waybar/tree/master/src/util"
    click Build "https://github.com/alexays/waybar/blob/master/meson.build"
    click Build "https://github.com/alexays/waybar/blob/master/meson_options.txt"
    click Build "https://github.com/alexays/waybar/tree/master/Dockerfiles"
    click Build "https://github.com/alexays/waybar/blob/master/default.nix"
    click Build "https://github.com/alexays/waybar/blob/master/flake.nix"

    %% Styles
    classDef core fill:#003f5c,stroke:#000,color:#fff
    classDef config fill:#2f4b7c,stroke:#000,color:#fff
    classDef module fill:#2f7f4f,stroke:#000,color:#fff
    classDef render fill:#7a5195,stroke:#000,color:#fff
    classDef ipc fill:#ff7c43,stroke:#000,color:#fff
    classDef util fill:#ffa600,stroke:#000,color:#000
    classDef external fill:#aaaaaa,stroke:#000,color:#000
    classDef Build fill:#cccccc,stroke:#000,color:#000
```
