# grapes7000/arch-wm-install architecture

> Architecture diagram of the GitHub repository grapes7000/arch-wm-install, 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/grapes7000/arch-wm-install
- Repository: https://github.com/grapes7000/arch-wm-install
- Video tour (about a minute): https://gitdiagram.com/grapes7000/arch-wm-install/video

## Overview

Arch WM Install provisions and maintains a customized Arch desktop, then provides its runtime shell, compositor configuration, terminal, and shared theming. The user chooses an installer profile and theme; the staged installer applies managed configuration and packages with resumable state and rollback. At runtime, Quickshell presents layout-driven surfaces and widgets, while Hyprland and terminal settings consume the shared theme contract. An optional desktop-profile manager audits and prepares alternate profiles. README capabilities inform unsampled branches; links are limited to documented behavior and sampled source, so exact internal wiring is not inferred.

Main entry points: [`installer/runtime.py`](https://github.com/grapes7000/arch-wm-install/blob/main/installer/runtime.py) (Stage runtime), [`modules/theme-engine`](https://github.com/grapes7000/arch-wm-install/tree/main/modules/theme-engine) (Generated theme targets), [`desktop_manager/manager.py`](https://github.com/grapes7000/arch-wm-install/blob/main/desktop_manager/manager.py) (Profile planning and activation), [`modules/shell/shell.qml`](https://github.com/grapes7000/arch-wm-install/blob/main/modules/shell/shell.qml) (Shell entry and surfaces)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_provision["Installation and Recovery"]
  node_installer["Installer CLI<br/>[install.sh]"]
  node_stages["Stage runtime<br/>[runtime.py]"]
  node_entry["Installer entry<br/>[entry.py]"]
  node_state[("Run state and backups<br/>[state.py]")]
  node_manifests["Package manifests"]
end

subgraph group_appearance["Theme Engine"]
  node_theme_cli["Theme commands"]
  node_theme_components["Theme generators"]
  node_theme_catalog["Theme catalog and schema"]
  node_theme_outputs["Generated theme targets"]
end

subgraph group_shell["Quickshell Platform"]
  node_shell_root["Shell entry and surfaces<br/>[shell.qml]"]
  node_shell_core["Shell registries and context"]
  node_layouts["Surface layouts"]
  node_widgets["Portable widgets"]
  node_services["System services"]
end

subgraph group_desktop["Desktop Runtime"]
  node_hyprland["Hyprland configuration"]
  node_terminal["Terminal configuration"]
  node_login["Login configuration"]
end

subgraph group_profiles["Profile Management"]
  node_profile_cli["Profile manager CLI<br/>[cli.py]"]
  node_profile_manager["Profile planning and activation<br/>[manager.py]"]
  node_profile_scanner["Profile safety scanner<br/>[scanner.py]"]
  node_codex_review["Optional Codex review<br/>[codex_review.py]"]
end

node_user(("Desktop user"))
node_arch(("Arch Linux system"))
node_upstream(("Theme upstream"))

node_user -->|"selects profile"| node_installer
node_installer -->|"dispatches"| node_entry
node_entry -->|"configures stages"| node_stages
node_stages -->|"records backups"| node_state
node_stages -->|"reads packages"| node_manifests
node_stages -->|"installs configuration"| node_arch
node_upstream -.->|"provides catalog"| node_theme_catalog
node_theme_cli -->|"reads themes"| node_theme_catalog
node_theme_cli -->|"generates targets"| node_theme_components
node_theme_components -->|"writes targets"| node_theme_outputs
node_stages -->|"installs theme engine"| node_theme_cli
node_theme_outputs -->|"supplies theme settings"| node_hyprland
node_theme_outputs -->|"supplies theme settings"| node_shell_root
node_theme_outputs -->|"supplies theme settings"| node_terminal
node_shell_root -->|"uses registries"| node_shell_core
node_shell_root -->|"loads layouts"| node_layouts
node_shell_core -->|"resolves widgets"| node_widgets
node_widgets -->|"reads service state"| node_services
node_user -->|"interacts with desktop"| node_shell_root
node_user -->|"requests profile action"| node_profile_cli
node_profile_cli -->|"dispatches command"| node_profile_manager
node_profile_manager -->|"audits profile"| node_profile_scanner
node_profile_manager -.->|"requests review"| node_codex_review
node_profile_manager -->|"tracks managed changes"| node_state

click node_installer "https://github.com/grapes7000/arch-wm-install/blob/main/install.sh"
click node_stages "https://github.com/grapes7000/arch-wm-install/blob/main/installer/runtime.py"
click node_entry "https://github.com/grapes7000/arch-wm-install/blob/main/installer/entry.py"
click node_state "https://github.com/grapes7000/arch-wm-install/blob/main/installer/state.py"
click node_manifests "https://github.com/grapes7000/arch-wm-install/tree/main/manifests"
click node_theme_cli "https://github.com/grapes7000/arch-wm-install/blob/main/modules/theme-engine/bin/theme"
click node_theme_components "https://github.com/grapes7000/arch-wm-install/blob/main/modules/theme-engine/bin/theme_components.py"
click node_theme_catalog "https://github.com/grapes7000/arch-wm-install/tree/main/modules/theme-engine/schema"
click node_theme_outputs "https://github.com/grapes7000/arch-wm-install/tree/main/modules/theme-engine"
click node_shell_root "https://github.com/grapes7000/arch-wm-install/blob/main/modules/shell/shell.qml"
click node_shell_core "https://github.com/grapes7000/arch-wm-install/tree/main/modules/shell/core"
click node_layouts "https://github.com/grapes7000/arch-wm-install/tree/main/modules/shell/layouts"
click node_widgets "https://github.com/grapes7000/arch-wm-install/tree/main/modules/shell/widgets"
click node_services "https://github.com/grapes7000/arch-wm-install/tree/main/modules/shell/services"
click node_hyprland "https://github.com/grapes7000/arch-wm-install/tree/main/modules/hyprland/config"
click node_terminal "https://github.com/grapes7000/arch-wm-install/tree/main/modules/terminal"
click node_login "https://github.com/grapes7000/arch-wm-install/tree/main/modules/login"
click node_profile_cli "https://github.com/grapes7000/arch-wm-install/blob/main/desktop_manager/cli.py"
click node_profile_manager "https://github.com/grapes7000/arch-wm-install/blob/main/desktop_manager/manager.py"
click node_profile_scanner "https://github.com/grapes7000/arch-wm-install/blob/main/desktop_manager/scanner.py"
click node_codex_review "https://github.com/grapes7000/arch-wm-install/blob/main/desktop_manager/codex_review.py"

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_installer,node_stages,node_entry,node_state,node_manifests,node_user toneBlue
class node_theme_cli,node_theme_components,node_theme_catalog,node_theme_outputs toneAmber
class node_shell_root,node_shell_core,node_layouts,node_widgets,node_services toneMint
class node_hyprland,node_terminal,node_login toneRose
class node_profile_cli,node_profile_manager,node_profile_scanner,node_codex_review,node_arch,node_upstream toneIndigo
```

## Components

### Installation and Recovery

- [Installer CLI](https://github.com/grapes7000/arch-wm-install/blob/main/install.sh): `install.sh`
- [Stage runtime](https://github.com/grapes7000/arch-wm-install/blob/main/installer/runtime.py): `installer/runtime.py`
- [Installer entry](https://github.com/grapes7000/arch-wm-install/blob/main/installer/entry.py): `installer/entry.py`
- [Run state and backups](https://github.com/grapes7000/arch-wm-install/blob/main/installer/state.py): `installer/state.py`
- [Package manifests](https://github.com/grapes7000/arch-wm-install/tree/main/manifests): `manifests`

### Theme Engine

- [Theme commands](https://github.com/grapes7000/arch-wm-install/blob/main/modules/theme-engine/bin/theme): `modules/theme-engine/bin/theme`
- [Theme generators](https://github.com/grapes7000/arch-wm-install/blob/main/modules/theme-engine/bin/theme_components.py): `modules/theme-engine/bin/theme_components.py`
- [Theme catalog and schema](https://github.com/grapes7000/arch-wm-install/tree/main/modules/theme-engine/schema): `modules/theme-engine/schema`
- [Generated theme targets](https://github.com/grapes7000/arch-wm-install/tree/main/modules/theme-engine): `modules/theme-engine`

### Quickshell Platform

- [Shell entry and surfaces](https://github.com/grapes7000/arch-wm-install/blob/main/modules/shell/shell.qml): `modules/shell/shell.qml`
- [Shell registries and context](https://github.com/grapes7000/arch-wm-install/tree/main/modules/shell/core): `modules/shell/core`
- [Surface layouts](https://github.com/grapes7000/arch-wm-install/tree/main/modules/shell/layouts): `modules/shell/layouts`
- [Portable widgets](https://github.com/grapes7000/arch-wm-install/tree/main/modules/shell/widgets): `modules/shell/widgets`
- [System services](https://github.com/grapes7000/arch-wm-install/tree/main/modules/shell/services): `modules/shell/services`

### Desktop Runtime

- [Hyprland configuration](https://github.com/grapes7000/arch-wm-install/tree/main/modules/hyprland/config): `modules/hyprland/config`
- [Terminal configuration](https://github.com/grapes7000/arch-wm-install/tree/main/modules/terminal): `modules/terminal`
- [Login configuration](https://github.com/grapes7000/arch-wm-install/tree/main/modules/login): `modules/login`

### Profile Management

- [Profile manager CLI](https://github.com/grapes7000/arch-wm-install/blob/main/desktop_manager/cli.py): `desktop_manager/cli.py`
- [Profile planning and activation](https://github.com/grapes7000/arch-wm-install/blob/main/desktop_manager/manager.py): `desktop_manager/manager.py`
- [Profile safety scanner](https://github.com/grapes7000/arch-wm-install/blob/main/desktop_manager/scanner.py): `desktop_manager/scanner.py`
- [Optional Codex review](https://github.com/grapes7000/arch-wm-install/blob/main/desktop_manager/codex_review.py): `desktop_manager/codex_review.py`

### Other components

- **Desktop user**
- **Arch Linux system**
- **Theme upstream**

## Connections

- Desktop user → Installer CLI: selects profile
- Installer CLI → Installer entry: dispatches
- Installer entry → Stage runtime: configures stages
- Stage runtime → Run state and backups: records backups
- Stage runtime → Package manifests: reads packages
- Stage runtime → Arch Linux system: installs configuration
- Theme upstream → Theme catalog and schema: provides catalog
- Theme commands → Theme catalog and schema: reads themes
- Theme commands → Theme generators: generates targets
- Theme generators → Generated theme targets: writes targets
- Stage runtime → Theme commands: installs theme engine
- Generated theme targets → Hyprland configuration: supplies theme settings
- Generated theme targets → Shell entry and surfaces: supplies theme settings
- Generated theme targets → Terminal configuration: supplies theme settings
- Shell entry and surfaces → Shell registries and context: uses registries
- Shell entry and surfaces → Surface layouts: loads layouts
- Shell registries and context → Portable widgets: resolves widgets
- Portable widgets → System services: reads service state
- Desktop user → Shell entry and surfaces: interacts with desktop
- Desktop user → Profile manager CLI: requests profile action
- Profile manager CLI → Profile planning and activation: dispatches command
- Profile planning and activation → Profile safety scanner: audits profile
- Profile planning and activation → Optional Codex review: requests review
- Profile planning and activation → Run state and backups: tracks managed changes