Architecture and repositories
How the equisdots repositories fit together, the shared contracts they rely on and the decisions behind them.
equisdots is a set of small repositories with one clear owner each, tied
together by two shared contracts: settings.json for configuration and the
palette files for color. This page maps the repositories, the data flow and
the invariants the pieces rely on.
Repositories and install paths
| Repository | Role | Payload location |
|---|---|---|
| dots | Meta installer, updater, diagnostics | ~/.local/bin/dots |
| hyprland | Compositor config and scripts | ~/.config/hypr |
| niri | niri compositor config (KDL) and scripts | ~/.config/niri |
| niri-meta | Meta installer, updater, diagnostics (dotsniri) |
~/.local/bin/dotsniri |
| niri-shell | Shell overlay (Niri backend) | merged into the shell |
| nyx-niri | Nyx overlay (compositor-neutral) | merged into the shell |
| niri-login | Wayland session entry | /usr/share/wayland-sessions |
| shell | Quickshell UI | ~/.config/hypr/scripts/quickshell |
| nyx | Mascot island/notch plugin | .../quickshell/ui/plugins/nyx |
| palettes | Palette data and schema | .../quickshell/dock/palettes |
| background | Curated wallpapers and scene catalog | release asset background.zip |
| theme-sync | Cross-app theming engine | ~/.local/bin/theme-sync |
| davinci | Wallpaper kernel | ~/.local/bin/davinci |
| timex | Weather/time plugin (engine, calendar, bar island) | .../quickshell/ui/plugins/timex |
| xturing | Terminal settings UI | ~/.local/bin/xturing |
| plugins | Standard, 63-plugin hub, install registry | .../quickshell/ui/plugins/<id> |
| plugin-api | Manifest schema, API version, compat evaluators | .../quickshell/plugin-api.json |
| plugin-sdk | PluginHost, Settings, surfaces, Lua mod | .../quickshell/core/sdk |
| transformpath | Plugin architecture and decision log | documentation only |
| web | Documentation and previews site | GitHub Pages |
| login | SDDM greeter | /usr/share/sddm/themes/x |
Managed clones live under ~/.local/share/equisdots/<repo> (the niri stack uses
~/.local/share/equisdots-niri/<repo>). Wrappers in ~/.local/bin exec the
cloned engines, so dots update changes behavior without touching the wrapper.
hyprland and niri are the two compositor front ends; shell, nyx,
palettes, theme-sync, background, timex, davinci, the plugin
repositories and login are shared by both.
One shell, two compositors
The shell repository is Hyprland-first; niri-shell and nyx-niri are
overlays that add what niri needs and leave every other file untouched. The niri
meta merges them into the deployed shell, so one tree drives both sessions:
shell (base) + niri-shell + nyx-niri = ~/.config/hypr/scripts/quickshell
core/Compositor.qml has no hard-coded compositor. It reads the environment and
picks core/compositors/Niri.qml when XDG_CURRENT_DESKTOP contains niri or
NIRI_SOCKET is set, otherwise core/compositors/Hyprland.qml. Both backends
implement the same surface — workspacesCommand, keyboardCommand,
focusCommand, setWindowBorders, switchWorkspace,
cycleKeyboardLayout — plus the neutral persistence calls in core/Config.qml
(persistKeybinds, persistStartup, applyMonitors, resetMonitors,
reload). Widgets never branch on the compositor.
The shared data root stays ~/.config/hypr on both compositors (settings,
palettes, wallpapers, shell); only the compositor output moves to
~/.config/niri. The niri scripts read the shared root through
EQUISDOTS_CONFIG_DIR.
| Concern | Hyprland | niri |
|---|---|---|
| Workspaces | hyprctl + .socket2.sock |
niri msg --json event-stream |
| Borders | hyprctl eval |
generated/borders.kdl + reload |
| Keybinds / startup / appearance | config/*.lua + reload |
generated/user-*.kdl + reload |
| Effects / monitors | hyprctl getoption/eval, hl.monitor |
generated/*.kdl + reload |
The two meta installers are independent: dots owns the Hyprland stack
(~/.local/share/equisdots), dotsniri owns the niri stack
(~/.local/share/equisdots-niri), and both can coexist. Overlays are
conditional and reversible: a shared file is only replaced by its niri variant
while the niri session is selected. See niri compositor.
Plugin system
The plugin layer is split into four contracts, so hosts and plugins never import each other's internals:
| Repository | Contract |
|---|---|
| plugin-api | plugin.json schema, host API version and compat evaluators |
| plugin-sdk | PluginHost, reactive Settings, surfaces, Lua mod |
| plugins | Standard, 63-plugin hub, registry and smoke tests |
| transformpath | Architecture notes, decisions and migration status |
Hosts discover plugins by folder (~/.config/hypr/plugins and
plugins-user), resolve the manifest, and mount only enabled, compatible
plugins. A managed plugin deploys twice: the whole repository into
.../quickshell/ui/plugins/<id>/ (the UI face) and the runtime subset
(plugin.json, hypr.lua, scripts/) into ~/.config/hypr/plugins/<id>/.
The shell mounts generic hosts, panels, bar modules and complete bars; the
Hyprland loader evaluates hypr.lua fragments under pcall. niri consumes the
same plugins through static KDL binds and the compositor-neutral shell.
See Plugins and extensions for the manifest, lifecycle and CLI.
Configuration flow
settings.json (single source of truth: bar, widgets, timex, plugins, ...)
| read/write atomically (tmp + mv), watched by the shell
|
+--> shell Config.qml -----------> live UI updates
+--> plugins scan -----------------> enabled/config/enabled defaults
+--> xturing --------------------- terminal edits
+--> hyprland colors.lua ---------> border defaults at load
+--> theme-sync ------------------> active palette for every target
+--> timex -----------------------> provider, city, unit
+--> davinci --------------------> slideshow and wallpaper options
Writes are atomic so file watchers keep working: dots merges settings.json
as shipped defaults plus user values, xturing preserves unknown keys, and the
shell editor debounces its own writes.
Palette flow
palettes repo --> dock/palettes/{*.json, community/, index.json, schema.json}
|
settings.json bar.palette selects the slug (fallback: x)
|
+--------------------+--------------------+
| | |
shell Colors.qml theme-sync targets Hyprland colors.lua
| | |
bar, widgets, kitty, starship, window borders
lock screen nvim, vscode, gtk, (live via hyprctl eval)
qt, browsers, ...
|
xwww scenes (--palette equisdots)
Consumers never hardcode colors; a scene that reads the same palette file agrees with the rest of the desktop by construction. See Theming and palettes.
Wallpaper flow
davinci (kernel CLI)
+--> xwww img ......... still images
+--> xwww scene run ... interactive scenes (JS, palette-driven)
+--> mpvpaper ......... video wallpapers
+--> current_wallpaper.png ... lock screen, SDDM
+--> current_scene, thumbs, slideshow state ... cache/state/run dirs
The Quickshell picker is a thin frontend over the same CLI. The shell, the
lock screen and init.sh only consume the contract files.
Session startup
autostart.lua starts xwww-daemon and init.sh; init.sh re-applies the
scene recorded in current_scene when present, otherwise the previous
wallpaper is restored. restore-monitors.sh re-applies the saved monitor
layout and reconciles it every couple of seconds. The shell and its data
watchers then run for the whole session.
Update invariants
- Managed clones are read-only:
dotsfetchesorigin/mainand hard-resets. - A clone with uncommitted changes is never deployed, so a stale checkout cannot downgrade live files.
xwwwis pinned to a release;dots update/dots systemreinstall when the running binary differs, anddots doctorreports mismatches.settings.jsonis never regenerated from scratch; it is always defaults plus user overrides.
See Updating and diagnosing for the command details.
Design decisions
- Lua Hyprland config (0.55+): modular
require()files with runtime overrides; runtime changes go throughhyprctl eval, never by rewriting loaded files mid-session. - No Matugen: palettes are fixed JSON data, so colors are predictable and shared across compositor, shell and applications.
- Static SDDM theme: no runtime sudo and no palette sync at the greeter, which avoids PAM failures.
- Scenes render in the xwww client: the daemon stays a dumb frame consumer, and the sandbox keeps scene code CPU-only with no I/O or input.
- Two compositor front ends, one shell:
hyprlandandniriare swappable behindcore/Compositor.qml; the shell, palettes and Nyx are shared, the shared data root stays at~/.config/hypr, and niri-specific code ships as reversible overlays (niri-shell,nyx-niri). - Plugins are a first-class layer: the manifest is the only contract, hosts
know no plugin ids, extension points are generic (
provides), and a failing plugin is isolated instead of aborting the session. - No CI: each repository ships a local check script, run before pushing.
Development checks
| Repository | Command | Checks |
|---|---|---|
| shell | scripts/check.sh |
qmllint on QML, node --check on JS |
| hyprland | scripts/check.sh |
luac -p on Lua, bash -n on scripts |
| niri | scripts/check.sh |
bash -n on scripts, KDL brace balance |
| niri-meta | dotsniri doctor --self-test |
bash -n over the toolkit (works without niri) |
| palettes | scripts/check.sh |
Schema and index.json consistency |
| theme-sync | scripts/check.sh |
compileall plus CLI smoke test |
| xturing | scripts/check.sh |
cargo fmt, clippy and tests |
| plugins | tests/smoke.sh |
Manifests, qmldir, scan, ids and registry integrity |
| plugin-api | evaluator fixtures | Bash and Lua semver parity |
| plugin-sdk | qmllint + Lua tests |
Host kit and mod API |
External dependencies
The stack also installs from outside the organization: xscriptor-colors/terminal (kitty and starship), xscriptor-colors/nvim, xscriptor-colors/vscode and x-ports/xwww (the wallpaper daemon and scene engine).
Related pages
- Contributing and security for checks and reporting.
- Updating and diagnosing for the update flow.