# fabric-development/fabric architecture

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

- Interactive diagram: https://gitdiagram.com/fabric-development/fabric
- Repository: https://github.com/fabric-development/fabric

## Overview

##### Project type and purpose
- Fabric is a Python-based Desktop Widgets System. It’s a library + CLI tool that lets users write desktop widgets in Python, supports X11/Wayland, and exposes services (audio, bluetooth, notifications, system tray, Hyprland integration) through a signal-driven core.
- The README calls it “Ricing, Made Easy,” a high-level widget framework—so it’s neither a full-stack web app nor a microservice; it’s a desktop UI toolkit with a runtime orchestrator.

##### File structure
- Top-level packaging:
- setup.py, pyproject.toml, requirements.txt for PyPI packaging
- default.nix, flake.nix, scripts/ for reproducible Nix builds
- Core library under src / fabric:
- fabric/__main__.py – CLI entrypoint
- fabric/core/ – orchestrator: Application, Fabricator, Service base
- fabric/utils/ – helper functions
- Services layer under fabric/*/service.py:
- audio, bluetooth, notifications, system_tray, hyprland
- DBus definitions under fabric/dbus_assets – XML interfaces
- Examples directory holds sample configs showcasing user-facing code
- tests/ for unit-style tests of individual services

##### README for additional insights
- Emphasis on signal-based workflow (no polling)
- Support for both display servers (X11/Wayland)
- High typing/DevEX, low resource usage

##### Main components & interactions
a. Components
- CLI / Entrypoint (fabric/__main__.py)
- Core Orchestrator
– Application (initialization)
– Fabricator (service/widget registry)
- Services
– AudioService, BluetoothService, NotificationService, SystemTrayService, HyprlandService
- DBus Layer
– XML assets → GDBus interfaces → Service implementations
- Widget Library
– GTK widgets (fabric.widgets.*)
- External Systems
– X11/Wayland compositor
– System D-Bus daemon
– OS subsystems: PulseAudio/ALSA, BlueZ, Desktop Notifications
- User Config / Examples

b. Relationships & data flows
– Entrypoint launches Application → instantiates Fabricator
– Fabricator loads services (reads XML introspection, instantiates each Service)
– Services register on the D-Bus and listen to OS events (audio level, Bluetooth status, notifications)
– Widget instances subscribe to service signals via core APIs
– Widgets translate signals into GTK UI updates
– User config code instantiates specific widgets via Python import
– Under the hood GTK event loop drives updates; events propagate back to Application

c. Architectural patterns & design principles
– Inversion of Control via Fabricator registry
– Signal/slot (observer) pattern for service → widget updates
– Modular service plugin pattern (each service lives in its own subpackage)
– Separation of concerns: services vs. UI vs. core orchestration
– Declarative user code (examples) separate from library code

d. Key technologies & frameworks
– Python 3.9+
– PyGObject / GTK4 for widget rendering
– GDBus (via PyGI) for D-Bus interfaces
– Nix for reproducible builds
– GObject signals for event wiring

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "CLI & Core"
        CLI["CLI Entrypoint\n(fabric/__main__.py)"]:::core
        App["Application\n(fabric/core/application.py)"]:::core
        Fab["Fabricator\n(fabric/core/fabricator.py)"]:::core
        SvcBase["Service Base\n(fabric/core/service.py)"]:::core
    end

    CLI -->|"launches"| App
    App -->|"instantiates"| Fab
    Fab --> SvcBase

    click CLI "https://github.com/fabric-development/fabric/blob/main/fabric/__main__.py"
    click App "https://github.com/fabric-development/fabric/blob/main/fabric/core/application.py"
    click Fab "https://github.com/fabric-development/fabric/blob/main/fabric/core/fabricator.py"
    click SvcBase "https://github.com/fabric-development/fabric/blob/main/fabric/core/service.py"

    subgraph "Services"
        Audio["AudioService"]:::service
        Bluetooth["BluetoothService"]:::service
        Notification["NotificationService"]:::service
        Tray["SystemTrayService"]:::service
        Hypr["HyprlandService"]:::service
    end

    SvcBase --> Audio
    SvcBase --> Bluetooth
    SvcBase --> Notification
    SvcBase --> Tray
    SvcBase --> Hypr

    click Audio "https://github.com/fabric-development/fabric/blob/main/fabric/audio/service.py"
    click Bluetooth "https://github.com/fabric-development/fabric/blob/main/fabric/bluetooth/service.py"
    click Notification "https://github.com/fabric-development/fabric/blob/main/fabric/notifications/service.py"
    click Tray "https://github.com/fabric-development/fabric/blob/main/fabric/system_tray/service.py"
    click Hypr "https://github.com/fabric-development/fabric/blob/main/fabric/hyprland/service.py"

    subgraph "DBus Layer"
        XML["XML Interface Definitions\n(fabric/dbus_assets/)"]:::dbus
        DbusIface["GDBus Interfaces"]:::dbus
    end

    Audio -->|"register via XML"| XML
    Bluetooth -->|"register via XML"| XML
    Notification -->|"register via XML"| XML
    Tray -->|"register via XML"| XML
    Hypr -->|"register via XML"| XML
    XML --> DbusIface
    DbusIface --> Audio
    DbusIface --> Bluetooth
    DbusIface --> Notification
    DbusIface --> Tray
    DbusIface --> Hypr

    click XML "https://github.com/fabric-development/fabric/tree/main/fabric/dbus_assets/"

    subgraph "Widgets"
        WidgetsLib["GTK Widget Library\n(fabric/widgets/)"]:::widget
    end

    Audio -->|"emit signals"| WidgetsLib
    Bluetooth -->|"emit signals"| WidgetsLib
    Notification -->|"emit signals"| WidgetsLib
    Tray -->|"emit signals"| WidgetsLib
    Hypr -->|"emit signals"| WidgetsLib

    click WidgetsLib "https://github.com/fabric-development/fabric/tree/main/fabric/widgets/"

    subgraph "External Systems"
        Compositor["X11/Wayland Compositor"]:::external
        DBusDaemon["System D-Bus Daemon"]:::external
        OSAudio["PulseAudio/ALSA"]:::external
        BlueZ["BlueZ"]:::external
        DesktopNotif["Desktop Notifications"]:::external
    end

    Audio -->|"connects"| OSAudio
    Bluetooth -->|"connects"| BlueZ
    Notification -->|"connects"| DesktopNotif
    Tray -->|"connects"| Compositor
    Hypr -->|"connects"| Compositor
    Audio -->|"via D-Bus"| DBusDaemon
    Bluetooth -->|"via D-Bus"| DBusDaemon
    Notification -->|"via D-Bus"| DBusDaemon
    Tray -->|"via D-Bus"| DBusDaemon
    Hypr -->|"via D-Bus"| DBusDaemon

    subgraph "User & Packaging"
        Examples["Example Configurations\n(examples/)"]:::aux
        Utils["Utility Helpers\n(fabric/utils/helpers.py)"]:::core
        Packaging["Packaging & Build Scripts"]:::aux
    end

    Examples --> CLI
    Utils --> App
    Packaging -.-> CLI

    click Examples "https://github.com/fabric-development/fabric/tree/main/examples/"
    click Utils "https://github.com/fabric-development/fabric/blob/main/fabric/utils/helpers.py"
    click Packaging "https://github.com/fabric-development/fabric/blob/main/setup.py"
    click Packaging "https://github.com/fabric-development/fabric/blob/main/pyproject.toml"
    click Packaging "https://github.com/fabric-development/fabric/blob/main/requirements.txt"
    click Packaging "https://github.com/fabric-development/fabric/blob/main/default.nix"
    click Packaging "https://github.com/fabric-development/fabric/blob/main/flake.nix"
    click Packaging "https://github.com/fabric-development/fabric/tree/main/scripts/"

    classDef core fill:#E8F4FD,stroke:#1E90FF,color:#000
    classDef service fill:#FFF5E5,stroke:#FFA500,color:#000
    classDef dbus fill:#F0EFEF,stroke:#999,color:#000
    classDef widget fill:#E8FFE8,stroke:#32CD32,color:#000
    classDef external fill:#F5F5F5,stroke:#666,color:#000
    classDef aux fill:#F9E8F9,stroke:#C71585,color:#000
```
