# devnall/dotfiles architecture

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

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

## Overview

This project is a personal dotfiles repository designed to manage and configure your development environment. It includes configurations for your shell (zsh), text editor (vim), terminal multiplexer (tmux), version control (git), and others like starship prompt and ack. Additionally, you have helper scripts (in bin/) and extra configuration files (in config/) for tools like Docker, iTerm2, and plex-meta-manager. The repository also preserves legacy configurations in the archive/ folder, providing a clear separation between current and older setups.

##### Project Type & Purpose
- That this is not a “full-stack” web application or compiler but a set of configuration files (dotfiles) that are meant to be symlinked to your home directory.
- The purpose is to standardize and automate the setup of your development environment across different machines (e.g., macOS and Linux, ARM vs. Intel).

##### File Structure
- Top-Level Files: Multiple dotfiles (.zshrc, .vimrc, .tmux.conf, .gitconfig, etc.) that are directly symlinked to the home folder.
- Directories:
- bin/: Contains custom scripts likely executed from the command line.
- config/: Holds configuration for external tools (docker-compose, iTerm2, plex-meta-manager, sheldon, and starship).
- docs/: Provides cheatsheets and setup instructions for various tools.
- archive/: Stores legacy configurations no longer actively used.
- zsh/: Contains libraries and custom functions supporting zsh configuration.
- Hidden configurations (.ackrc, .vimrc, etc.) indicate a close integration with the UNIX environment.

##### Relevant Insights from README
- README mentions that the dotfiles help manage configurations for zsh, vim, tmux, and starship prompt.
- Specific symlink directions and post-install steps (e.g., setting up Homebrew’s shell environment, installation of vim-plug) outline dependencies and integration across the system.
- The repository is modular and designed to be extended, with reminders to clean up unused aliases and functions, particularly within the zsh configuration.

a. Main Components:
- Dotfiles Repository: The core repository containing configuration files and scripts.
- Home Environment: Your OS’ home directory where the dotfiles are symlinked.
- Shell Configuration (zsh): Represented by .zshrc, the zsh library subdirectory (zsh/lib) with its various components (aliases, path, completions, etc.).
- Editor Configuration (vim): Files like .vimrc and the vim-plug installation; include the archive’s historical vim config files.
- Terminal Multiplexer (tmux): Represented by .tmux.conf.
- Helper Scripts (bin): Custom scripts (e.g., git commands, system scripts) that interact with the environment.
- External Tool Configurations (config/): For Docker, iTerm2, plex-meta-manager, sheldon, starship, etc.
- Documentation (docs/) and Remote TODOs (remote/): Outline additional setups and notes.

b. Relationships and Interactions:
- Symlink Connections: Show how each dotfile from the repository is connected with its counterpart in the home directory.
- Legacy vs. Current: Clearly differentiate between the active configuration files and the archived legacy files.
- Integration among Components: For instance, custom scripts (bin/) that might affect git operations, while zsh functions use these scripts; and config files in "config/" like docker-compose.yml which control containerized environments.

c. Important Architectural Patterns/Design Principles:
- Separation of Concerns: Clearly isolate configurations for different tools (shell, editor, multiplexer, external services).
- Modularity: The repository is designed so that pieces (scripts, configurations) can be updated individually.
- Extendibility: The presence of directories like zsh/lib and docs indicates that adding or modifying functions, aliases, or documentation is anticipated.
- Legacy Preservation: Use of an archive/ directory to retain older configurations for fallback or historical reference.

d. Relevant Technologies/Frameworks/Libraries:
- Shell (zsh) and supporting libraries (zsh/lib, zsh/zfunctions)
- Editor (vim) with plugin management (vim-plug)
- Terminal multiplexer (tmux) and its configuration (.tmux.conf)
- Package management via Homebrew (Brewfile and shell environment setup)
- Various scripts (bash scripts, shell scripts in bin/) that add custom functionality

