# archcraft-os/archcraft-openbox architecture

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

- Interactive diagram: https://gitdiagram.com/archcraft-os/archcraft-openbox
- Repository: https://github.com/archcraft-os/archcraft-openbox

## Overview

##### Project Type and Purpose
- This is neither a web app nor a service-oriented system, but a Linux configuration/theme package for the Openbox window manager (an Archcraft Openbox “dotfiles” / theming repository).
- It provides:
- A PKGBUILD and install scripts to build/package the config.
- A “files/” directory containing per-application config snippets (Alacritty, Kitty, Rofi, Tint2, Polybar, Plank, pipemenus, Nitrogen, etc.).
- A “themes/” directory of dozens of complete theme sets, each with subfolders for polybar, rofi, tint2, wallpaper, and an apply.sh script.

##### File-Structure Analysis
- Top-level:
- build.sh / PKGBUILD / archcraft-openbox.install → build & package management
- files/ → application configurations and scripts
- themes/ → multiple theme bundles
- The patterns show a clear separation of concerns:
- Build & install layer → packaging logic
- Config layer → static config files and helper scripts
- Themes layer → theme directories, each with its own apply.sh

##### README Insights
- Single documentation link pointing to Archcraft Openbox wiki
- No embedded architecture doc, so we reverse-engineer from the file tree

