# voronenko/dotfiles architecture

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

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

## Overview

##### Project Type and Purpose
- This is a “dotfiles” project: a configuration and automation framework for shell environments (zsh/bash), developer tools, and utilities.
- Purpose: clone or bootstrap into ~/dotfiles, create symlinks into $HOME, install/enable plugins and external tools, and provide documented helpers (e.g., MkDocs site under mkdocs/).

##### File Structure
Top-level components:
- bootstrap scripts: bootstrap.sh, bootstrap_remote.sh, init.sh, init_simple.sh
- configuration directories:
– “bin/”: scripts and binaries symlinked into ~/bin
– “completions/”: shell completion scripts for many CLIs
– “config/”: app and IDE configs (e.g., webide/, lazycli/, kubie/)
– “helpers/”: shared shell functions and plugins
– “adr/”: architectural decision records tooling
- root-level dotfiles: .zshrc, .bashrc, .gitconfig, tmux.conf, etc.
- Makefile: orchestrates “make install-console-fzf”, “make swiss-knife”, etc.
- GitHub workflows, pre-commit config, .chglog for CHANGELOG generation.

##### Key Insights from README
- README outlines the bootstrap flow: back up existing, symlink dotfiles, clone oh-my-zsh, install shell dependencies, set default shell.
- Describes major features: fzf integration, docker helpers, tmuxinator, direnv, AWS/Cloud tools, MkDocs documentation.

