# carlosmed/dotfiles architecture

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

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

## Overview

##### Main Components
- Installation Scripts: A central install script (setup.sh in the root and further OS-specific scripts under installs like arch.sh, mac.sh) is responsible for initializing the process.
- Package Directories: The “packages” folder is subdivided into “common,” “linux,” and “mac” directories. The “common” folder contains configurations that apply across systems (e.g., Vim, Zsh, Neovim, polybar, rofi, etc.), whereas the OS-specific folders have configurations or packages unique to that system.
- GNU Stow Integration: The system relies on GNU Stow to create symlinks from these configuration directories to their appropriate target locations on the user’s system.
- Supporting Files: There are additional configuration files such as .gitignore, .stowrc, and documentation (README.md, arch_install.md) that support version control or environment configuration.

##### Relationships and Interactions
- The “setup.sh” script acts as the entry point. When executed, it invokes the OS-specific install scripts (via conditional logic or user selection).
- Next, the user navigates into a particular package (common, linux, mac) and runs GNU Stow with the “-t” target parameter. This creates symlinks from the repository’s config files to the designated locations (e.g., home directories, application config folders).

##### Important Architectural Patterns and Design Principles
- Modularity: Separation of configuration files by OS and by common/shared files facilitates reuse and easier maintenance.
- Declarative Configuration Management: Rather than rewriting configuration files on every install, WIMILI uses symlink management (via GNU Stow) to automate and simplify the process.
- Script-Driven Automation: The repository contains scripts for installation across different platforms, providing a uniform mechanism to set up and integrate multiple tools (brew, oh-my-zsh, etc.).

##### Incorporate Relevant Technologies/Frameworks/Libraries
- GNU Stow is at the heart of the configuration deployment.
- Shell scripting plays a central role (with scripts written in Bash).

##### Essential Elements
- Clear labels for components: “Install Scripts,” “Common Configs,” “Mac Configs,” “Linux Configs,” “GNU Stow,” and “Target System.”
- Functional components (scripts, package directories);
- Process or workflow actions (installation, symlink deployment);
- External dependencies (tools installed on the user’s OS like Homebrew, oh-my-zsh).

- Since the project supports multiple platforms, clearly differentiate the “Linux” and “Mac” configuration paths versus the shared “Common” configuration path.

1. At the top is the “Setup” layer (install scripts and initialization).
2. The middle layer outlines the configuration packages (common and OS-specific) and shows GNU Stow’s pivotal role.
3. At the bottom layer, illustrate the final state on the user’s system where configuration files are symlinked into their respective locations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Setup Layer
    subgraph "Setup Layer"
        A["Setup Script (setup.sh)"]:::installer
        B["OS Script (arch.sh)"]:::installer
        C["OS Script (mac.sh)"]:::installer
    end

    %% Configuration Packages Layer
    subgraph "Configuration Packages"
        D["Common Configs (packages/common)"]:::package
        E["Linux Configs (packages/linux)"]:::package
        F["Mac Configs (packages/mac)"]:::package
    end

    %% Deployment Layer
    subgraph "Deployment"
        G["GNU Stow"]:::deployment
    end

    %% Target System Layer
    subgraph "Target System"
        H["Symlink Destinations"]:::target
    end

    %% Supporting Documentation
    subgraph "Supporting Documentation"
        I[".stowrc"]:::docs
        J["README.md"]:::docs
        K["arch_install.md"]:::docs
        L[".gitignore"]:::docs
    end

    %% Connections between Setup and OS-specific scripts
    A -->|"selectOS"| B
    A -->|"selectOS"| C

    %% Connect Setup to common configs
    A -->|"deployCommon"| D

    %% Connect OS-specific scripts to their packages
    B -->|"deployLinux"| E
    C -->|"deployMac"| F

    %% Connect packages to GNU Stow for symlink creation
    D -->|"symlink"| G
    E -->|"symlink"| G
    F -->|"symlink"| G

    %% GNU Stow creates symlinks in the target system
    G -->|"createsSymlinks"| H

    %% Styles
    classDef installer fill:#9ec9ff,stroke:#000,stroke-width:2px;
    classDef package fill:#a0f2a0,stroke:#000,stroke-width:2px;
    classDef deployment fill:#ffb3b3,stroke:#000,stroke-width:2px;
    classDef target fill:#fff2b3,stroke:#000,stroke-width:2px;
    classDef docs fill:#f2a0f2,stroke:#000,stroke-width:2px;

    %% Click Events
    click A "https://github.com/carlosmed/dotfiles/blob/main/setup.sh"
    click B "https://github.com/carlosmed/dotfiles/blob/main/installs/arch.sh"
    click C "https://github.com/carlosmed/dotfiles/blob/main/installs/mac.sh"
    click D "https://github.com/carlosmed/dotfiles/tree/main/packages/common"
    click E "https://github.com/carlosmed/dotfiles/tree/main/packages/linux"
    click F "https://github.com/carlosmed/dotfiles/tree/main/packages/mac"
    click I "https://github.com/carlosmed/dotfiles/blob/main/.stowrc"
    click J "https://github.com/carlosmed/dotfiles/blob/main/README.md"
    click K "https://github.com/carlosmed/dotfiles/blob/main/arch_install.md"
    click L "https://github.com/carlosmed/dotfiles/blob/main/.gitignore"
```
