# xenlism/gnome-widget-center architecture

> Architecture diagram of the GitHub repository xenlism/gnome-widget-center, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xenlism/gnome-widget-center
- Repository: https://github.com/xenlism/gnome-widget-center

## Overview

GNOME Widget Center is a GNOME Shell extension for placing and configuring live desktop widgets. The main workflow begins in the Control Center or overlay, discovers and loads widget instances, renders them on the desktop, and lets users arrange them with drag, snapping, and monitor-aware layout before saving configuration. It also supports theme-pack sharing, encrypted backups, custom and architect-created widgets, styling, and localized interfaces. The README documents these capabilities; sampled source confirms the extension’s wiring and selected layout, storage, preferences, and drag behavior, but not every subsystem’s internal calls.

Main entry points: [`gnome-widget-center@xenlism.github.io/extension.js`](https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/extension.js) (Extension lifecycle), [`gnome-widget-center@xenlism.github.io/lib/prefsWindowController.js`](https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/lib/prefsWindowController.js) (Preferences controller), [`gnome-widget-center@xenlism.github.io/lib/widgetLoader.js`](https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/lib/widgetLoader.js) (Widget loader), [`gnome-widget-center@xenlism.github.io/lib/storageService.js`](https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/lib/storageService.js) (Layout and settings files)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Shell runtime"]
  node_extension["Extension lifecycle<br/>[extension.js]"]
  node_widgetloader["Widget loader<br/>[widgetLoader.js]"]
  node_widgetlayer["Desktop widget layer<br/>[widgetLayer.js]"]
  node_widgets["Widget collection<br/>[widget.js]"]
  node_overlay["Widget overlay"]
  node_drag["Quick drag<br/>[dragController.js]"]
  node_editdrag["Edit-mode drag"]
  node_layout["Layout rules<br/>[layoutEngine.js]"]
  node_snap["Snap and grid<br/>[snapManager.js]"]
end

subgraph group_management["Widget management"]
  node_prefs["Control Center<br/>[prefs.js]"]
  node_prefscontroller["Preferences controller"]
  node_widgetlist["Widget discovery<br/>[prefsWidgetList.js]"]
  node_widgetconfig["Widget configuration<br/>[widgetConfigUI.js]"]
  node_userfiles[("User widget files<br/>[widgetLoader.js]")]
end

subgraph group_sharing["Portable setups"]
  node_themes["Theme packs<br/>[themeService.js]"]
  node_themeexport["Theme export"]
  node_backup["Backup and restore<br/>[backupService.js]"]
  node_screenshot["Screenshot capture"]
end

subgraph group_foundation["Settings and interface"]
  node_storage[("Layout and settings files<br/>[storageService.js]")]
  node_settings["Settings service<br/>[settingsService.js]"]
  node_translations["Translations<br/>[index.js]"]
end

node_user(("Desktop user"))
node_shell["GNOME Shell"]

node_user -->|"opens and configures"| node_prefs
node_user -->|"opens"| node_overlay
node_prefs -->|"builds interface"| node_prefscontroller
node_prefscontroller -->|"discovers widgets"| node_widgetlist
node_prefscontroller -->|"loads translations"| node_translations
node_prefscontroller -->|"initializes storage"| node_storage
node_prefscontroller -->|"configures widgets"| node_widgetconfig
node_extension -->|"loads instances"| node_widgetloader
node_extension -->|"initializes layer"| node_widgetlayer
node_extension -->|"creates layout rules"| node_layout
node_extension -->|"creates drag controller"| node_drag
node_extension -->|"creates overlay"| node_overlay
node_extension -->|"persists layout"| node_storage
node_widgetloader -->|"loads widget code"| node_widgets
node_widgetloader -->|"reads widget settings"| node_storage
node_widgetlayer -->|"adds desktop actors"| node_shell
node_drag -->|"checks placement"| node_layout
node_editdrag -->|"snaps placement"| node_snap
node_editdrag -->|"checks placement"| node_layout
node_editdrag -->|"saves positions"| node_storage
node_extension -->|"applies theme packs"| node_themes
node_prefscontroller -->|"opens export dialog"| node_themeexport
node_themeexport -->|"captures preview"| node_screenshot
node_user -->|"backs up or restores"| node_backup
node_widgetloader -->|"loads installed widgets"| node_userfiles

