# crazybadger/omarchy-workspace-ribbon architecture

> Architecture diagram of the GitHub repository crazybadger/omarchy-workspace-ribbon, 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/crazybadger/omarchy-workspace-ribbon
- Repository: https://github.com/crazybadger/omarchy-workspace-ribbon

## Overview

Workspace Ribbon is a Quickshell overlay for viewing and switching Hyprland workspaces, with app icons resolved for windows on each workspace. The documented runtime is concentrated in `Ribbon.qml`; `manifest.json` declares the overlay plugin. Source excerpts were not available, so relationships below follow the README rather than source-level inspection.

Main entry points: [`Ribbon.qml`](https://github.com/crazybadger/omarchy-workspace-ribbon/blob/main/Ribbon.qml) (Workspace ribbon), [`manifest.json`](https://github.com/crazybadger/omarchy-workspace-ribbon/blob/main/manifest.json) (Overlay manifest)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_overlay["Ribbon overlay"]
  node_manifest["Overlay manifest<br/>[manifest.json]"]
  node_ribbon["Workspace ribbon<br/>[Ribbon.qml]"]
end

subgraph group_workspace["Workspace data"]
  node_hyprland["Hyprland workspaces"]
  node_toplevels["Wayland toplevels"]
end

subgraph group_icons["Icon resolution"]
  node_iconfiles[("XDG icon files")]
  node_qticons["Qt themed icons"]
  node_desktopentries[("Desktop entries")]
end

node_user(("User"))
node_shell["Omarchy shell"]

node_shell -->|"loads plugin"| node_manifest
node_user -->|"invokes toggle"| node_shell
node_shell -->|"shows overlay"| node_ribbon
node_ribbon -->|"reads workspaces"| node_hyprland
node_ribbon -->|"matches titles"| node_toplevels
node_ribbon -->|"indexes icons"| node_iconfiles
node_ribbon -.->|"falls back"| node_qticons
node_ribbon -.->|"matches titles"| node_desktopentries
node_ribbon -->|"focuses workspace"| node_hyprland

click node_manifest "https://github.com/crazybadger/omarchy-workspace-ribbon/blob/main/manifest.json"
click node_ribbon "https://github.com/crazybadger/omarchy-workspace-ribbon/blob/main/Ribbon.qml"

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_manifest,node_ribbon,node_user toneBlue
class node_hyprland,node_toplevels toneAmber
class node_iconfiles,node_qticons,node_desktopentries toneMint
class node_shell toneIndigo
```

## Components

### Ribbon overlay

- [Overlay manifest](https://github.com/crazybadger/omarchy-workspace-ribbon/blob/main/manifest.json): `manifest.json`
- [Workspace ribbon](https://github.com/crazybadger/omarchy-workspace-ribbon/blob/main/Ribbon.qml): `Ribbon.qml`

### Workspace data

- **Hyprland workspaces**
- **Wayland toplevels**

### Icon resolution

- **XDG icon files**
- **Qt themed icons**
- **Desktop entries**

### Other components

- **User**
- **Omarchy shell**

## Connections

- Omarchy shell → Overlay manifest: loads plugin
- User → Omarchy shell: invokes toggle
- Omarchy shell → Workspace ribbon: shows overlay
- Workspace ribbon → Hyprland workspaces: reads workspaces
- Workspace ribbon → Wayland toplevels: matches titles
- Workspace ribbon → XDG icon files: indexes icons
- Workspace ribbon → Qt themed icons: falls back
- Workspace ribbon → Desktop entries: matches titles
- Workspace ribbon → Hyprland workspaces: focuses workspace