# spacecabbage/dotfiles architecture

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

- Interactive diagram: https://gitdiagram.com/spacecabbage/dotfiles
- Repository: https://github.com/spacecabbage/dotfiles

## Overview

##### Project Type and Purpose
- This is a “dotfiles” repository: an open-source toolkit for managing personal shell and editor configurations.
- It contains Neovim configs (in Lua), shell and terminal configs (.bashrc, tmux, starship, ghostty), plus a snapshot/backup folder.

##### File Structure Overview
- Top-level directories:
- `.snapshots/` – backups of previous configs.
- `nvim/` & `nvim.bak/` – active and backup Neovim setups.
- `terminal/` – shell and terminal multiplexer configs.
- Key files:
- `nvim/init.lua` – entry point for Neovim config.
- `nvim/lua/*.lua` – individual modules (statusline, LSP, plugins, etc.).
- `terminal/.bashrc`, `.tmux.conf`, `starship.toml` – environment and prompt settings.
- Build & deploy: no compiled artifacts; “deployment” is via `ln -s` symlinks from your $HOME to these files.

##### README Insights
- Installation is simply cloning and symlinking.
- Lists external dependencies: bat, exa, fzf, ripgrep, starship, tmux, Neovim, etc.

a. Main Components
- Dotfiles Repo (Git)
- Symlink Manager / Installer Script (manual ln -s steps)
- Shell Environment Loader (reads `.bashrc`)
- Terminal Multiplexer (tmux, reads `.tmux.conf`)
- Prompt Engine (starship, reads `starship.toml`)
- Neovim Core (init.lua + Lua modules)
- Plugin Manager (lazy.nvim + Mason + lspconfig, etc.)
- External CLI tools (bat, fzf, exa, ripgrep, zellij, zoxide)
b. Relationships & Data Flow
1. User clones repo → creates symlinks → config files appear in `$HOME`.
2. On shell startup → `.bashrc` is sourced → loads aliases, functions, calls starship.
3. Starting tmux → reads `.tmux.conf`.
4. Launching Neovim → `init.lua` loads core modules → invokes plugin manager → plugins lazy-load as needed → LSPs launched via Mason.
5. Plugins and modules call out to external tools (fzf, ripgrep, etc.).
c. Architectural Patterns & Principles
- Modular config: each area (keymaps, options, plugins) is its own Lua module.
- Lazy-loading: plugins are only loaded when invoked.
- Separation of concerns: shell, editor, terminal each in their own subdirectory.
- Versioned backups: `.snapshots/` and `nvim.bak/` provide rollback.
d. Key Technologies & Libraries
- Lua (Neovim API)
- lazy.nvim (plugin manager)
- Mason & lspconfig (LSP installer/config)
- Bash (shell scripting)
- tmux, starship, ghostty (terminal/UX)
- CLI tools (bat, exa, fzf, ripgrep)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Installation Flow
    subgraph "Installation Flow"
        Repo["Dotfiles Repository (Git)"]:::repo
        Install["Symlink Manager / Installer"]:::script
        Home["$HOME (Symlinks)"]:::home
        Repo -->|clone repo| Install
        Install -->|create symlinks| Home
    end

    %% Shell Environment
    subgraph "Shell Environment"
        Bash["Shell Environment Loader (.bashrc)"]:::shell
        Starship["Prompt Engine (starship.toml)"]:::shell
        Home --> Bash
        Bash -->|loads prompt| Starship
    end

    %% Terminal Multiplexer
    subgraph "Terminal Multiplexer"
        Tmux["tmux Configuration (.tmux.conf)"]:::terminal
        Home --> Tmux
    end

    %% Neovim Editor
    subgraph "Neovim Editor"
        NVIM["Neovim Core (init.lua)"]:::editor
        Modules["Neovim Lua Modules"]:::editor
        PluginMgr["Plugin Manager (lazy.nvim)"]:::editor
        LSP["LSP Installer & Config (Mason + lspconfig)"]:::editor
        External["External CLI Tools (bat, fzf, rg, exa)"]:::external

        Home --> NVIM
        NVIM --> Modules
        NVIM --> PluginMgr
        PluginMgr --> LSP
        Modules --> External
        PluginMgr --> External
    end

    %% Backups
    subgraph "Backups"
        Snap["Backup Snapshots (.snapshots/)"]:::backup
        NVIMBak["Neovim Backup Config (nvim.bak/)"]:::backup
        Repo --> Snap
        Repo --> NVIMBak
    end

    %% Click Events
    click Repo "https://github.com/spacecabbage/dotfiles/tree/arch/./"
    click Bash "https://github.com/spacecabbage/dotfiles/blob/arch/terminal/.bashrc"
    click Tmux "https://github.com/spacecabbage/dotfiles/blob/arch/terminal/.tmux.conf"
    click Starship "https://github.com/spacecabbage/dotfiles/blob/arch/terminal/starship.toml"
    click NVIM "https://github.com/spacecabbage/dotfiles/blob/arch/nvim/init.lua"
    click Modules "https://github.com/spacecabbage/dotfiles/tree/arch/nvim/lua/"
    click PluginMgr "https://github.com/spacecabbage/dotfiles/blob/arch/nvim/lazy-lock.json"
    click LSP "https://github.com/spacecabbage/dotfiles/blob/arch/nvim/lua/lsp.lua"
    click Snap "https://github.com/spacecabbage/dotfiles/tree/arch/.snapshots/"
    click NVIMBak "https://github.com/spacecabbage/dotfiles/tree/arch/nvim.bak/"

    %% Styles
    classDef repo fill:#FFE4B5,stroke:#B8860B,stroke-width:2px
    classDef script fill:#FFFACD,stroke:#DAA520,stroke-width:1px,stroke-dasharray: 5 5
    classDef home fill:#E6E6FA,stroke:#9370DB,stroke-width:2px
    classDef shell fill:#E0FFE0,stroke:#008000,stroke-width:1px
    classDef terminal fill:#E0F7FF,stroke:#007BFF,stroke-width:1px
    classDef editor fill:#FFF0E0,stroke:#FF8C00,stroke-width:2px
    classDef external fill:#F0F0F0,stroke:#A9A9A9,stroke-width:1px,stroke-dasharray: 2 2
    classDef backup fill:#FFFFFF,stroke:#A9A9A9,stroke-width:1px,stroke-dasharray: 4 4
```
