# basecamp/omakub architecture

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

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

## Overview

##### Project type and purpose
- Omakub is a CLI-based system configurator and installer for Ubuntu.
- It’s built entirely with shell scripts and organized as an opinionated, plugin-style toolset to bootstrap a modern web-dev workstation in one command.

##### File structure
- Top-level “bin/omakub” and “install.sh” act as entrypoints.
- “install/” contains categorized installers (desktop, terminal, optional, required).
- “uninstall/” mirrors install for cleanup.
- “migrations/” scripts upgrade older Omakub installs.
- “configs/”, “themes/”, “defaults/”, “applications/” hold payloads and configuration templates.
- “EXTENSIONS.md” lists community add-ons; “version” tracks the tool’s release.

##### Key README insights
- Single command invocation that delegates to the orchestrator.
- Opinionated default settings but extensible via extras and extensions.
- Shells, editors, apps, theming, and system preferences.

##### Main components and their interactions
a. Orchestration Layer
– CLI entrypoint (boot.sh / bin/omakub)
– install.sh (master script)
– migrations runner (executes “migrations/*.sh” if version has changed)
b. Module Layer
– Desktop installers (install/desktop/*)
– Terminal installers (install/terminal/*)
– Optional feature installers (nested under “optional/”)
– Uninstallers (“uninstall/…”)
– Application scripts (applications/*.sh)
– Config loaders (configs/, defaults/)
– Theme applier (themes/)
c. External-systems Layer
– Package managers (apt, flatpak)
– GNOME settings (gsettings)
– Third-party CLIs (gum, fzf, lazygit, etc.)
– Shell (bash, zsh), terminal emulator (Alacritty), editor (Neovim), code editor (VSCode)

##### Architectural patterns and design principles
- Modular plugin pattern: each installer or config file is its own script or directory.
- Layered orchestration: entrypoint → version check/migrations → install modules → config/theme apply → exit.
- Convention-over-configuration: directory naming maps to functional phases automatically.
- Idempotent scripts: modules can be re-run without side-effects (leveraging checks inside each .sh).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Orchestration Layer
    subgraph "Orchestration Layer"
        direction TB
        UserCLI["User Shell / CLI"]:::external
        CLIEntrypoint["CLI Entrypoint\nbin/omakub"]:::orchestration
        InstallScript["Master Install Script\ninstall.sh"]:::orchestration
        VersionTracker["Version Tracker\nversion"]:::orchestration
        MigrNeeded{"Version changed?"}:::orchestration
        MigrateRunner["Migration Runner\nmigrate.sh"]:::orchestration
        Migrations["Migration Scripts\nmigrations/*.sh"]:::orchestration
        UninstallRunner["Uninstall Orchestrator\nuninstall.sh"]:::orchestration
        ThemeEngine["Theme Applier\ntheme.sh"]:::orchestration
    end

    UserCLI -->|"invokes"| CLIEntrypoint
    CLIEntrypoint -->|"runs"| InstallScript
    InstallScript -->|"reads"| VersionTracker
    InstallScript -->|"checks"| MigrNeeded
    MigrNeeded -->|Yes| MigrateRunner
    MigrateRunner -->|"executes"| Migrations
    Migrations -->|"back to"| InstallScript
    MigrNeeded -->|No| InstallScript
    InstallScript -->|"orchestrates"| Modules
    InstallScript -->|"applies"| ConfigLayer
    InstallScript -->|"applies"| ThemeEngine
    CLIEntrypoint -->|"invokes"| UninstallRunner

    %% Module Layer
    subgraph "Module Layer"
        direction TB
        subgraph "Install Modules"
            direction TB
            DesktopCore["Desktop Install\ninstall/desktop.sh"]:::modules
            DesktopMods["Desktop Modules\ninstall/desktop/*.sh"]:::modules
            TerminalCore["Terminal Install\ninstall/terminal.sh"]:::modules
            TerminalMods["Terminal Modules\ninstall/terminal/*.sh"]:::modules
            OptionalDesktop["Optional Desktop\ninstall/desktop/optional/*.sh"]:::modules
            OptionalTerminal["Optional Terminal\ninstall/terminal/optional/*.sh"]:::modules
        end
        subgraph "Uninstall Modules"
            direction TB
            UninstallModules["Cleanup Scripts\nuninstall/*.sh"]:::modules
        end
        ApplicationScripts["Application Scripts\napplications/*.sh"]:::modules
        ThemePayloads["Theme Payloads\nthemes/"]:::modules
    end

    InstallScript -->|"runs"| DesktopCore
    InstallScript -->|"runs"| TerminalCore
    DesktopCore --> DesktopMods
    TerminalCore --> TerminalMods
    DesktopMods --> OptionalDesktop
    TerminalMods --> OptionalTerminal
    UninstallRunner -->|"runs"| UninstallModules
    InstallScript -->|"runs"| ApplicationScripts
    ThemeEngine -->|"uses"| ThemePayloads

    %% Config Layer
    subgraph "Config Layer"
        direction TB
        ConfigTemplates["Configuration Templates\nconfigs/"]:::config
        Defaults["Default Configs\ndefaults/"]:::config
    end
    ApplicationScripts -->|"loads"| ConfigTemplates
    ApplicationScripts -->|"loads"| Defaults

    %% External Systems Layer
    subgraph "External Systems"
        direction TB
        Apt["apt"]:::external
        Flatpak["flatpak"]:::external
        Gsettings["gsettings"]:::external
        ThirdPartyCLIs["Third-Party CLIs\n(gum, fzf, lazygit)"]:::external
        Shells["Shells & Terminal\n(bash, zsh, Alacritty)"]:::external
        Editors["Editors\n(Neovim, VSCode)"]:::external
    end
    DesktopMods -->|"installs via"| Apt
    TerminalMods -->|"installs via"| Apt
    OptionalDesktop -->|"installs via"| Flatpak
    OptionalTerminal -->|"installs via"| Flatpak
    ThemeEngine -->|"applies via"| Gsettings
    ApplicationScripts -->|"invokes"| ThirdPartyCLIs
    UserCLI -->|"runs on"| Shells
    ApplicationScripts -->|"configures"| Editors

    %% Click Events
    click CLIEntrypoint "https://github.com/basecamp/omakub/tree/master/bin/omakub"
    click InstallScript "https://github.com/basecamp/omakub/blob/master/install.sh"
    click MigrateRunner "https://github.com/basecamp/omakub/blob/master/bin/omakub-sub/migrate.sh"
    click Migrations "https://github.com/basecamp/omakub/tree/master/migrations/"
    click DesktopCore "https://github.com/basecamp/omakub/blob/master/install/desktop.sh"
    click DesktopMods "https://github.com/basecamp/omakub/blob/master/install/desktop/*.sh"
    click TerminalCore "https://github.com/basecamp/omakub/blob/master/install/terminal.sh"
    click TerminalMods "https://github.com/basecamp/omakub/blob/master/install/terminal/*.sh"
    click OptionalDesktop "https://github.com/basecamp/omakub/blob/master/install/desktop/optional/*.sh"
    click OptionalTerminal "https://github.com/basecamp/omakub/blob/master/install/terminal/optional/*.sh"
    click UninstallRunner "https://github.com/basecamp/omakub/blob/master/bin/omakub-sub/uninstall.sh"
    click UninstallModules "https://github.com/basecamp/omakub/blob/master/uninstall/*.sh"
    click ApplicationScripts "https://github.com/basecamp/omakub/blob/master/applications/*.sh"
    click ConfigTemplates "https://github.com/basecamp/omakub/tree/master/configs/"
    click Defaults "https://github.com/basecamp/omakub/tree/master/defaults/"
    click ThemeEngine "https://github.com/basecamp/omakub/blob/master/bin/omakub-sub/theme.sh"
    click ThemePayloads "https://github.com/basecamp/omakub/tree/master/themes/"

    %% Styles
    classDef orchestration fill:#cce5ff,stroke:#004085,color:#004085
    classDef modules fill:#d4edda,stroke:#155724,color:#155724
    classDef config fill:#fff3cd,stroke:#856404,color:#856404
    classDef external fill:#ffe5b4,stroke:#cc8400,color:#cc8400
```
