# exs-lab/exs-core architecture

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

- Interactive diagram: https://gitdiagram.com/exs-lab/exs-core
- Repository: https://github.com/exs-lab/exs-core

## Overview

exs-core is a Python support library for exs-shell and its plugins, rather than a standalone shell application. Its principal workflow is plugin validation and loading, followed by plugins registering services, settings, event handlers, and IPC commands for the shell to use. It also provides GTK window/settings widgets, compositor access, and Linux desktop/system utilities. The README is absent and source excerpts are partial, so links among unsampled modules are limited to documented or directly evidenced relationships.

Main entry points: [`libexs/utils/plugin.py`](https://github.com/exs-lab/exs-core/blob/main/libexs/utils/plugin.py) (Plugin Loader), [`libexs/_state.py`](https://github.com/exs-lab/exs-core/blob/main/libexs/_state.py) (Shared State), [`libexs/register/events/connectors.py`](https://github.com/exs-lab/exs-core/blob/main/libexs/register/events/connectors.py) (Event Connectors), [`libexs/settings/widgets.py`](https://github.com/exs-lab/exs-core/blob/main/libexs/settings/widgets.py) (Settings Widgets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_plugins["Plugin Runtime"]
  node_plugin_loader["Plugin Loader<br/>[plugin.py]"]
  node_shared_state["Shared State<br/>[_state.py]"]
  node_event_connectors["Event Connectors<br/>[connectors.py]"]
  node_command_registry["Command Registry<br/>[cmd.py]"]
  node_event_base["Event Registration<br/>[base.py]"]
end

subgraph group_ui["GTK Interface"]
  node_settings_api["Settings API<br/>[base.py]"]
  node_settings_widgets["Settings Widgets<br/>[widgets.py]"]
  node_widget_base["Widget Base<br/>[base.py]"]
  node_window_widgets["Window Widgets<br/>[window.py]"]
  node_icon_widget["Icon Widget<br/>[icon.py]"]
end

subgraph group_desktop["Desktop Integration"]
  node_compositor_service["Compositor Service<br/>[service.py]"]
  node_compositor_api["Compositor Interface<br/>[abc_core.py]"]
  node_compositor_adapters["Compositor Adapters"]
  node_desktop_services["Shell Services"]
end

subgraph group_utilities["System Utilities"]
  node_system_utils["System Monitoring<br/>[system.py]"]
  node_other_utils["Desktop Utilities"]
end

node_plugin_author(("Plugin"))
node_shell(("exs-shell"))
node_linux(("Linux Desktop"))
node_ignis["Ignis GTK"]

node_plugin_author -->|"provides plugin"| node_plugin_loader
node_plugin_loader -->|"registers services"| node_shared_state
node_plugin_loader -->|"registers settings"| node_settings_api
node_plugin_loader -->|"loads plugin"| node_shell
node_shell -->|"registers commands"| node_command_registry
node_command_registry -->|"stores commands"| node_shared_state
node_event_connectors -->|"resolves services"| node_shared_state
node_event_connectors -->|"uses connectors"| node_event_base
node_settings_widgets -->|"creates dialogs"| node_window_widgets
node_settings_widgets -->|"builds controls"| node_widget_base
node_window_widgets -->|"extends windows"| node_ignis
node_widget_base -->|"extends widgets"| node_ignis
node_compositor_service -->|"calls interface"| node_compositor_api
node_compositor_adapters -->|"implement interface"| node_compositor_api
node_compositor_service -->|"exposes state"| node_shell
node_system_utils -->|"reads system data"| node_linux
node_other_utils -->|"uses desktop facilities"| node_linux
node_plugin_loader -->|"applies CSS"| node_ignis
node_shared_state -->|"holds references"| node_desktop_services

click node_plugin_loader "https://github.com/exs-lab/exs-core/blob/main/libexs/utils/plugin.py"
click node_shared_state "https://github.com/exs-lab/exs-core/blob/main/libexs/_state.py"
click node_event_connectors "https://github.com/exs-lab/exs-core/blob/main/libexs/register/events/connectors.py"
click node_command_registry "https://github.com/exs-lab/exs-core/blob/main/libexs/register/cmd.py"
click node_event_base "https://github.com/exs-lab/exs-core/blob/main/libexs/register/events/base.py"
click node_settings_api "https://github.com/exs-lab/exs-core/blob/main/libexs/settings/base.py"
click node_settings_widgets "https://github.com/exs-lab/exs-core/blob/main/libexs/settings/widgets.py"
click node_widget_base "https://github.com/exs-lab/exs-core/blob/main/libexs/widgets/base.py"
click node_window_widgets "https://github.com/exs-lab/exs-core/blob/main/libexs/widgets/window.py"
click node_icon_widget "https://github.com/exs-lab/exs-core/blob/main/libexs/widgets/icon.py"
click node_compositor_service "https://github.com/exs-lab/exs-core/blob/main/libexs/compositor/service.py"
click node_compositor_api "https://github.com/exs-lab/exs-core/blob/main/libexs/compositor/abc_core.py"
click node_compositor_adapters "https://github.com/exs-lab/exs-core/tree/main/libexs/compositor/impl"
click node_system_utils "https://github.com/exs-lab/exs-core/blob/main/libexs/utils/system.py"
click node_other_utils "https://github.com/exs-lab/exs-core/tree/main/libexs/utils"

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_plugin_loader,node_shared_state,node_event_connectors,node_command_registry,node_event_base toneBlue
class node_settings_api,node_settings_widgets,node_widget_base,node_window_widgets,node_icon_widget toneAmber
class node_compositor_service,node_compositor_api,node_compositor_adapters,node_desktop_services toneMint
class node_system_utils,node_other_utils toneRose
class node_plugin_author,node_shell,node_linux,node_ignis toneIndigo
```

## Components

### Plugin Runtime

- [Plugin Loader](https://github.com/exs-lab/exs-core/blob/main/libexs/utils/plugin.py): `libexs/utils/plugin.py`
- [Shared State](https://github.com/exs-lab/exs-core/blob/main/libexs/_state.py): `libexs/_state.py`
- [Event Connectors](https://github.com/exs-lab/exs-core/blob/main/libexs/register/events/connectors.py): `libexs/register/events/connectors.py`
- [Command Registry](https://github.com/exs-lab/exs-core/blob/main/libexs/register/cmd.py): `libexs/register/cmd.py`
- [Event Registration](https://github.com/exs-lab/exs-core/blob/main/libexs/register/events/base.py): `libexs/register/events/base.py`

### GTK Interface

- [Settings API](https://github.com/exs-lab/exs-core/blob/main/libexs/settings/base.py): `libexs/settings/base.py`
- [Settings Widgets](https://github.com/exs-lab/exs-core/blob/main/libexs/settings/widgets.py): `libexs/settings/widgets.py`
- [Widget Base](https://github.com/exs-lab/exs-core/blob/main/libexs/widgets/base.py): `libexs/widgets/base.py`
- [Window Widgets](https://github.com/exs-lab/exs-core/blob/main/libexs/widgets/window.py): `libexs/widgets/window.py`
- [Icon Widget](https://github.com/exs-lab/exs-core/blob/main/libexs/widgets/icon.py): `libexs/widgets/icon.py`

### Desktop Integration

- [Compositor Service](https://github.com/exs-lab/exs-core/blob/main/libexs/compositor/service.py): `libexs/compositor/service.py`
- [Compositor Interface](https://github.com/exs-lab/exs-core/blob/main/libexs/compositor/abc_core.py): `libexs/compositor/abc_core.py`
- [Compositor Adapters](https://github.com/exs-lab/exs-core/tree/main/libexs/compositor/impl): `libexs/compositor/impl`
- **Shell Services**

### System Utilities

- [System Monitoring](https://github.com/exs-lab/exs-core/blob/main/libexs/utils/system.py): `libexs/utils/system.py`
- [Desktop Utilities](https://github.com/exs-lab/exs-core/tree/main/libexs/utils): `libexs/utils`

### Other components

- **Plugin**
- **exs-shell**
- **Linux Desktop**
- **Ignis GTK**

## Connections

- Plugin → Plugin Loader: provides plugin
- Plugin Loader → Shared State: registers services
- Plugin Loader → Settings API: registers settings
- Plugin Loader → exs-shell: loads plugin
- exs-shell → Command Registry: registers commands
- Command Registry → Shared State: stores commands
- Event Connectors → Shared State: resolves services
- Event Connectors → Event Registration: uses connectors
- Settings Widgets → Window Widgets: creates dialogs
- Settings Widgets → Widget Base: builds controls
- Window Widgets → Ignis GTK: extends windows
- Widget Base → Ignis GTK: extends widgets
- Compositor Service → Compositor Interface: calls interface
- Compositor Adapters → Compositor Interface: implement interface
- Compositor Service → exs-shell: exposes state
- System Monitoring → Linux Desktop: reads system data
- Desktop Utilities → Linux Desktop: uses desktop facilities
- Plugin Loader → Ignis GTK: applies CSS
- Shared State → Shell Services: holds references