# amanhex/ukishima architecture

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

- Interactive diagram: https://gitdiagram.com/amanhex/ukishima
- Repository: https://github.com/amanhex/ukishima

## Overview

Ukishima is a Quickshell widget shell for Hyprland. Its main interaction is a user opening a surface through Quickshell IPC; the shell presents the requested control, which reads or updates shared state and, where needed, interacts with desktop services. The README documents the capabilities and IPC entry point, while sampled source covers only selected utilities, so uncertain internal dispatch and integration wiring is omitted.

Main entry points: [`shell.qml`](https://github.com/amanhex/ukishima/blob/master/shell.qml) (IPC Shell), [`Singletons`](https://github.com/amanhex/ukishima/tree/master/Singletons) (Shell State), [`surfaces/Wallpaper.qml`](https://github.com/amanhex/ukishima/blob/master/surfaces/Wallpaper.qml) (Wallpaper), [`Singletons/Dyn.qml`](https://github.com/amanhex/ukishima/blob/master/Singletons/Dyn.qml) (Dynamic Theme)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shell["Shell UI"]
  node_ipc["IPC Shell<br/>[shell.qml]"]
  node_pill["Dynamic Pill<br/>[Pill.qml]"]
  node_dock["Dock<br/>[DockBar.qml]"]
end

subgraph group_surfaces["User Surfaces"]
  node_launcher["Launcher<br/>[Launcher.qml]"]
  node_wallpaper["Wallpaper<br/>[Wallpaper.qml]"]
  node_settings["Settings<br/>[Appearance.qml]"]
  node_media["Media Controls<br/>[Media.qml]"]
  node_system["System Controls<br/>[Power.qml]"]
  node_notifications["Notifications<br/>[Toast.qml]"]
  node_lockscreen["Lock Screen<br/>[shell.qml]"]
end

subgraph group_state["Shared State"]
  node_singletons["Shell State"]
  node_config["Configuration<br/>[Config.qml]"]
  node_dyn["Dynamic Theme<br/>[Dyn.qml]"]
end

subgraph group_desktop["Desktop Integration"]
  node_palette["Palette Generator<br/>[wallcolors.py]"]
  node_monitorutil["Monitor Utilities<br/>[monitors.js]"]
end

node_user(("User"))
node_hyprland["Hyprland"]
node_walltools["Wallpaper Tools"]
node_quickshell["Quickshell IPC"]

node_user -->|"invokes IPC"| node_quickshell
node_quickshell -->|"dispatches to"| node_ipc
node_ipc -->|"presents"| node_pill
node_ipc -->|"opens"| node_launcher
node_ipc -->|"opens"| node_wallpaper
node_ipc -->|"opens"| node_settings
node_ipc -->|"opens"| node_media
node_ipc -->|"opens"| node_system
node_ipc -->|"opens"| node_notifications
node_pill -->|"reads state"| node_singletons
node_dock -->|"reads state"| node_singletons
node_settings -->|"updates settings"| node_config
node_wallpaper -->|"uses wallpaper state"| node_singletons
node_media -->|"uses player state"| node_singletons
node_system -->|"uses system state"| node_singletons
node_wallpaper -->|"generates palette"| node_palette
node_palette -->|"writes palette data"| node_dyn
node_dyn -->|"provides theme"| node_pill
node_dyn -->|"provides theme"| node_dock
node_lockscreen -.->|"locks session"| node_hyprland
node_monitorutil -->|"parses monitor data"| node_hyprland
node_wallpaper -.->|"uses wallpaper services"| node_walltools

click node_ipc "https://github.com/amanhex/ukishima/blob/master/shell.qml"
click node_pill "https://github.com/amanhex/ukishima/blob/master/Pill.qml"
click node_dock "https://github.com/amanhex/ukishima/blob/master/components/DockBar.qml"
click node_launcher "https://github.com/amanhex/ukishima/blob/master/surfaces/Launcher.qml"
click node_wallpaper "https://github.com/amanhex/ukishima/blob/master/surfaces/Wallpaper.qml"
click node_settings "https://github.com/amanhex/ukishima/blob/master/surfaces/Appearance.qml"
click node_media "https://github.com/amanhex/ukishima/blob/master/surfaces/Media.qml"
click node_system "https://github.com/amanhex/ukishima/blob/master/surfaces/Power.qml"
click node_notifications "https://github.com/amanhex/ukishima/blob/master/surfaces/Toast.qml"
click node_lockscreen "https://github.com/amanhex/ukishima/blob/master/lockscreen/shell.qml"
click node_singletons "https://github.com/amanhex/ukishima/tree/master/Singletons"
click node_config "https://github.com/amanhex/ukishima/blob/master/Singletons/Config.qml"
click node_dyn "https://github.com/amanhex/ukishima/blob/master/Singletons/Dyn.qml"
click node_palette "https://github.com/amanhex/ukishima/blob/master/scripts/wallcolors.py"
click node_monitorutil "https://github.com/amanhex/ukishima/blob/master/lib/monitors.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_ipc,node_pill,node_dock,node_user toneBlue
class node_launcher,node_wallpaper,node_settings,node_media,node_system,node_notifications,node_lockscreen toneAmber
class node_singletons,node_config,node_dyn toneMint
class node_palette,node_monitorutil toneRose
class node_hyprland,node_walltools,node_quickshell toneIndigo
```

## Components

### Shell UI

- [IPC Shell](https://github.com/amanhex/ukishima/blob/master/shell.qml): `shell.qml`
- [Dynamic Pill](https://github.com/amanhex/ukishima/blob/master/Pill.qml): `Pill.qml`
- [Dock](https://github.com/amanhex/ukishima/blob/master/components/DockBar.qml): `components/DockBar.qml`

### User Surfaces

- [Launcher](https://github.com/amanhex/ukishima/blob/master/surfaces/Launcher.qml): `surfaces/Launcher.qml`
- [Wallpaper](https://github.com/amanhex/ukishima/blob/master/surfaces/Wallpaper.qml): `surfaces/Wallpaper.qml`
- [Settings](https://github.com/amanhex/ukishima/blob/master/surfaces/Appearance.qml): `surfaces/Appearance.qml`
- [Media Controls](https://github.com/amanhex/ukishima/blob/master/surfaces/Media.qml): `surfaces/Media.qml`
- [System Controls](https://github.com/amanhex/ukishima/blob/master/surfaces/Power.qml): `surfaces/Power.qml`
- [Notifications](https://github.com/amanhex/ukishima/blob/master/surfaces/Toast.qml): `surfaces/Toast.qml`
- [Lock Screen](https://github.com/amanhex/ukishima/blob/master/lockscreen/shell.qml): `lockscreen/shell.qml`

### Shared State

- [Shell State](https://github.com/amanhex/ukishima/tree/master/Singletons): `Singletons`
- [Configuration](https://github.com/amanhex/ukishima/blob/master/Singletons/Config.qml): `Singletons/Config.qml`
- [Dynamic Theme](https://github.com/amanhex/ukishima/blob/master/Singletons/Dyn.qml): `Singletons/Dyn.qml`

### Desktop Integration

- [Palette Generator](https://github.com/amanhex/ukishima/blob/master/scripts/wallcolors.py): `scripts/wallcolors.py`
- [Monitor Utilities](https://github.com/amanhex/ukishima/blob/master/lib/monitors.js): `lib/monitors.js`

### Other components

- **User**
- **Hyprland**
- **Wallpaper Tools**
- **Quickshell IPC**

## Connections

- User → Quickshell IPC: invokes IPC
- Quickshell IPC → IPC Shell: dispatches to
- IPC Shell → Dynamic Pill: presents
- IPC Shell → Launcher: opens
- IPC Shell → Wallpaper: opens
- IPC Shell → Settings: opens
- IPC Shell → Media Controls: opens
- IPC Shell → System Controls: opens
- IPC Shell → Notifications: opens
- Dynamic Pill → Shell State: reads state
- Dock → Shell State: reads state
- Settings → Configuration: updates settings
- Wallpaper → Shell State: uses wallpaper state
- Media Controls → Shell State: uses player state
- System Controls → Shell State: uses system state
- Wallpaper → Palette Generator: generates palette
- Palette Generator → Dynamic Theme: writes palette data
- Dynamic Theme → Dynamic Pill: provides theme
- Dynamic Theme → Dock: provides theme
- Lock Screen → Hyprland: locks session
- Monitor Utilities → Hyprland: parses monitor data
- Wallpaper → Wallpaper Tools: uses wallpaper services