##### Specific Elements
- Use clear labels for every component (e.g., "zsh Configuration (.zshrc & zsh/lib)", "Vim Configuration (.vimrc + vim-plug)", "Tmux Configuration (.tmux.conf)", "Helper Scripts (bin/)", "External Tool Configs (config/)" and "Legacy Archive (archive/)").
- The flow from repository files to symlinked locations in the home directory.
- How configuration files trigger or integrate with respective external tools.
- Dependencies like the piped command from Homebrew to the shell environment.
- Rectangles for configuration files.
- Ovals or ellipses for external tools.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Dotfiles Repository
    subgraph "Dotfiles Repository"
        DotRepo["Dotfiles Repository"]:::repo
    end

    %% Active Configurations
    subgraph "Active Configurations"
        SC["Shell Configuration (.zshrc & zsh/)"]:::config
        EC["Editor Configuration (.vimrc & vim-plug)"]:::config
        TMUX["Terminal Multiplexer (.tmux.conf)"]:::config
        VC["Version Control (.gitconfig & .gitignore)"]:::config
        HS["Helper Scripts (bin/)"]:::config
        ETC["External Tool Configs (config/)"]:::config
        DOC["Documentation (docs/ & remote/)"]:::config
    end

    %% Sub-nodes for Shell Configuration
    SC --> SC1["zsh/lib"]:::config
    SC --> SC2["zsh/zfunctions"]:::config

    %% Legacy Archive
    subgraph "Legacy Archive"
        LVim["Legacy Vim Configs (.gvimrc, svimrc)"]:::archive
        LTmux["Legacy Tmux Config (.tmuxinator.yml)"]:::archive
        LOthers["Other Legacy Configs"]:::archive
    end

    %% Home Directory
    Home["Home Directory (Symlinked)"]:::home

    %% External Dependencies
    HB["Homebrew"]:::external
    VP["vim-plug"]:::external

    %% Relationships from Dotfiles Repository to Active Configurations
    DotRepo -->|"symlink"| SC
    DotRepo -->|"symlink"| EC
    DotRepo -->|"symlink"| TMUX
    DotRepo -->|"symlink"| VC
    DotRepo -->|"symlink"| HS
    DotRepo -->|"symlink"| ETC
    DotRepo -->|"symlink"| DOC

    %% Symlink connections to Home Directory
    SC -->|"symlink"| Home
    EC -->|"symlink"| Home
    TMUX -->|"symlink"| Home
    VC -->|"symlink"| Home
    HS -->|"symlink"| Home
    ETC -->|"symlink"| Home
    DOC -->|"symlink"| Home

    %% External dependency integrations
    SC -->|"setup"| HB
    EC -->|"plugin"| VP

    %% Integration with Legacy Archive
    EC -->|"legacy"| LVim
    TMUX -->|"legacy"| LTmux

    %% Click Events for Component Mapping
    click DotRepo "https://github.com/devnall/dotfiles/blob/main/.zshrc"
    click SC "https://github.com/devnall/dotfiles/tree/main/zsh/"
    click SC1 "https://github.com/devnall/dotfiles/tree/main/zsh/lib"
    click SC2 "https://github.com/devnall/dotfiles/tree/main/zsh/zfunctions"
    click EC "https://github.com/devnall/dotfiles/blob/main/.vimrc"
    click TMUX "https://github.com/devnall/dotfiles/blob/main/.tmux.conf"
    click VC "https://github.com/devnall/dotfiles/blob/main/.gitconfig"
    click HS "https://github.com/devnall/dotfiles/tree/main/bin/"
    click ETC "https://github.com/devnall/dotfiles/tree/main/config/"
    click DOC "https://github.com/devnall/dotfiles/tree/main/docs/"
    click LVim "https://github.com/devnall/dotfiles/blob/main/archive/.gvimrc"
    click LTmux "https://github.com/devnall/dotfiles/blob/main/archive/tmuxinator.yml"
    click LOthers "https://github.com/devnall/dotfiles/tree/main/archive/"

    %% Class Definitions
    classDef repo fill:#ffe6e6,stroke:#333,stroke-width:2px;
    classDef config fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef archive fill:#ffd6cc,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5;
    classDef home fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef external fill:#ffebcc,stroke:#333,stroke-width:2px;
```
