# caelestia-dots/scripts architecture

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

- Interactive diagram: https://gitdiagram.com/caelestia-dots/scripts
- Repository: https://github.com/caelestia-dots/scripts

## Overview

##### File structure
- Top‐level scripts:
- main.fish – the CLI dispatcher
- *.fish scripts (install/, toggles/, and standalone scripts) – implementations of each subcommand
- util.fish – shared utility functions
- completions/ – Fish completion definitions
- Patterns:
- Modular subcommands under folders (install/, toggles/, scheme/)
- A “plugin”-like system where each subdir groups scripts for one category
- Shared utilities and data used by multiple commands
- Mixed-language: Fish for CLI and orchestration; Python for more complex scheme logic

##### README for additional insights
- Confirms the CLI interface and available commands
- Installation is simply cloning the repo and running install/scripts.fish

a. Main components
- Fish Interpreter
- Entrypoint – main.fish (CLI parser & dispatcher)
- Subcommand modules:
– install/*
– toggles/*
– standalone scripts: screenshot.fish, record.fish, emoji-picker.fish, wallpaper.fish, clipboard.fish, clipboard-delete.fish, pip.fish
– scheme module: scheme/main.fish, gen-scheme.fish, gen-print-scheme.fish, autoadjust.py, score.py
- Shared utilities: util.fish
- Data store: data/ (config.json, emojis.txt, schemes/…)
- Completion definitions: completions/caelestia.fish
- External services & binaries: Hyprland, slurp, ffmpeg, fish shell, etc.
- User environment: PATH, ~/.local/bin

b. Relationships & interactions
- User invokes `caelestia <command>` → Fish interpreter loads main.fish
- main.fish parses the command name and arguments
- Dispatches to the corresponding script or function in install/, toggles/, scheme/, or standalone .fish files
- That script:
– Sources util.fish for shared functions
– If a scheme command, may spawn Python scripts (autoadjust.py, score.py) to process schemes, then returns results to Fish
– Invokes external binaries (e.g., slurp for screenshots, Hyprland commands for workspace actions)
– Optionally writes logs or updates files in the user’s home directory
- Fish completions script provides tab-completion for the CLI

c. Architectural patterns & design principles
- Modular “subcommand” structure – each feature is isolated in its own folder/script
- Shared library (util.fish) to avoid code duplication
- Command dispatcher (main.fish) implements the CLI façade pattern
- Layered approach: CLI → command module → util/data → external binaries

d. Key technologies & libraries
- Fish shell for scripting and CLI
- External CLI tools (Hyprland, ffmpeg, slurp, etc.)
- JSON for config (data/config.json)

##### Elements
- From user → Fish interpreter → main.fish
- From main.fish → subcommand scripts
- From scripts → util.fish and data/
- From scripts → external binaries
- From scheme.fish → Python scripts → back to Fish
- Python scripts in another
- Data files in a third
- External services/binaries in a fourth

##### Detailed breakdown
- Layer 1 (left): User’s terminal
- Layer 2: Fish interpreter → main.fish (CLI dispatcher)
- Layer 3: Branching into modules:
- install/
- toggles/
- scheme/ (with embedded Python processing)
- standalone scripts (screenshot.fish, record.fish, etc.)
- Layer 4: Common util.fish and data/
- Layer 5 (right): External tools and services
- Feedback loops where scripts read/write data, and where Python returns data to Fish

## Diagram (Mermaid)

```mermaid
graph TB
    %% Layer 1: User
    User["User Terminal"]:::external

    %% Layer 2: Fish Interpreter & Entrypoint
    subgraph "CLI Layer"
        Fish["Fish Interpreter"]:::external
        Entrypoint["main.fish (CLI Entrypoint)"]:::script
    end

    %% Layer 3: Subcommand Modules
    subgraph "Modules"
        subgraph "Install Module"
            InstallDispatcher["install/scripts.fish"]:::script
            I1["install/btop.fish"]:::script
            I2["install/discord.fish"]:::script
            I3["install/firefox.fish"]:::script
            I4["install/fish.fish"]:::script
            I5["install/foot.fish"]:::script
            I6["install/fuzzel.fish"]:::script
            I7["install/gtk.fish"]:::script
            I8["install/hypr.fish"]:::script
            I9["install/qt.fish"]:::script
            I10["install/safeeyes.fish"]:::script
            I11["install/slurp.fish"]:::script
            I12["install/spicetify.fish"]:::script
            I13["install/util.fish"]:::script
            I14["install/vscode.fish"]:::script
            I15["install/shell.fish"]:::script
        end
        subgraph "Toggles Module"
            TogUtil["toggles/util.fish"]:::script
            TogWS["toggles/specialws.fish"]:::script
        end
        subgraph "Scheme Module"
            SM_Main["scheme/main.fish"]:::script
            SM_Gen["scheme/gen-scheme.fish"]:::script
            SM_Print["scheme/gen-print-scheme.fish"]:::script
            SM_PySubgraph["Python Processors"]
            SM_Auto["autoadjust.py"]:::python
            SM_Score["score.py"]:::python
        end
        subgraph "Standalone Scripts"
            SS1["clipboard.fish"]:::script
            SS2["clipboard-delete.fish"]:::script
            SS3["emoji-picker.fish"]:::script
            SS4["screenshot.fish"]:::script
            SS5["record.fish"]:::script
            SS6["wallpaper.fish"]:::script
            SS7["pip.fish"]:::script
            SS8["workspace-action.sh"]:::script
        end
    end

    %% Layer 4: Shared Utilities & Data
    subgraph "Core Resources"
        Util["util.fish"]:::script
        subgraph "Data Store"
            Config["config.json"]:::data
            Emojis["emojis.txt"]:::data
            Schemes["schemes/"]:::data
        end
        Completions["completions/caelestia.fish"]:::script
    end

    %% Layer 5: External Tools
    subgraph "External Tools"
        Hypr["Hyprland"]:::external
        Slurp["slurp"]:::external
        FFmpeg["ffmpeg"]:::external
        FishShell["Fish Shell"]:::external
    end

    %% Connections
    User --> Fish
    Fish --> Entrypoint
    Entrypoint --> InstallDispatcher
    Entrypoint --> TogUtil
    Entrypoint --> SM_Main
    Entrypoint --> SS1
    Entrypoint --> SS2
    Entrypoint --> SS3
    Entrypoint --> SS4
    Entrypoint --> SS5
    Entrypoint --> SS6
    Entrypoint --> SS7
    Entrypoint --> SS8

    InstallDispatcher --> I1
    InstallDispatcher --> I2
    InstallDispatcher --> I3
    InstallDispatcher --> I4
    InstallDispatcher --> I5
    InstallDispatcher --> I6
    InstallDispatcher --> I7
    InstallDispatcher --> I8
    InstallDispatcher --> I9
    InstallDispatcher --> I10
    InstallDispatcher --> I11
    InstallDispatcher --> I12
    InstallDispatcher --> I13
    InstallDispatcher --> I14
    InstallDispatcher --> I15

    SM_Main --> SM_Gen
    SM_Main --> SM_Print
    SM_Gen --> SM_Auto
    SM_Print --> SM_Score
    SM_Auto --> SM_Main
    SM_Score --> SM_Main

    %% Shared util and data usage
    InstallDispatcher --> Util
    TogUtil --> Util
    SM_Main --> Util
    SS1 --> Util
    SS2 --> Util
    SS3 --> Util
    SS4 --> Util
    SS5 --> Util
    SS6 --> Util
    SS7 --> Util
    SS8 --> Util

    InstallDispatcher --> Config
    InstallDispatcher --> Schemes
    TogUtil --> Config
    SM_Main --> Schemes
    SM_Main --> Config
    SS3 --> Emojis

    %% External tool invocations
    SS4 --> Slurp
    SS5 --> FFmpeg
    SS8 --> Hypr
    Entrypoint --> FishShell

    %% Completions
    FishShell --> Completions

    %% Click Events
    click Entrypoint "https://github.com/caelestia-dots/scripts/blob/main/main.fish"
    click Util "https://github.com/caelestia-dots/scripts/blob/main/util.fish"
    click Completions "https://github.com/caelestia-dots/scripts/blob/main/completions/caelestia.fish"
    click Config "https://github.com/caelestia-dots/scripts/blob/main/data/config.json"
    click Emojis "https://github.com/caelestia-dots/scripts/blob/main/data/emojis.txt"
    click Schemes "https://github.com/caelestia-dots/scripts/tree/main/data/schemes/"
    click InstallDispatcher "https://github.com/caelestia-dots/scripts/blob/main/install/scripts.fish"
    click I1 "https://github.com/caelestia-dots/scripts/blob/main/install/btop.fish"
    click I2 "https://github.com/caelestia-dots/scripts/blob/main/install/discord.fish"
    click I3 "https://github.com/caelestia-dots/scripts/blob/main/install/firefox.fish"
    click I4 "https://github.com/caelestia-dots/scripts/blob/main/install/fish.fish"
    click I5 "https://github.com/caelestia-dots/scripts/blob/main/install/foot.fish"
    click I6 "https://github.com/caelestia-dots/scripts/blob/main/install/fuzzel.fish"
    click I7 "https://github.com/caelestia-dots/scripts/blob/main/install/gtk.fish"
    click I8 "https://github.com/caelestia-dots/scripts/blob/main/install/hypr.fish"
    click I9 "https://github.com/caelestia-dots/scripts/blob/main/install/qt.fish"
    click I10 "https://github.com/caelestia-dots/scripts/blob/main/install/safeeyes.fish"
    click I11 "https://github.com/caelestia-dots/scripts/blob/main/install/slurp.fish"
    click I12 "https://github.com/caelestia-dots/scripts/blob/main/install/spicetify.fish"
    click I13 "https://github.com/caelestia-dots/scripts/blob/main/install/util.fish"
    click I14 "https://github.com/caelestia-dots/scripts/blob/main/install/vscode.fish"
    click I15 "https://github.com/caelestia-dots/scripts/blob/main/install/shell.fish"
    click TogUtil "https://github.com/caelestia-dots/scripts/blob/main/toggles/util.fish"
    click TogWS "https://github.com/caelestia-dots/scripts/blob/main/toggles/specialws.fish"
    click SM_Main "https://github.com/caelestia-dots/scripts/blob/main/scheme/main.fish"
    click SM_Gen "https://github.com/caelestia-dots/scripts/blob/main/scheme/gen-scheme.fish"
    click SM_Print "https://github.com/caelestia-dots/scripts/blob/main/scheme/gen-print-scheme.fish"
    click SM_Auto "https://github.com/caelestia-dots/scripts/blob/main/scheme/autoadjust.py"
    click SM_Score "https://github.com/caelestia-dots/scripts/blob/main/scheme/score.py"
    click SS1 "https://github.com/caelestia-dots/scripts/blob/main/clipboard.fish"
    click SS2 "https://github.com/caelestia-dots/scripts/blob/main/clipboard-delete.fish"
    click SS3 "https://github.com/caelestia-dots/scripts/blob/main/emoji-picker.fish"
    click SS4 "https://github.com/caelestia-dots/scripts/blob/main/screenshot.fish"
    click SS5 "https://github.com/caelestia-dots/scripts/blob/main/record.fish"
    click SS6 "https://github.com/caelestia-dots/scripts/blob/main/wallpaper.fish"
    click SS7 "https://github.com/caelestia-dots/scripts/blob/main/pip.fish"
    click SS8 "https://github.com/caelestia-dots/scripts/blob/main/workspace-action.sh"

    %% Styles
    classDef script fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef python fill:#d4edda,stroke:#333,stroke-width:1px
    classDef data fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef external fill:#f8f9fa,stroke:#333,stroke-width:1px
```
