# elpritchos/omadora architecture

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

- Interactive diagram: https://gitdiagram.com/elpritchos/omadora
- Repository: https://github.com/elpritchos/omadora

## Overview

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`](https://github.com/elpritchos/omadora/blob/master/install.sh) (Install), [`install/config`](https://github.com/elpritchos/omadora/tree/master/install/config) (Config stage), [`bin`](https://github.com/elpritchos/omadora/tree/master/bin) (Commands), [`config`](https://github.com/elpritchos/omadora/tree/master/config) (Active config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_install["Install pipeline"]
  node_node_install_entry["Install<br/>[install.sh]"]
  node_node_preflight["Preflight<br/>install stage"]
  node_node_config_stage["Config stage<br/>install stage"]
  node_node_login_stage["Login stage<br/>install stage"]
  node_node_packaging_stage["Packaging<br/>install stage"]
  node_node_postinstall_stage["Post-install<br/>install stage"]
  node_node_package_lists["Package lists<br/>package manifest"]
end

subgraph group_grp_runtime["Desktop runtime"]
  node_node_boot_entry["Boot<br/>[boot.sh]"]
  node_node_hyprland_runtime["Hyprland<br/>compositor session"]
  node_node_uwsm_runtime["UWSM<br/>session manager"]
  node_node_desktop_services["Desktop services<br/>user units"]
  node_node_waybar_stack["Panel stack<br/>desktop UI"]
end

subgraph group_grp_config["Config layers"]
  node_node_defaults["Defaults<br/>baseline templates"]
  node_node_active_config["Active config<br/>installed config"]
  node_node_hooks_extensions["Hooks<br/>customization points"]
  node_node_shell_defaults["Shell defaults<br/>shell baseline"]
end

subgraph group_grp_themes["Themes"]
  node_node_theme_templates["Theme templates<br/>render templates"]
  node_node_themes["Theme packs<br/>theme assets"]
end

subgraph group_grp_ops["Operations"]
  node_node_bin_api["Commands<br/>ops scripts"]
  node_node_apps_catalog["Apps catalog<br/>desktop entries"]
  node_node_migrations["Migrations<br/>state transitions"]
end

node_node_install_entry -->|"starts"| node_node_preflight
node_node_install_entry -->|"applies"| node_node_config_stage
node_node_install_entry -->|"sets up"| node_node_login_stage
node_node_install_entry -->|"installs"| node_node_packaging_stage
node_node_install_entry -->|"finishes"| node_node_postinstall_stage
node_node_preflight -->|"checks"| node_node_migrations
node_node_preflight -->|"reads"| node_node_package_lists
node_node_config_stage -->|"overlays"| node_node_defaults
node_node_config_stage -->|"writes"| node_node_active_config
node_node_config_stage -->|"enables"| node_node_hooks_extensions
node_node_config_stage -->|"selects"| node_node_themes
node_node_login_stage -->|"configures"| node_node_uwsm_runtime
node_node_login_stage -->|"enables"| node_node_desktop_services
node_node_boot_entry -->|"enters"| node_node_uwsm_runtime
node_node_uwsm_runtime -->|"starts"| node_node_hyprland_runtime
node_node_hyprland_runtime -->|"drives"| node_node_waybar_stack
node_node_hyprland_runtime -->|"invokes"| node_node_bin_api
node_node_bin_api -->|"launches"| node_node_apps_catalog
node_node_apps_catalog -->|"references"| node_node_active_config
node_node_defaults -->|"feeds"| node_node_theme_templates
node_node_theme_templates -->|"renders"| node_node_themes
node_node_themes -->|"repaints"| node_node_active_config
node_node_package_lists -->|"guides"| node_node_packaging_stage
node_node_packaging_stage -->|"supports"| node_node_bin_api
node_node_migrations -->|"updates"| node_node_active_config
node_node_hooks_extensions -->|"extends"| node_node_bin_api

click node_node_install_entry "https://github.com/elpritchos/omadora/blob/master/install.sh"
click node_node_boot_entry "https://github.com/elpritchos/omadora/blob/master/boot.sh"
click node_node_preflight "https://github.com/elpritchos/omadora/tree/master/install/preflight"
click node_node_config_stage "https://github.com/elpritchos/omadora/tree/master/install/config"
click node_node_login_stage "https://github.com/elpritchos/omadora/tree/master/install/login"
click node_node_packaging_stage "https://github.com/elpritchos/omadora/tree/master/install/packaging"
click node_node_postinstall_stage "https://github.com/elpritchos/omadora/tree/master/install/post-install"
click node_node_hyprland_runtime "https://github.com/elpritchos/omadora/tree/master/config/hypr"
click node_node_uwsm_runtime "https://github.com/elpritchos/omadora/tree/master/config/uwsm"
click node_node_desktop_services "https://github.com/elpritchos/omadora/tree/master/config/systemd/user"
click node_node_defaults "https://github.com/elpritchos/omadora/tree/master/default"
click node_node_active_config "https://github.com/elpritchos/omadora/tree/master/config"
click node_node_theme_templates "https://github.com/elpritchos/omadora/tree/master/default/themed"
click node_node_themes "https://github.com/elpritchos/omadora/tree/master/themes"
click node_node_hooks_extensions "https://github.com/elpritchos/omadora/tree/master/config/omadora"
click node_node_bin_api "https://github.com/elpritchos/omadora/tree/master/bin"
click node_node_apps_catalog "https://github.com/elpritchos/omadora/tree/master/applications"
click node_node_package_lists "https://github.com/elpritchos/omadora/blob/master/install/omadora-base.packages"
click node_node_migrations "https://github.com/elpritchos/omadora/tree/master/migrations"
click node_node_shell_defaults "https://github.com/elpritchos/omadora/tree/master/default/bash"
click node_node_waybar_stack "https://github.com/elpritchos/omadora/tree/master/config/waybar"

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_node_install_entry,node_node_preflight,node_node_config_stage,node_node_login_stage,node_node_packaging_stage,node_node_postinstall_stage,node_node_package_lists toneBlue
class node_node_boot_entry,node_node_hyprland_runtime,node_node_uwsm_runtime,node_node_desktop_services,node_node_waybar_stack toneAmber
class node_node_defaults,node_node_active_config,node_node_hooks_extensions,node_node_shell_defaults toneMint
class node_node_theme_templates,node_node_themes toneRose
class node_node_bin_api,node_node_apps_catalog,node_node_migrations toneIndigo
```

