How elpritchos/omadora works
1. What this repo is
Omadora is a Linux desktop distribution layer, not an app. It assembles a minimal Hyprland-based Fedora 43 workstation using shell scripts, configuration files, desktop-entry metadata, and theme assets. The repo’s job is to install and maintain a cohesive user session.
2. Primary control flow
The top-level entry points are install.sh for initial setup and boot.sh for session bootstrap. Installation is organized as a staged pipeline under install/:
- preflight/ for safety checks and environment validation
- config/ for system/user configuration
- login/ for login/session-related setup
- packaging/ for package selection and installation
- post-install/ for cleanup, updates, and reboot actions
3. Session runtime model
Omadora expects a logged-in Fedora user to start the desktop manually via the omadora command mentioned in the README. The runtime desktop is centered on Hyprland and managed through UWSM-related config under config/uwsm/. Systemd user units in config/systemd/user/ support long-running desktop services such as battery monitoring.
4. Configuration layering
The repo uses a clear split between baseline defaults and active overrides:
- default/ holds the canonical baseline for shell, Hyprland, theming, and app-specific settings
- config/ contains the installed/active configuration
- themes/ provides selectable theme packs
This makes the architecture “template + overlay”: defaults define behavior, config adapts it for the target machine, and themes repaint the same desktop stack.
5. Theme system as a cross-cutting subsystem
Themes are one of the main architectural axes. Each theme directory under themes/ carries coordinated assets for multiple consumers: colors.toml, icons.theme, background images, and app-specific theme files for Neovim, btop, VS Code, and sometimes Hyprland or Chromium. Template files under default/themed/ and config/omadora/themed/ are used to render or switch the active look across the desktop.
6. Desktop composition
The desktop is built from several tightly integrated components: Hyprland as the compositor, Waybar as the panel, Wofi or Walker as launchers, Mako for notifications, Hyprlock/Hypridle/Hyprsunset for lock and idle behavior, and terminal/editor/browser defaults. Their configuration lives in default/hypr/, config/hypr/, config/waybar/, config/wofi/, config/walker/, config/mako/, and related directories.
7. Command layer / operational scripts
The large bin/ directory is the operational API of the system. These are small commands for desktop actions rather than user-facing applications: launching apps, restarting services, changing themes, switching audio, toggling idle/nightlight/waybar, taking screenshots, running updates, and managing packages. They act as stable wrappers around the underlying desktop tools and system commands.
8. Applications and launch integration
applications/ contains .desktop entries for apps that should appear in menus or launchers, plus applications/hidden/ for entries that should be suppressed. This is part of the desktop cataloging layer: Omadora curates which applications are visible to the user and how they are launched.
9. Package and provisioning boundaries
Package selection is centralized in install/omadora-base.packages, install/omadora-base.groups, and the related “removed” lists. The packaging stage is split by concern (fonts.sh, icons.sh, nvim.sh, tuis.sh, webapps.sh, cargo.sh), which suggests the repo installs a curated baseline and then optional feature bundles. The README notes that most packages come from Fedora repos, with Hyprland-related packages sourced from a COPR repository.
10. Migrations and long-term state
The migrations/ directory plus scripts like bin/omadora-migrate and bin/omadora-dev-add-migration indicate explicit versioned state transitions. This is how Omadora evolves installed systems safely over time, rather than treating the repo as a one-shot installer.
11. Hooks and extensibility points
config/omadora/hooks/ and config/omadora/extensions/ provide user customization boundaries. Sample hook files such as font-set.sample, theme-set.sample, and post-update.sample show where local behavior can be injected without modifying the core logic.
12. External integrations that materially shape the architecture
The main external dependencies are Fedora’s package ecosystem, Hyprland and its associated desktop tools, systemd user services, and uwsm for session orchestration. These are not incidental; they define how the desktop starts, persists, and responds to refresh/restart commands.
13. How to diagram the system
A good architecture diagram would show:
- installation pipeline feeding into the user’s home/system config
- theme selection feeding multiple app-specific config consumers
- desktop session startup managed by UWSM/Hyprland
- bin/ commands acting as the control surface for runtime operations
- applications/ feeding launchers/menus
- migrations updating installed state over time
Main entry points: install.sh Install · install/config Config stage · bin Commands · config Active config
Components 21
Install pipeline
Staged setup, provisioning, and post-install actions.
- Install · Top-level installation entry point.
install.sh - Preflight · Safety checks, validation, migrations, and sudo/session handling.
install/preflight - Config stage · System, branding, hardware, and desktop configuration installation.
install/config - Login stage · Login/session integration, keyring, Plymouth, and systemd setup.
install/login - Packaging · Curated package selection and feature bundle installation.
install/packaging - Post-install · Cleanup, database updates, and reboot completion.
install/post-install - Package lists · Base, removed, and curated package group definitions.
install/omadora-base.packages
Desktop runtime
Hyprland session, desktop services, and user-session control.
- Boot · Session startup entry point.
boot.sh - Hyprland · Core desktop compositor and workspace/session behavior.
config/hypr - UWSM · Session orchestration and environment wiring for the desktop.
config/uwsm - Desktop services · Long-running user services such as battery monitoring.
config/systemd/user - Panel stack · Waybar, launcher, notifications, and related desktop UI config.
config/waybar
Config layers
Baseline defaults, active overrides, and generated templates.
- Defaults · Canonical shell, compositor, launcher, and app defaults.
default - Active config · Live configuration applied on the target machine.
config - Hooks · Local hook and extension boundaries for user overrides.
config/omadora - Shell defaults · Shared shell environment, prompts, aliases, and input defaults.
default/bash
Themes
Selectable theme packs and shared theme templates.
- Theme templates · Shared templates that repaint multiple desktop components.
default/themed - Theme packs · Selectable theme directories with coordinated colors, icons, and app themes.
themes
Operations
Command wrappers, app catalog, and system maintenance flows.
- Commands · Operational command surface for launching, restarting, toggling, and updating.
bin - Apps catalog · Visible and hidden application launch metadata.
applications - Migrations · Versioned changes for already-installed systems.
migrations
Connections 26
- Install → Preflight: starts · Install begins with safety checks and migration awareness.
- Install → Config stage: applies · Installer writes machine-specific configuration.
- Install → Login stage: sets up · Installer prepares login/session integration.
- Install → Packaging: installs · Installer provisions packages and feature bundles.
- Install → Post-install: finishes · Installer runs cleanup and reboot steps.
- Preflight → Migrations: checks · Preflight verifies and applies required migrations.
- Preflight → Package lists: reads · Preflight consults package/state manifests.
- Config stage → Defaults: overlays · Installed config is layered on top of defaults.
- Config stage → Active config: writes · Configuration stage populates the live config tree.
- Config stage → Hooks: enables · Config stage preserves customization boundaries.
- Config stage → Theme packs: selects · Config stage binds the active theme set.
- Login stage → UWSM: configures · Login stage wires the user session manager.
- Login stage → Desktop services: enables · Login stage installs user services for the desktop.
- Boot → UWSM: enters · Boot script hands off into session orchestration.
- UWSM → Hyprland: starts · UWSM launches the compositor session.
- Hyprland → Panel stack: drives · Hyprland session composes the panel and launcher stack.
- Hyprland → Commands: invokes · Keybindings and session actions call operational commands.
- Commands → Apps catalog: launches · Command wrappers feed desktop app launchers and menus.
- Apps catalog → Active config: references · Desktop entries are curated alongside installed configuration.
- Defaults → Theme templates: feeds · Baseline config is parameterized by shared theme templates.
- Theme templates → Theme packs: renders · Templates are populated from the selected theme pack.
- Theme packs → Active config: repaints · Theme assets are applied across active desktop configuration.
- Package lists → Packaging: guides · Package manifests drive curated installation bundles.
- Packaging → Commands: supports · Installed tools back the desktop control surface.
- Migrations → Active config: updates · Migrations transform persisted system state over time.
- Hooks → Commands: extends · Hooks and extensions customize operational behavior.