# sanjyay/mirador architecture

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

- Interactive diagram: https://gitdiagram.com/sanjyay/mirador
- Repository: https://github.com/sanjyay/mirador

## Overview

Mirador is an Omarchy Shell plugin for navigating workspaces and windows in a fullscreen overview. Users open it by keyboard or gesture, browse in full, focused, or cycle views, then select, activate, close, or move windows. WorkspaceOverview is the apparent central UI from the source tree; README capabilities establish the broader workflow, but sampled excerpts do not show QML call wiring, so internal UI links are marked unverified. Geometry, window modeling, gestures, and jiggle animation are represented as distinct supporting layers.

Main entry points: [`WorkspaceOverview.qml`](https://github.com/sanjyay/mirador/blob/main/WorkspaceOverview.qml) (Workspace overview), [`JiggleController.qml`](https://github.com/sanjyay/mirador/blob/main/JiggleController.qml) (Jiggle controller), [`bin/mirador`](https://github.com/sanjyay/mirador/blob/main/bin/mirador) (Mirador launcher), [`mirador.bindings.lua`](https://github.com/sanjyay/mirador/blob/main/mirador.bindings.lua) (Key bindings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and input"]
  node_launcher["Mirador launcher"]
  node_bindings["Key bindings"]
  node_gestures["Gesture bindings"]
  node_gesturehelper["Gesture decisions<br/>[GestureHelper.js]"]
end

subgraph group_overview["Overview UI"]
  node_overview["Workspace overview"]
  node_carousel["Carousel cycle"]
  node_compact["Compact cycle"]
  node_card["Workspace card<br/>[WorkspaceCard.qml]"]
  node_insertion["Insertion card"]
  node_preview["Window preview<br/>[WindowPreview.qml]"]
  node_demo["Demo overlay"]
end

subgraph group_domain["Workspace and geometry"]
  node_model["Window model<br/>[WindowModel.js]"]
  node_geometry["Window geometry<br/>[WindowGeometry.js]"]
end

subgraph group_motion["Interaction effects"]
  node_jigglecontroller["Jiggle controller"]
  node_jigglesurface["Jiggle surface<br/>[JiggleSurface.qml]"]
  node_physics["Jiggle physics<br/>[JigglePhysics.js]"]
end

node_user(("User"))
node_compositor["Hyprland compositor"]

node_user -->|"opens overview"| node_launcher
node_user -->|"uses shortcuts"| node_bindings
node_user -->|"uses gestures"| node_gestures
node_bindings -->|"dispatches commands"| node_launcher
node_launcher -.->|"summons UI"| node_overview
node_gestures -.->|"toggles modes"| node_overview
node_overview -.->|"offers cycle view"| node_carousel
node_overview -.->|"offers cycle view"| node_compact
node_overview -.->|"renders workspaces"| node_card
node_overview -.->|"offers workspace target"| node_insertion
node_card -.->|"renders windows"| node_preview
node_overview -.->|"models window state"| node_model
node_overview -.->|"computes layouts"| node_geometry
node_compositor -.->|"provides workspace state"| node_overview
node_compositor -->|"provides window geometry"| node_preview
node_user -.->|"pinches to switch"| node_gesturehelper
node_gesturehelper -.->|"selects mode"| node_overview
node_overview -.->|"animates changes"| node_jigglecontroller
node_jigglecontroller -.->|"updates surface"| node_jigglesurface
node_jigglecontroller -.->|"uses physics"| node_physics

click node_launcher "https://github.com/sanjyay/mirador/blob/main/bin/mirador"
click node_bindings "https://github.com/sanjyay/mirador/blob/main/mirador.bindings.lua"
click node_gestures "https://github.com/sanjyay/mirador/blob/main/mirador.gestures.lua"
click node_overview "https://github.com/sanjyay/mirador/blob/main/WorkspaceOverview.qml"
click node_carousel "https://github.com/sanjyay/mirador/blob/main/CarouselCycleView.qml"
click node_compact "https://github.com/sanjyay/mirador/blob/main/CompactCycleView.qml"
click node_card "https://github.com/sanjyay/mirador/blob/main/WorkspaceCard.qml"
click node_insertion "https://github.com/sanjyay/mirador/blob/main/InsertionWorkspaceCard.qml"
click node_preview "https://github.com/sanjyay/mirador/blob/main/WindowPreview.qml"
click node_demo "https://github.com/sanjyay/mirador/blob/main/DemoInputOverlay.qml"
click node_model "https://github.com/sanjyay/mirador/blob/main/WindowModel.js"
click node_geometry "https://github.com/sanjyay/mirador/blob/main/WindowGeometry.js"
click node_gesturehelper "https://github.com/sanjyay/mirador/blob/main/GestureHelper.js"
click node_jigglecontroller "https://github.com/sanjyay/mirador/blob/main/JiggleController.qml"
click node_jigglesurface "https://github.com/sanjyay/mirador/blob/main/JiggleSurface.qml"
click node_physics "https://github.com/sanjyay/mirador/blob/main/JigglePhysics.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_launcher,node_bindings,node_gestures,node_gesturehelper,node_user toneBlue
class node_overview,node_carousel,node_compact,node_card,node_insertion,node_preview,node_demo toneAmber
class node_model,node_geometry toneMint
class node_jigglecontroller,node_jigglesurface,node_physics toneRose
class node_compositor toneIndigo
```

## Components

### Entry and input

- [Mirador launcher](https://github.com/sanjyay/mirador/blob/main/bin/mirador): `bin/mirador`
- [Key bindings](https://github.com/sanjyay/mirador/blob/main/mirador.bindings.lua): `mirador.bindings.lua`
- [Gesture bindings](https://github.com/sanjyay/mirador/blob/main/mirador.gestures.lua): `mirador.gestures.lua`
- [Gesture decisions](https://github.com/sanjyay/mirador/blob/main/GestureHelper.js): `GestureHelper.js`

### Overview UI

- [Workspace overview](https://github.com/sanjyay/mirador/blob/main/WorkspaceOverview.qml): `WorkspaceOverview.qml`
- [Carousel cycle](https://github.com/sanjyay/mirador/blob/main/CarouselCycleView.qml): `CarouselCycleView.qml`
- [Compact cycle](https://github.com/sanjyay/mirador/blob/main/CompactCycleView.qml): `CompactCycleView.qml`
- [Workspace card](https://github.com/sanjyay/mirador/blob/main/WorkspaceCard.qml): `WorkspaceCard.qml`
- [Insertion card](https://github.com/sanjyay/mirador/blob/main/InsertionWorkspaceCard.qml): `InsertionWorkspaceCard.qml`
- [Window preview](https://github.com/sanjyay/mirador/blob/main/WindowPreview.qml): `WindowPreview.qml`
- [Demo overlay](https://github.com/sanjyay/mirador/blob/main/DemoInputOverlay.qml): `DemoInputOverlay.qml`

### Workspace and geometry

- [Window model](https://github.com/sanjyay/mirador/blob/main/WindowModel.js): `WindowModel.js`
- [Window geometry](https://github.com/sanjyay/mirador/blob/main/WindowGeometry.js): `WindowGeometry.js`

### Interaction effects

- [Jiggle controller](https://github.com/sanjyay/mirador/blob/main/JiggleController.qml): `JiggleController.qml`
- [Jiggle surface](https://github.com/sanjyay/mirador/blob/main/JiggleSurface.qml): `JiggleSurface.qml`
- [Jiggle physics](https://github.com/sanjyay/mirador/blob/main/JigglePhysics.js): `JigglePhysics.js`

### Other components

- **User**
- **Hyprland compositor**

## Connections

- User → Mirador launcher: opens overview (evidence: `README.md`)
- User → Key bindings: uses shortcuts (evidence: `README.md`)
- User → Gesture bindings: uses gestures (evidence: `README.md`)
- Key bindings → Mirador launcher: dispatches commands (evidence: `README.md`)
- Mirador launcher → Workspace overview: summons UI
- Gesture bindings → Workspace overview: toggles modes
- Workspace overview → Carousel cycle: offers cycle view
- Workspace overview → Compact cycle: offers cycle view
- Workspace overview → Workspace card: renders workspaces
- Workspace overview → Insertion card: offers workspace target
- Workspace card → Window preview: renders windows
- Workspace overview → Window model: models window state
- Workspace overview → Window geometry: computes layouts
- Hyprland compositor → Workspace overview: provides workspace state
- Hyprland compositor → Window preview: provides window geometry (evidence: `README.md`)
- User → Gesture decisions: pinches to switch
- Gesture decisions → Workspace overview: selects mode
- Workspace overview → Jiggle controller: animates changes
- Jiggle controller → Jiggle surface: updates surface
- Jiggle controller → Jiggle physics: uses physics
