# exs-lab/exs-shell architecture

> Architecture diagram of the GitHub repository exs-lab/exs-shell, 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-shell
- Repository: https://github.com/exs-lab/exs-shell
- Video tour (about a minute): https://gitdiagram.com/exs-lab/exs-shell/video

## Overview

exs-shell is a GTK4 desktop shell for the Niri Wayland compositor. Its main runtime brings up system services and shell UI; users interact through shell surfaces or issue optional IPC commands that the running process dispatches. The tree and sampled code support the service registry, MPRIS controller, settings/configuration interaction, and IPC dispatch. Other listed UI modules are documented by their paths, but their internal wiring was not sampled, so those connections are intentionally not inferred.

Main entry points: [`exs_shell/app/init/before/services.py`](https://github.com/exs-lab/exs-shell/blob/main/exs_shell/app/init/before/services.py) (Desktop services), [`exs_shell/controllers/ipc/server.py`](https://github.com/exs-lab/exs-shell/blob/main/exs_shell/controllers/ipc/server.py) (IPC server), [`exs_shell/state`](https://github.com/exs-lab/exs-shell/tree/main/exs_shell/state) (Shared service state), [`exs_shell/cli`](https://github.com/exs-lab/exs-shell/tree/main/exs_shell/cli) (exs CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Startup and IPC"]
  node_cli["exs CLI"]
  node_ipcserver["IPC server<br/>[server.py]"]
end

subgraph group_services["System services"]
  node_serviceinit["Service initialization<br/>[services.py]"]
  node_systemservices["Desktop services<br/>[services.py]"]
  node_appearancesvc["Appearance service<br/>[appearance.py]"]
  node_idlesvc["Idle service<br/>[idle.py]"]
  node_battery["Battery tracker<br/>[battery_tracker.py]"]
end

subgraph group_surfaces["Shell surfaces"]
  node_bar["Bar and widgets"]
  node_launcher["Launcher"]
  node_controlcenter["Control center"]
  node_mpris["Media controller<br/>[controller.py]"]
  node_notifications["Notifications"]
  node_osd["On-screen display"]
  node_workspaces["Workspaces"]
end

subgraph group_settings["Settings and state"]
  node_settingsui["Settings UI"]
  node_settingsconfig["User configuration"]
end

subgraph group_internal["Runtime infrastructure"]
  node_commands["Command registry"]
  node_startup["Application startup"]
  node_stateservices["Shared service state"]
end

node_user(("Desktop user"))
node_niri(("Niri compositor"))
node_externaldesktop(("Desktop system"))

node_user -->|"issues command"| node_cli
node_cli -->|"sends IPC"| node_ipcserver
node_ipcserver -->|"looks up command"| node_commands
node_ipcserver -->|"dispatches command"| node_commands
node_startup -->|"initializes services"| node_serviceinit
node_serviceinit -->|"gets defaults"| node_systemservices
node_serviceinit -->|"gets default"| node_appearancesvc
node_systemservices -->|"stores services"| node_stateservices
node_appearancesvc -->|"stores service"| node_stateservices
node_niri -->|"provides compositor service"| node_systemservices
node_externaldesktop -->|"provides desktop data"| node_systemservices
node_stateservices -->|"provides MPRIS"| node_mpris
node_user -->|"changes preferences"| node_settingsui
node_settingsui -->|"updates options"| node_settingsconfig
node_user -->|"interacts"| node_bar
node_user -->|"interacts"| node_launcher
node_user -->|"interacts"| node_controlcenter
node_user -->|"views alerts"| node_notifications
node_user -->|"views status"| node_osd
node_user -->|"switches workspace"| node_workspaces

click node_cli "https://github.com/exs-lab/exs-shell/tree/main/exs_shell/cli"
click node_ipcserver "https://github.com/exs-lab/exs-shell/blob/main/exs_shell/controllers/ipc/server.py"
click node_commands "https://github.com/exs-lab/exs-shell/tree/main/exs_shell/state"
click node_startup "https://github.com/exs-lab/exs-shell/tree/main/exs_shell/app/init"
click node_serviceinit "https://github.com/exs-lab/exs-shell/blob/main/exs_shell/app/init/before/services.py"
click node_stateservices "https://github.com/exs-lab/exs-shell/tree/main/exs_shell/state"
click node_systemservices "https://github.com/exs-lab/exs-shell/blob/main/exs_shell/app/init/before/services.py"
click node_appearancesvc "https://github.com/exs-lab/exs-shell/blob/main/exs_shell/ui/services/appearance.py"
click node_idlesvc "https://github.com/exs-lab/exs-shell/blob/main/exs_shell/ui/services/idle.py"
click node_battery "https://github.com/exs-lab/exs-shell/blob/main/exs_shell/ui/services/battery_tracker.py"
click node_bar "https://github.com/exs-lab/exs-shell/tree/main/exs_shell/ui/modules/bar"
click node_launcher "https://github.com/exs-lab/exs-shell/tree/main/exs_shell/ui/modules/launcher"
click node_controlcenter "https://github.com/exs-lab/exs-shell/tree/main/exs_shell/ui/modules/control_center"
click node_mpris "https://github.com/exs-lab/exs-shell/blob/main/exs_shell/ui/modules/control_center/inners/controllers/mpris/controller.py"
click node_notifications "https://github.com/exs-lab/exs-shell/tree/main/exs_shell/ui/modules/notification"
click node_osd "https://github.com/exs-lab/exs-shell/tree/main/exs_shell/ui/modules/osd"
click node_workspaces "https://github.com/exs-lab/exs-shell/tree/main/exs_shell/ui/modules/workspaces"
click node_settingsui "https://github.com/exs-lab/exs-shell/tree/main/exs_shell/ui/modules/settings"
click node_settingsconfig "https://github.com/exs-lab/exs-shell/tree/main/exs_shell/configs/user"

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_cli,node_ipcserver,node_user toneBlue
class node_serviceinit,node_systemservices,node_appearancesvc,node_idlesvc,node_battery toneAmber
class node_bar,node_launcher,node_controlcenter,node_mpris,node_notifications,node_osd,node_workspaces toneMint
class node_settingsui,node_settingsconfig toneRose
class node_commands,node_startup,node_stateservices,node_niri,node_externaldesktop toneIndigo
```

## Components

### Startup and IPC

- [exs CLI](https://github.com/exs-lab/exs-shell/tree/main/exs_shell/cli): `exs_shell/cli`
- [IPC server](https://github.com/exs-lab/exs-shell/blob/main/exs_shell/controllers/ipc/server.py): `exs_shell/controllers/ipc/server.py`

### System services

- [Service initialization](https://github.com/exs-lab/exs-shell/blob/main/exs_shell/app/init/before/services.py): `exs_shell/app/init/before/services.py`
- [Desktop services](https://github.com/exs-lab/exs-shell/blob/main/exs_shell/app/init/before/services.py): `exs_shell/app/init/before/services.py`
- [Appearance service](https://github.com/exs-lab/exs-shell/blob/main/exs_shell/ui/services/appearance.py): `exs_shell/ui/services/appearance.py`
- [Idle service](https://github.com/exs-lab/exs-shell/blob/main/exs_shell/ui/services/idle.py): `exs_shell/ui/services/idle.py`
- [Battery tracker](https://github.com/exs-lab/exs-shell/blob/main/exs_shell/ui/services/battery_tracker.py): `exs_shell/ui/services/battery_tracker.py`

### Shell surfaces

- [Bar and widgets](https://github.com/exs-lab/exs-shell/tree/main/exs_shell/ui/modules/bar): `exs_shell/ui/modules/bar`
- [Launcher](https://github.com/exs-lab/exs-shell/tree/main/exs_shell/ui/modules/launcher): `exs_shell/ui/modules/launcher`
- [Control center](https://github.com/exs-lab/exs-shell/tree/main/exs_shell/ui/modules/control_center): `exs_shell/ui/modules/control_center`
- [Media controller](https://github.com/exs-lab/exs-shell/blob/main/exs_shell/ui/modules/control_center/inners/controllers/mpris/controller.py): `exs_shell/ui/modules/control_center/inners/controllers/mpris/controller.py`
- [Notifications](https://github.com/exs-lab/exs-shell/tree/main/exs_shell/ui/modules/notification): `exs_shell/ui/modules/notification`
- [On-screen display](https://github.com/exs-lab/exs-shell/tree/main/exs_shell/ui/modules/osd): `exs_shell/ui/modules/osd`
- [Workspaces](https://github.com/exs-lab/exs-shell/tree/main/exs_shell/ui/modules/workspaces): `exs_shell/ui/modules/workspaces`

### Settings and state

- [Settings UI](https://github.com/exs-lab/exs-shell/tree/main/exs_shell/ui/modules/settings): `exs_shell/ui/modules/settings`
- [User configuration](https://github.com/exs-lab/exs-shell/tree/main/exs_shell/configs/user): `exs_shell/configs/user`

### Runtime infrastructure

- [Command registry](https://github.com/exs-lab/exs-shell/tree/main/exs_shell/state): `exs_shell/state`
- [Application startup](https://github.com/exs-lab/exs-shell/tree/main/exs_shell/app/init): `exs_shell/app/init`
- [Shared service state](https://github.com/exs-lab/exs-shell/tree/main/exs_shell/state): `exs_shell/state`

### Other components

- **Desktop user**
- **Niri compositor**
- **Desktop system**

## Connections

- Desktop user → exs CLI: issues command
- exs CLI → IPC server: sends IPC
- IPC server → Command registry: looks up command
- IPC server → Command registry: dispatches command
- Application startup → Service initialization: initializes services
- Service initialization → Desktop services: gets defaults
- Service initialization → Appearance service: gets default
- Desktop services → Shared service state: stores services
- Appearance service → Shared service state: stores service
- Niri compositor → Desktop services: provides compositor service
- Desktop system → Desktop services: provides desktop data
- Shared service state → Media controller: provides MPRIS
- Desktop user → Settings UI: changes preferences
- Settings UI → User configuration: updates options
- Desktop user → Bar and widgets: interacts
- Desktop user → Launcher: interacts
- Desktop user → Control center: interacts
- Desktop user → Notifications: views alerts
- Desktop user → On-screen display: views status
- Desktop user → Workspaces: switches workspace