## Components

### Install pipeline

Staged setup, provisioning, and post-install actions.

- [Install](https://github.com/elpritchos/omadora/blob/master/install.sh): installer entry · Top-level installation entry point. · `install.sh`
- [Preflight](https://github.com/elpritchos/omadora/tree/master/install/preflight): install stage · Safety checks, validation, migrations, and sudo/session handling. · `install/preflight`
- [Config stage](https://github.com/elpritchos/omadora/tree/master/install/config): install stage · System, branding, hardware, and desktop configuration installation. · `install/config`
- [Login stage](https://github.com/elpritchos/omadora/tree/master/install/login): install stage · Login/session integration, keyring, Plymouth, and systemd setup. · `install/login`
- [Packaging](https://github.com/elpritchos/omadora/tree/master/install/packaging): install stage · Curated package selection and feature bundle installation. · `install/packaging`
- [Post-install](https://github.com/elpritchos/omadora/tree/master/install/post-install): install stage · Cleanup, database updates, and reboot completion. · `install/post-install`
- [Package lists](https://github.com/elpritchos/omadora/blob/master/install/omadora-base.packages): package manifest · Base, removed, and curated package group definitions. · `install/omadora-base.packages`

### Desktop runtime

Hyprland session, desktop services, and user-session control.

- [Boot](https://github.com/elpritchos/omadora/blob/master/boot.sh): session bootstrap · Session startup entry point. · `boot.sh`
- [Hyprland](https://github.com/elpritchos/omadora/tree/master/config/hypr): compositor session · Core desktop compositor and workspace/session behavior. · `config/hypr`
- [UWSM](https://github.com/elpritchos/omadora/tree/master/config/uwsm): session manager · Session orchestration and environment wiring for the desktop. · `config/uwsm`
- [Desktop services](https://github.com/elpritchos/omadora/tree/master/config/systemd/user): user units · Long-running user services such as battery monitoring. · `config/systemd/user`
- [Panel stack](https://github.com/elpritchos/omadora/tree/master/config/waybar): desktop UI · Waybar, launcher, notifications, and related desktop UI config. · `config/waybar`

### Config layers

Baseline defaults, active overrides, and generated templates.

- [Defaults](https://github.com/elpritchos/omadora/tree/master/default): baseline templates · Canonical shell, compositor, launcher, and app defaults. · `default`
- [Active config](https://github.com/elpritchos/omadora/tree/master/config): installed config · Live configuration applied on the target machine. · `config`
- [Hooks](https://github.com/elpritchos/omadora/tree/master/config/omadora): customization points · Local hook and extension boundaries for user overrides. · `config/omadora`
- [Shell defaults](https://github.com/elpritchos/omadora/tree/master/default/bash): shell baseline · Shared shell environment, prompts, aliases, and input defaults. · `default/bash`

### Themes

Selectable theme packs and shared theme templates.

- [Theme templates](https://github.com/elpritchos/omadora/tree/master/default/themed): render templates · Shared templates that repaint multiple desktop components. · `default/themed`
- [Theme packs](https://github.com/elpritchos/omadora/tree/master/themes): theme assets · Selectable theme directories with coordinated colors, icons, and app themes. · `themes`

### Operations

Command wrappers, app catalog, and system maintenance flows.

- [Commands](https://github.com/elpritchos/omadora/tree/master/bin): ops scripts · Operational command surface for launching, restarting, toggling, and updating. · `bin`
- [Apps catalog](https://github.com/elpritchos/omadora/tree/master/applications): desktop entries · Visible and hidden application launch metadata. · `applications`
- [Migrations](https://github.com/elpritchos/omadora/tree/master/migrations): state transitions · Versioned changes for already-installed systems. · `migrations`

## Connections

- 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.