click node_extension "https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/extension.js"
click node_widgetloader "https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/lib/widgetLoader.js"
click node_widgetlayer "https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/lib/shell/widgetLayer.js"
click node_widgets "https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/widgets/settings-control/widget.js"
click node_overlay "https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/lib/shell/widgetCenterOverlay.js"
click node_drag "https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/lib/shell/dragController.js"
click node_editdrag "https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/lib/shell/editModeDragController.js"
click node_layout "https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/lib/layoutEngine.js"
click node_snap "https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/lib/snapManager.js"
click node_prefs "https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/prefs.js"
click node_prefscontroller "https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/lib/prefsWindowController.js"
click node_widgetlist "https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/lib/prefsWidgetList.js"
click node_widgetconfig "https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/lib/widgetConfigUI.js"
click node_storage "https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/lib/storageService.js"
click node_settings "https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/lib/settingsService.js"
click node_translations "https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/i18n/index.js"
click node_themes "https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/lib/themeService.js"
click node_themeexport "https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/lib/themePackExportDialog.js"
click node_backup "https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/lib/backupService.js"
click node_screenshot "https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/lib/screenshotPortal.js"
click node_userfiles "https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/lib/widgetLoader.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_extension,node_widgetloader,node_widgetlayer,node_widgets,node_overlay,node_drag,node_editdrag,node_layout,node_snap,node_user toneBlue
class node_prefs,node_prefscontroller,node_widgetlist,node_widgetconfig,node_userfiles toneAmber
class node_themes,node_themeexport,node_backup,node_screenshot toneMint
class node_storage,node_settings,node_translations toneRose
class node_shell toneIndigo
```

## Components

### Shell runtime

- [Extension lifecycle](https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/extension.js): `gnome-widget-center@xenlism.github.io/extension.js`
- [Widget loader](https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/lib/widgetLoader.js): `gnome-widget-center@xenlism.github.io/lib/widgetLoader.js`
- [Desktop widget layer](https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/lib/shell/widgetLayer.js): `gnome-widget-center@xenlism.github.io/lib/shell/widgetLayer.js`
- [Widget collection](https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/widgets/settings-control/widget.js): `gnome-widget-center@xenlism.github.io/widgets/settings-control/widget.js`
- [Widget overlay](https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/lib/shell/widgetCenterOverlay.js): `gnome-widget-center@xenlism.github.io/lib/shell/widgetCenterOverlay.js`
- [Quick drag](https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/lib/shell/dragController.js): `gnome-widget-center@xenlism.github.io/lib/shell/dragController.js`
- [Edit-mode drag](https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/lib/shell/editModeDragController.js): `gnome-widget-center@xenlism.github.io/lib/shell/editModeDragController.js`
- [Layout rules](https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/lib/layoutEngine.js): `gnome-widget-center@xenlism.github.io/lib/layoutEngine.js`
- [Snap and grid](https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/lib/snapManager.js): `gnome-widget-center@xenlism.github.io/lib/snapManager.js`

### Widget management

- [Control Center](https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/prefs.js): `gnome-widget-center@xenlism.github.io/prefs.js`
- [Preferences controller](https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/lib/prefsWindowController.js): `gnome-widget-center@xenlism.github.io/lib/prefsWindowController.js`
- [Widget discovery](https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/lib/prefsWidgetList.js): `gnome-widget-center@xenlism.github.io/lib/prefsWidgetList.js`
- [Widget configuration](https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/lib/widgetConfigUI.js): `gnome-widget-center@xenlism.github.io/lib/widgetConfigUI.js`
- [User widget files](https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/lib/widgetLoader.js): `gnome-widget-center@xenlism.github.io/lib/widgetLoader.js`

### Portable setups

- [Theme packs](https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/lib/themeService.js): `gnome-widget-center@xenlism.github.io/lib/themeService.js`
- [Theme export](https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/lib/themePackExportDialog.js): `gnome-widget-center@xenlism.github.io/lib/themePackExportDialog.js`
- [Backup and restore](https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/lib/backupService.js): `gnome-widget-center@xenlism.github.io/lib/backupService.js`
- [Screenshot capture](https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/lib/screenshotPortal.js): `gnome-widget-center@xenlism.github.io/lib/screenshotPortal.js`

### Settings and interface

- [Layout and settings files](https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/lib/storageService.js): `gnome-widget-center@xenlism.github.io/lib/storageService.js`
- [Settings service](https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/lib/settingsService.js): `gnome-widget-center@xenlism.github.io/lib/settingsService.js`
- [Translations](https://github.com/xenlism/gnome-widget-center/blob/main/gnome-widget-center%40xenlism.github.io/i18n/index.js): `gnome-widget-center@xenlism.github.io/i18n/index.js`

### Other components

- **Desktop user**
- **GNOME Shell**

## Connections

- Desktop user → Control Center: opens and configures
- Desktop user → Widget overlay: opens
- Control Center → Preferences controller: builds interface
- Preferences controller → Widget discovery: discovers widgets
- Preferences controller → Translations: loads translations
- Preferences controller → Layout and settings files: initializes storage
- Preferences controller → Widget configuration: configures widgets
- Extension lifecycle → Widget loader: loads instances
- Extension lifecycle → Desktop widget layer: initializes layer
- Extension lifecycle → Layout rules: creates layout rules
- Extension lifecycle → Quick drag: creates drag controller
- Extension lifecycle → Widget overlay: creates overlay
- Extension lifecycle → Layout and settings files: persists layout
- Widget loader → Widget collection: loads widget code
- Widget loader → Layout and settings files: reads widget settings
- Desktop widget layer → GNOME Shell: adds desktop actors
- Quick drag → Layout rules: checks placement
- Edit-mode drag → Snap and grid: snaps placement
- Edit-mode drag → Layout rules: checks placement
- Edit-mode drag → Layout and settings files: saves positions
- Extension lifecycle → Theme packs: applies theme packs
- Preferences controller → Theme export: opens export dialog
- Theme export → Screenshot capture: captures preview
- Desktop user → Backup and restore: backs up or restores
- Widget loader → User widget files: loads installed widgets