# jakestanger/ironbar architecture

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

- Interactive diagram: https://gitdiagram.com/jakestanger/ironbar
- Repository: https://github.com/jakestanger/ironbar

## Overview

##### Main components
- Core Binary and Entry Point – Represented by src/main.rs, this is the application’s entry point that initializes core services.
- Configuration – Found under src/config and supported by documentation/examples, it reads and processes configuration files (Corn, TOML, JSON, etc.) and determines settings for the bar.
- UI / Rendering Layer – Built on GTK (with GTK helpers in src/gtk_helpers.rs and gtk-layer-shell support), this is responsible for rendering the bar, applying dynamic CSS themes (see docs/Styling guide.md), and managing popups.
- Modules / Widgets – Located in src/modules (with each module, such as clock, music, networkmanager, tray, workspaces, etc., in their dedicated files/subdirectories), these are the individual components that display dynamic content and handle specific functionality on the bar.
- Clients – Under src/clients, the project integrates with various Wayland compositors and related services. There are different clients (for Sway, Hyprland, Niri, libinput, etc.) that abstract the interaction with compositors and external services (e.g., clipboard, system info, volume, etc.).
- IPC System – Found in src/ipc (with subdirectories for client and server implementations), it enables interprocess communication, allowing external commands to interact with Ironbar (for actions like reloading configuration or updating content).
- Scripting and Dynamic Content – Support for Lua scripting (in the lua directory) and custom script modules (src/clients/lua.rs) allow dynamic widget content and extensions.

##### Relationships and interactions
- The Core Binary (main.rs) initializes and orchestrates the configuration loader, the UI renderer, the module system, and the IPC server.
- The Configuration module feeds settings and style information into both the UI layer and module initialization.
- The UI rendering layer (using GTK and CSS) dynamically creates the bar layout and applies theming; it interacts with individual modules to display their output.
- Modules (widgets) obtain data either from dedicated clients (e.g., for music, network, notifications) or from internal data pipelines. They must be shown as separate, interconnected elements.
- The Clients layer abstracts different integrations with compositors (Sway, Hyprland, etc.) and other OS-level data sources, feeding necessary events or state data to modules.
- The IPC system manages command requests (with separate server and client components) providing external control over the bar’s dynamic behavior.

##### Architectural patterns and design principles
- Modular Design – Each widget and client is separated logically, facilitating extensibility and independent updates.
- Separation of Concerns – The use of distinct directories (e.g., src/config, src/modules, src/clients, src/ipc) clearly separates configuration, business logic, UI, and communication layers.

##### Relevant technologies, frameworks, and libraries
- Rust – The primary language used.
- GTK and gtk-layer-shell – For rendering and theming the bar.
- Wayland (and libraries like Smithay Client Toolkit) – For communicating with supported compositors.
- Scripting support via Lua – Allowing dynamic content and widget customization.

##### Elements
- Core Application (main.rs)
- Configuration Manager (src/config)
- UI/Rendering Engine (GTK + CSS integration)
- Modules/Widgets (src/modules – list a few key ones like clock, music, notifications)
- Clients (src/clients – include sub-clients for Sway, Hyprland, etc.)
- IPC System (client and server components in src/ipc)
- Scripting/Dynamic Extensions (lua support)
- Configuration settings flowing into UI and module initialization.
- Clients feeding live data into modules.
- IPC commands interacting with the core application.

##### Detail and clarity
- Do not over-simplify – be as detailed as possible by separately accounting for each functional area.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Core Application
    Core["Core Application"]:::core
    click Core "https://github.com/jakestanger/ironbar/blob/master/src/main.rs"
    
    %% Configuration Manager
    Config["Configuration Manager"]:::config
    click Config "https://github.com/jakestanger/ironbar/tree/master/src/config"
    
    %% UI / Rendering Engine
    UI["UI / Rendering Engine"]:::ui
    click UI "https://github.com/jakestanger/ironbar/blob/master/src/gtk_helpers.rs"
    
    %% Modules / Widgets
    subgraph "Modules / Widgets"
        Modules["Modules (General)"]:::modules
        click Modules "https://github.com/jakestanger/ironbar/tree/master/src/modules"
        Clock["Clock Module"]:::modules
        click Clock "https://github.com/jakestanger/ironbar/blob/master/src/modules/clock.rs"
        Music["Music Module"]:::modules
        click Music "https://github.com/jakestanger/ironbar/blob/master/src/modules/music/mod.rs"
        Tray["Tray Module"]:::modules
        click Tray "https://github.com/jakestanger/ironbar/blob/master/src/modules/tray/mod.rs"
        Workspaces["Workspaces Module"]:::modules
        click Workspaces "https://github.com/jakestanger/ironbar/blob/master/src/modules/workspaces/mod.rs"
    end

    %% Clients Integration
    Clients["Clients Integration"]:::clients
    click Clients "https://github.com/jakestanger/ironbar/tree/master/src/clients"
    
    %% IPC System
    IPC["IPC System"]:::ipc
    click IPC "https://github.com/jakestanger/ironbar/tree/master/src/ipc"
    
    %% Scripting & Dynamic Content
    Scripting["Scripting & Dynamic Content"]:::scripting
    click Scripting "https://github.com/jakestanger/ironbar/tree/master/lua"
    
    %% Data/Control Flow Connections
    Core -->|"initializes"| Config
    Core -->|"initializes"| UI
    Core -->|"initializes"| Modules
    Core -->|"sets up"| IPC

    Config -->|"supplies-settings"| UI
    Config -->|"supplies-settings"| Modules

    UI -->|"renders-output"| Modules

    Modules -->|"request-data"| Clients
    Clients -->|"provide-updates"| Modules

    IPC -->|"sends-commands"| Core

    Scripting -->|"extends"| Modules
    Scripting -->|"integrates"| Clients

%% Styles
classDef core fill:#ffe0b3,stroke:#d17a00,stroke-width:2px;
classDef config fill:#cce5ff,stroke:#003366,stroke-width:2px;
classDef ui fill:#d4edda,stroke:#155724,stroke-width:2px;
classDef modules fill:#fff3cd,stroke:#856404,stroke-width:2px;
classDef clients fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
classDef ipc fill:#f8d7da,stroke:#721c24,stroke-width:2px;
classDef scripting fill:#e2d6f3,stroke:#5a3e8c,stroke-width:2px;
```
