# aunetx/blur-my-shell architecture

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

- Interactive diagram: https://gitdiagram.com/aunetx/blur-my-shell
- Repository: https://github.com/aunetx/blur-my-shell

## Overview

This project is a GNOME Shell extension that “blurs” various parts of the GNOME Shell interface, including the panel, dash, overview, lockscreen, and even elements of other extensions. In other words, it injects custom visual effects into the GNOME Shell by processing static images or dynamic content through a configurable pipeline of blur effects and related visual modifications.

##### Main Components
- Extension Core – The entry point is located in “src/extension.js” which initializes the extension and ties together the various modules.
- UI Components – Under “src/components” you have JavaScript files for areas such as “appfolders.js”, “applications.js”, “dash_to_dock.js”, “overview.js”, “panel.js”, etc. These files represent the different regions of the GNOME Shell that the extension enhances.
- Effects Engine – In “src/effects”, you have GLSL (shader) files alongside their corresponding JavaScript wrappers (e.g., gaussian_blur, Monte Carlo blur, pixelize). This is where the image processing is implemented, forming the “pipeline” through which the blur effects are applied.
- Preferences & Pipeline Configuration – The “src/preferences” folder contains the UI logic for configuring how the effects are applied such as toggling between static and dynamic blur, managing the list of effects (pipelines) and additional visual settings.
- Common Utilities – The “src/conveniences” subdirectory provides helper modules for settings handling, pipeline management, and other essential utilities used throughout the extension.
- DBus Integration – Under “src/dbus” there are modules (client, services, and an iface.xml) which indicate that the extension exposes or consumes DBus services to interact with other components of the GNOME environment.
- Localization – The “po” directory contains a multitude of translation files (in various languages) that tie into the internationalization of the extension.
- Build & Documentation – Files like the Makefile, README.md, and metadata.json tie everything together, instructing on build, installation, and usage.

##### Relationships and Interactions
- The Core (extension.js) is the orchestrator that loads UI components, initializes the effects pipeline, and connects the preferences.
- Each UI component (from “src/components”) leverages the effects engine modules (from “src/effects”) and the utilities (from “src/conveniences”) to apply either static or dynamic blur effects.
- The preferences modules in “src/preferences” provide a user interface for tweaking these pipelines and effects. They interact with the core logic to update settings which in turn affect the UI components.
- The DBus module in “src/dbus” is responsible for handling or broadcasting messages between the extension and GNOME Shell services (or for integration with other extensions, as indicated by compatibility considerations with “Dash to Dock”, “Dash to Panel”, etc.).
- The settings, as defined in the GSettings schemas, are read and written by both the utilities and preferences, and may be used to modulate the effects dynamically on the GNOME Shell.

##### Architectural Patterns and Key Design Principles
- Modularity – The code is organized into clear modules (UI, effects, preferences, DBus, utilities) which simplifies testing and future maintenance.
- Separation of Concerns – The pipeline for image processing is decoupled from the UI components and settings management, enhancing flexibility.
- Extensibility – Inherent to the design is the ability to add or refine effects pipelines; new effects can be introduced without modifying the core logic.
- Localization Support – Full internationalization is provided through the “po” translations.
- Integration with External Components – The extension is designed to work harmoniously with other GNOME Shell extensions by interfacing with common GNOME Shell APIs and DBus services.

##### Final Recommendations for the Principal Software Engineer
- Because this is a GNOME Shell extension, indicate its integration point with GNOME Shell and any interoperability with other extensions as mentioned in the README.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% GNOME Shell Environment
    subgraph "GNOME Shell Environment"
        SN["GNOME Shell Interface"]:::external
    end

    %% Blur my Shell Extension Module
    subgraph "Blur my Shell Extension"
        EC["Extension Core"]:::core
        UIC["UI Components"]:::ui
        EE["Effects Engine"]:::effects
        PR["Preferences & Pipeline Configuration"]:::prefs
        UT["Common Utilities"]:::utils
        DB["DBus Integration"]:::dbus
        RES["Resources"]:::res
        SCH["Schemas"]:::res
        L10N["Localization"]:::local
        BD["Build & Documentation"]:::docs
    end

    %% Effects Pipeline Details (branching from Effects Engine)
    WI["Wallpaper Image"]:::effects
    SP["Static Pipeline"]:::effects
    RUI["Rendered UI Element"]:::ui
    CW["Current Window Content"]:::effects
    DP["Dynamic Pipeline"]:::effects
    UO["UI Overlay"]:::ui

    %% Connections: GNOME Shell Integration
    SN -->|"loads"| EC

    %% Core orchestrates modules
    EC -->|"initializes"| UIC
    EC -->|"initializes"| EE
    EC -->|"configures"| PR
    EC -->|"utilizes"| UT
    EC -->|"communicates"| DB

    %% Preferences interactions
    PR -->|"updates"| EC
    PR -->|"reads/writes"| UT

    %% UI Components interactions
    UIC -->|"applies effects"| EE
    UIC -->|"uses"| UT
    UIC -->|"consumes"| RES
    UIC <-->|"DBus messages"| DB

    %% Resource and Schema consumption
    PR -->|"consumes"| RES
    PR -->|"reads settings"| SCH
    UT -->|"reads settings"| SCH

    %% Effects Pipeline flows
    EE -->|"processes static"| WI
    WI --> SP
    SP -->|"produces"| RUI
    EE -->|"processes dynamic"| CW
    CW --> DP
    DP -->|"produces"| UO

    %% UI consumes effects outputs
    RUI -->|"integrated into"| UIC
    UO -->|"integrated into"| UIC

    %% Click Events
    click EC "https://github.com/aunetx/blur-my-shell/blob/master/src/extension.js"
    click UIC "https://github.com/aunetx/blur-my-shell/tree/master/src/components"
    click EE "https://github.com/aunetx/blur-my-shell/tree/master/src/effects"
    click PR "https://github.com/aunetx/blur-my-shell/tree/master/src/preferences"
    click UT "https://github.com/aunetx/blur-my-shell/tree/master/src/conveniences"
    click DB "https://github.com/aunetx/blur-my-shell/tree/master/src/dbus"
    click RES "https://github.com/aunetx/blur-my-shell/tree/master/resources"
    click SCH "https://github.com/aunetx/blur-my-shell/blob/master/schemas/org.gnome.shell.extensions.blur-my-shell.gschema.xml"
    click L10N "https://github.com/aunetx/blur-my-shell/tree/master/po"
    click BD "https://github.com/aunetx/blur-my-shell/tree/master/Makefile"

    %% Styles
    classDef core fill:#f9d5e5,stroke:#bd4f6c,stroke-width:2px;
    classDef ui fill:#d5f9e5,stroke:#4fbdb6,stroke-width:2px;
    classDef effects fill:#e5d5f9,stroke:#8f4fb1,stroke-width:2px;
    classDef prefs fill:#f9f3d5,stroke:#b8a21d,stroke-width:2px;
    classDef utils fill:#e5f9d5,stroke:#6fb24f,stroke-width:2px;
    classDef dbus fill:#d5e5f9,stroke:#4f6fb1,stroke-width:2px;
    classDef res fill:#f9e5d5,stroke:#b16f4f,stroke-width:2px;
    classDef local fill:#d5f9f3,stroke:#4fbab1,stroke-width:2px;
    classDef docs fill:#f9d5d5,stroke:#b64f6f,stroke-width:2px;
    classDef external fill:#d5d5ff,stroke:#0000ff,stroke-width:2px;
```