##### Main Components & Relationships
a. Components
- Build/Package Component: build.sh, PKGBUILD, archcraft-openbox.install
- Configuration Component: files/ directory
- Theme Component: themes/ directory (sub-themes)
- Runtime Components: Openbox WM, Alacritty, Kitty, Rofi, Polybar, Tint2, Plank, pipemenus, Nitrogen, NetworkManager-DMenu scripts
b. Interactions
1. Developer runs build.sh → invokes PKGBUILD → produces an Arch package
2. Package installer (pacman) triggers archcraft-openbox.install → copies files/* to ~/.config and themes/* to ~/.config/archcraft-themes
3. At session start:
- Openbox reads its rc.xml, menu definitions, autostart
- Autostart scripts launch Polybar, Tint2, Plank, Nitrogen, keybindings, rofi menus, etc., each reading their configs from ~/.config
4. Theme switching:
- User runs themes/<theme-name>/apply.sh → executes a series of file copies or symlinks to update each component’s config → restarts/reloads affected components
c. Architectural Patterns
- Separation of build vs. config vs. theme data
- Declarative theme bundles with a uniform structure (apply.sh + subfolders)
- Convention-over-configuration: each app expects config in ~/.config/<app>
d. Key Technologies
- Shell scripts (bash) for build/install/apply
- pacman packaging (PKGBUILD)
- Openbox WM
- Applications: Alacritty, Kitty, Rofi, Polybar, Tint2, Plank, Nitrogen, NetworkManager-DMenu

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Repository Layer
    subgraph "Repository"
        BuildSH["build.sh"]:::build
        PKGBUILD["PKGBUILD"]:::build
        InstallScript["archcraft-openbox.install"]:::build
    end

    BuildSH --> PKGBUILD
    PKGBUILD --> Package["Arch Package"]:::build

    %% User System Layer
    subgraph "User System"
        Installer["Installer"]:::build
        ConfigStore["files/ (Config Store)"]:::config
        ThemesStore["themes/ (Theme Store)"]:::theme
    end

    Package --> Installer
    Installer -->|"copies files/"| ConfigStore
    Installer -->|"copies themes/"| ThemesStore

    %% Configuration Deployment
    subgraph "User Config (~/.config)"
        CfgAlacritty["alacritty/"]:::config
        CfgKitty["kitty/"]:::config
        CfgOpenbox["openbox/ (rc.xml & theming)"]:::config
        CfgNitrogen["nitrogen/"]:::config
        CfgPlank["plank/"]:::config
        CfgPipemenus["pipemenus/"]:::config
        CfgScripts["scripts/"]:::config
        CfgNetwork["networkmanager-dmenu/"]:::config
    end

    ConfigStore --> CfgAlacritty
    ConfigStore --> CfgKitty
    ConfigStore --> CfgOpenbox
    ConfigStore --> CfgNitrogen
    ConfigStore --> CfgPlank
    ConfigStore --> CfgPipemenus
    ConfigStore --> CfgScripts
    ConfigStore --> CfgNetwork

    %% Theme Switching
    ThemesStore --> ThemeForest["forest/ apply.sh"]:::theme
    ThemesStore --> ThemesAll["...other themes..."]:::theme
    ThemeForest -->|"apply.sh"| CfgAlacritty
    ThemeForest -->|"apply.sh"| CfgKitty
    ThemeForest -->|"apply.sh"| CfgOpenbox

    %% Runtime Layer
    subgraph "Runtime (Openbox Session)"
        Openbox["Openbox WM"]:::runtime
        Polybar["Polybar"]:::runtime
        Tint2["Tint2"]:::runtime
        PlankApp["Plank"]:::runtime
        NitrogenApp["Nitrogen"]:::runtime
        PipemenusApp["Pipemenus"]:::runtime
        RofiApp["Rofi"]:::runtime
    end

    Openbox -->|"autostart"| Polybar
    Openbox -->|"autostart"| Tint2
    Openbox -->|"autostart"| PlankApp
    Openbox -->|"autostart"| NitrogenApp
    Openbox -->|"autostart"| PipemenusApp
    Openbox -->|"autostart"| RofiApp

    %% Click Events
    click BuildSH "https://github.com/archcraft-os/archcraft-openbox/blob/main/build.sh"
    click PKGBUILD "https://github.com/archcraft-os/archcraft-openbox/tree/main/PKGBUILD"
    click InstallScript "https://github.com/archcraft-os/archcraft-openbox/blob/main/archcraft-openbox.install"
    click ConfigStore "https://github.com/archcraft-os/archcraft-openbox/tree/main/files/"
    click CfgAlacritty "https://github.com/archcraft-os/archcraft-openbox/tree/main/files/alacritty/"
    click CfgKitty "https://github.com/archcraft-os/archcraft-openbox/tree/main/files/kitty/"
    click CfgOpenbox "https://github.com/archcraft-os/archcraft-openbox/blob/main/files/rc.xml"
    click CfgOpenbox "https://github.com/archcraft-os/archcraft-openbox/tree/main/files/ob-random/openbox-3/themerc"
    click CfgOpenbox "https://github.com/archcraft-os/archcraft-openbox/blob/main/files/obmenu-generator/config.pl"
    click CfgOpenbox "https://github.com/archcraft-os/archcraft-openbox/blob/main/files/obmenu-generator/schema.pl"
    click CfgScripts "https://github.com/archcraft-os/archcraft-openbox/tree/main/files/scripts/"
    click CfgNetwork "https://github.com/archcraft-os/archcraft-openbox/blob/main/files/networkmanager-dmenu/config.ini"
    click CfgNitrogen "https://github.com/archcraft-os/archcraft-openbox/blob/main/files/nitrogen/bg-saved.cfg"
    click CfgNitrogen "https://github.com/archcraft-os/archcraft-openbox/blob/main/files/nitrogen/nitrogen.cfg"
    click CfgPlank "https://github.com/archcraft-os/archcraft-openbox/tree/main/files/plank/dock1/"
    click CfgPipemenus "https://github.com/archcraft-os/archcraft-openbox/tree/main/files/pipemenus/"
    click ThemesStore "https://github.com/archcraft-os/archcraft-openbox/tree/main/themes/"
    click ThemeForest "https://github.com/archcraft-os/archcraft-openbox/blob/main/themes/forest/apply.sh"

    %% Styles
    classDef build fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef config fill:#90EE90,stroke:#000,stroke-width:1px
    classDef theme fill:#FFFFE0,stroke:#000,stroke-width:1px
    classDef runtime fill:#D3D3D3,stroke:#000,stroke-width:1px
```