##### Main Components & Their Relationships
a. Installer / Bootstrapper
– Scripts: bootstrap.sh / init.sh → Creates ~/dotfiles_old, symlinks all root-level dotfiles, clones oh-my-zsh, invokes Makefile targets.
b. Dotfiles Repository
– Holds source config files (.zshrc, .gitconfig, tmux.conf, etc.) and subdirectories.
c. Symlinks in $HOME
– .zshrc → ~/dotfiles/zshrc, .vimrc → ~/dotfiles/vimrc, bin/* → ~/bin/*, config/* → ~/.config/*, completions/* → ~/.completions/*.
d. Shell Initialization
– zsh startup loads .zshrc, which sources helpers/, completions/, and env-specific files (e.g., .zshrc.local).
e. External Dependencies & Plugins
– oh-my-zsh (cloned into ~/.oh-my-zsh)
– fzf, direnv, tmuxinator, asdf, nvm, pyenv, etc. (installed via Makefile)
f. Documentation Site
g. ADR Tooling
– adr/ directory provides a CLI for managing architecture decision records.

##### Architectural Patterns & Principles
- Modularity: Each category of config (git, shell, tmux, IDEs, cloud tools) lives in its own folder.
- Convention-over-configuration: predictable symlink paths (dotfile name = source in repo).
- Single source of truth: everything under ~/dotfiles.
- Extensibility: Makefile targets install additional tools on demand.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Installer / Bootstrapper
    subgraph "Installer" 
        direction TB
        BS1["bootstrap.sh"]:::installer
        BS2["bootstrap_remote.sh"]:::installer
        BS3["init.sh"]:::installer
        BS4["init_simple.sh"]:::installer
        MF["Makefile"]:::installer
    end

    %% Dotfiles Repository
    subgraph "Dotfiles Repo"
        direction TB
        ROOT["Root Dotfiles"]:::repo
        BIN["bin/"]:::repo
        COMP["completions/"]:::repo
        HELP["helpers/"]:::repo
        CFG["config/"]:::repo
        ADR["adr/"]:::repo
        MK["mkdocs/"]:::repo
        CODE["code/"]:::repo
        WEB["webide/"]:::repo
    end

    %% Home Directory Symlinks
    subgraph "Home Directory (Symlinks)"
        direction TB
        HZ[".zshrc"]:::repo
        HB[".bashrc"]:::repo
        HG[".gitconfig"]:::repo
        HT[".tmux.conf"]:::repo
        HV[".vimrc"]:::repo
        HS[".screenrc"]:::repo
        HE[".editorconfig"]:::repo
        HC[".chglog"]:::repo
        HP[".pre-commit-config.yaml"]:::repo
        HBIN["~/bin/*"]:::repo
        HCONF["~/.config/*"]:::repo
        HCOMP["~/.completions/*"]:::repo
    end

    %% Shell & Runtime
    subgraph "Shell & Runtime" 
        direction TB
        ZSH["zsh process"]:::runtime
        OHM["oh-my-zsh (~/.oh-my-zsh)"]:::runtime
        FZF["fzf"]:::runtime
        DENV["direnv"]:::runtime
        TMX["tmux/tmuxinator"]:::runtime
        ASDF["asdf/nvm/pyenv"]:::runtime
    end

    %% External Dependencies & Services
    subgraph "External Services" 
        direction TB
        GH["GitHub (plugins)"]:::external
        PM["Package Managers"]:::external
        AWS["Cloud APIs (AWS/GCP)"]:::external
    end

    %% Documentation Build
    subgraph "Documentation" 
        direction TB
        DOCS["MkDocs Build"]:::docs
    end

    %% Connections
    BS1 -->|"invokes"| BS2
    BS2 -->|"invokes"| BS3
    BS3 -->|"invokes"| BS4
    BS4 -->|"uses"| MF
    BS1 -->|"clones repo"| ROOT
    BS1 -->|"creates symlinks"| HZ
    BS1 -->|"creates symlinks"| HB
    BS1 -->|"creates symlinks"| HG
    BS1 -->|"creates symlinks"| HT
    BS1 -->|"creates symlinks"| HV
    BS1 -->|"creates symlinks"| HS
    BS1 -->|"creates symlinks"| HE
    BS1 -->|"creates symlinks"| HC
    BS1 -->|"creates symlinks"| HP

    ROOT --> BIN
    ROOT --> COMP
    ROOT --> HELP
    ROOT --> CFG
    ROOT --> ADR
    ROOT --> MK
    ROOT --> CODE
    ROOT --> WEB

    BIN --> HBIN
    COMP --> HCOMP
    CFG --> HCONF

    HZ -->|sources| ZSH
    HB -->|sources| ZSH
    ZSH -->|loads| HELP
    ZSH -->|loads| COMP
    ZSH -->|loads| CFG
    ZSH -->|uses plugin| OHM

    MF -->|"install tools"| FZF
    MF -->|"install tools"| DENV
    MF -->|"install tools"| TMX
    MF -->|"install tools"| ASDF

    FZF --> PM
    DENV --> PM
    TMX --> PM
    ASDF --> PM

    ROOT --> MK
    MK --> DOCS

    ADR --> DOCS

    BS1 --> GH
    MF --> GH

    %% Click events
    click BS1 "https://github.com/voronenko/dotfiles/blob/master/bootstrap.sh"
    click BS2 "https://github.com/voronenko/dotfiles/blob/master/bootstrap_remote.sh"
    click BS3 "https://github.com/voronenko/dotfiles/blob/master/init.sh"
    click BS4 "https://github.com/voronenko/dotfiles/blob/master/init_simple.sh"
    click MF "https://github.com/voronenko/dotfiles/tree/master/Makefile"
    click ROOT "https://github.com/voronenko/dotfiles/tree/master/bashrc"
    click HZ "https://github.com/voronenko/dotfiles/tree/master/bashrc"
    click HB "https://github.com/voronenko/dotfiles/tree/master/zshrc"
    click HG "https://github.com/voronenko/dotfiles/tree/master/gitconfig"
    click HT "https://github.com/voronenko/dotfiles/blob/master/tmux.conf"
    click HV "https://github.com/voronenko/dotfiles/tree/master/vimrc"
    click HS "https://github.com/voronenko/dotfiles/tree/master/screenrc"
    click HE "https://github.com/voronenko/dotfiles/tree/master/editorconfig"
    click HC "https://github.com/voronenko/dotfiles/blob/master/.chglog"
    click HP "https://github.com/voronenko/dotfiles/blob/master/.pre-commit-config.yaml"
    click BIN "https://github.com/voronenko/dotfiles/tree/master/bin/"
    click COMP "https://github.com/voronenko/dotfiles/tree/master/completions/"
    click HELP "https://github.com/voronenko/dotfiles/tree/master/helpers/"
    click CFG "https://github.com/voronenko/dotfiles/tree/master/config/"
    click ADR "https://github.com/voronenko/dotfiles/tree/master/adr/"
    click MK "https://github.com/voronenko/dotfiles/tree/master/mkdocs/"
    click CODE "https://github.com/voronenko/dotfiles/tree/master/code/"
    click WEB "https://github.com/voronenko/dotfiles/tree/master/webide/"

    %% Styles
    classDef installer fill:#ffa500,stroke:#333;
    classDef repo fill:#ADD8E6,stroke:#333;
    classDef runtime fill:#90EE90,stroke:#333;
    classDef external fill:#f0f0f0,stroke:#333,stroke-dasharray:5 5;
    classDef docs fill:#FFD700,stroke:#333;
```
