# akitaonrails/omakub-mj architecture

> Architecture diagram of the GitHub repository akitaonrails/omakub-mj, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/akitaonrails/omakub-mj
- Repository: https://github.com/akitaonrails/omakub-mj

## Overview

##### Project type and purpose
- This is a CLI-driven, opinionated bootstrap/automation tool for turning a fresh Manjaro GNOME install into a fully-configured web-development workstation.
- It consists entirely of shell scripts, configuration files, themes, migrations and small “application‐wrapper” scripts.

##### File structure
- Top-level orchestrator:
– boot.sh: downloads & kicks off the installer
– install.sh: entry point for all install sequences
- Installation modules (install/):
– install/desktop/: desktop-app installers & settings
– install/terminal/: CLI-tool installers & settings
– install/first-run-choices.sh, check-version.sh, etc.
- Configuration modules:
– configs/: concrete config files for Alacritty, Neovim, Zsh, VSCode, Ulauncher, etc.
– defaults/: baseline “defaults” for Bash, Zsh, xcompose
- Theme modules:
– themes/: per-theme subfolders containing theme-specific configs/scripts
– set-* scripts to apply a theme globally
- Applications wrappers (applications/ & bin/):
– applications/*.sh: short launcher scripts for installed apps
– bin/: utility scripts (omakub, omakub-sub) for driving menus, font sizes, installer tasks
- Migration scripts:
– migrations/*.sh: idempotent scripts to migrate existing installs to new versions
- Uninstaller:
– uninstall/*.sh: reverse of install for apps, languages, Docker, shell prompt, etc.

##### Readme insights
- Single‐command “boot” → orchestrator runs installer → installs packages, applies configs, sets themes.
- Integrates external systems: pacman/Docker/flatpak, GNOME settings, Zellij, Neovim, Atuin.

##### Main components & interactions
a. Core orchestrator
- boot.sh/download pipeline → install.sh
- check-version → first-run choices
b. Install modules
- Desktop installers → GNOME apps + settings
- Terminal installers → CLI tools + shell libs
- Each installer invokes specific scripts under install/desktop or install/terminal
c. Config & defaults application
- Post-install, copy or symlink configs/ & defaults/ into $HOME/.config or shell rc files
d. Themes
- Developer selects theme → calls set-chrome, set-gnome, set-vscode, etc.
- Scripts under themes/* orchestrate per-component theming
e. Migration
- On each run, detect version change → execute pending migrations/*.sh
f. Uninstaller
- mirror image of installers to remove packages and revert configs
g. Application wrappers & utilities
- invoked by user for quick access or further configuration

##### Architectural patterns & principles
- Modular directories by concern (install, config, theme, migrations, uninstall)
- Orchestrator + plugins pattern: installer calls sub-scripts like plugins
- Idempotence: each script can be re-run safely
- Convention over configuration: fixed layout under configs/ and themes/

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Orchestrator Layer
    subgraph "Orchestrator Layer"
        direction TB
        BOOT["boot.sh"]:::orchestrator
        INSTALL["install.sh"]:::orchestrator
        VERSION["check-version.sh"]:::orchestrator
        FIRST["first-run-choices.sh"]:::orchestrator
    end

    %% Install Module Layer
    subgraph "Install Module Layer"
        direction TB
        subgraph "Desktop Installers"
            DESK_ORCH["desktop.sh"]:::install
            DESK_DIR["install/desktop/"]:::install
        end
        subgraph "Terminal Installers"
            TERM_ORCH["terminal.sh"]:::install
            TERM_DIR["install/terminal/"]:::install
        end
    end

    %% Config & Defaults Layer
    subgraph "Config & Defaults Layer"
        direction TB
        CONFIGS["configs/"]:::config
        DEFAULTS["defaults/"]:::config
    end

    %% Theme Layer
    subgraph "Theme Layer"
        direction TB
        THEMES_DIR["themes/"]:::theme
        SET_CHROME["set-chrome-theme.sh"]:::theme
        SET_GNOME["set-gnome-theme.sh"]:::theme
        SET_VSCODE["set-vscode-theme.sh"]:::theme
    end

    %% Migration Layer
    subgraph "Migration Layer"
        direction TB
        MIGRATIONS["migrations/"]:::migration
    end

    %% Uninstaller Layer
    subgraph "Uninstaller Layer"
        direction TB
        UNINSTALL_DIR["uninstall/"]:::uninstall
    end

    %% App Wrappers & Utilities
    subgraph "App Wrappers & Utilities"
        direction TB
        APPS["applications/"]:::utility
        BIN["bin/"]:::utility
    end

    %% External Services
    subgraph "External Dependencies"
        direction TB
        PACMAN(("Pacman/Flatpak/Docker")):::external
        GNOME(("GNOME Settings Daemon")):::external
        TERMINAL(("Terminals/Shell/Editors")):::external
    end

    %% Flow
    BOOT --> INSTALL
    INSTALL --> VERSION
    VERSION --> FIRST
    FIRST --> DESK_ORCH
    FIRST --> TERM_ORCH

    DESK_ORCH --> DESK_DIR
    TERM_ORCH --> TERM_DIR

    DESK_DIR --> CONFIGS
    TERM_DIR --> CONFIGS

    CONFIGS --> DEFAULTS
    DEFAULTS --> THEMES_DIR

    THEMES_DIR --> SET_CHROME
    THEMES_DIR --> SET_GNOME
    THEMES_DIR --> SET_VSCODE

    SET_CHROME --> MIGRATIONS
    SET_GNOME --> MIGRATIONS
    SET_VSCODE --> MIGRATIONS

    MIGRATIONS --> UNINSTALL_DIR
    UNINSTALL_DIR --> CONFIGS

    APPS --> BIN
    BIN --> FIRST

    PACMAN --> DESK_ORCH
    PACMAN --> TERM_ORCH
    GNOME --> DESK_ORCH
    TERMINAL --> TERM_ORCH

    %% Click Events
    click BOOT "https://github.com/akitaonrails/omakub-mj/blob/stable/./boot.sh"
    click INSTALL "https://github.com/akitaonrails/omakub-mj/blob/stable/./install.sh"
    click VERSION "https://github.com/akitaonrails/omakub-mj/blob/stable/./install/check-version.sh"
    click FIRST "https://github.com/akitaonrails/omakub-mj/blob/stable/./install/first-run-choices.sh"
    click DESK_ORCH "https://github.com/akitaonrails/omakub-mj/blob/stable/./install/desktop.sh"
    click DESK_DIR "https://github.com/akitaonrails/omakub-mj/tree/stable/./install/desktop/"
    click TERM_ORCH "https://github.com/akitaonrails/omakub-mj/blob/stable/./install/terminal.sh"
    click TERM_DIR "https://github.com/akitaonrails/omakub-mj/tree/stable/./install/terminal/"
    click CONFIGS "https://github.com/akitaonrails/omakub-mj/tree/stable/./configs/"
    click DEFAULTS "https://github.com/akitaonrails/omakub-mj/tree/stable/./defaults/"
    click THEMES_DIR "https://github.com/akitaonrails/omakub-mj/tree/stable/./themes/"
    click SET_CHROME "https://github.com/akitaonrails/omakub-mj/blob/stable/./themes/set-chrome-theme.sh"
    click SET_GNOME "https://github.com/akitaonrails/omakub-mj/blob/stable/./themes/set-gnome-theme.sh"
    click SET_VSCODE "https://github.com/akitaonrails/omakub-mj/blob/stable/./themes/set-vscode-theme.sh"
    click MIGRATIONS "https://github.com/akitaonrails/omakub-mj/tree/stable/./migrations/"
    click UNINSTALL_DIR "https://github.com/akitaonrails/omakub-mj/tree/stable/./uninstall/"
    click APPS "https://github.com/akitaonrails/omakub-mj/tree/stable/./applications/"
    click BIN "https://github.com/akitaonrails/omakub-mj/tree/stable/./bin/"

    %% Styles
    classDef orchestrator fill:#9fdf9f,stroke:#333,stroke-width:1px
    classDef install fill:#9fbfdf,stroke:#333,stroke-width:1px
    classDef config fill:#fdf99f,stroke:#333,stroke-width:1px
    classDef theme fill:#d79fdf,stroke:#333,stroke-width:1px
    classDef migration fill:#df9f9f,stroke:#333,stroke-width:1px
    classDef uninstall fill:#c0c0c0,stroke:#333,stroke-width:1px
    classDef utility fill:#f0bf9f,stroke:#333,stroke-width:1px
    classDef external fill:#ffffff,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
