# baslangenberg/dots architecture

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

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

## Overview

##### Project type and purpose
- This is an Ansible-based dotfiles provisioning project. Its goal is to automate the setup of a personalized development environment (Arch-style on WSL2/Ubuntu or a Vagrant VM), installing configs for zsh, tmux, vim/neovim, polybar, ranger, etc.
- It includes testing via Molecule, supporting immutability and idempotence in the provisioning.

##### Analysis of the file structure
- Top-level:
- setup.yml: the main playbook
- Vagrantfile + bootstrap.sh + utils/: for spinning up and provisioning a VM
- roles/dots/: a single role encapsulating dotfiles, handlers, tasks, defaults, files, templates, meta
- molecule/: under roles to test the “dots” role via Docker or Vagrant
- config files: .gitignore, .pre-commit-config.yaml, yamllint.config.yaml
- roles/dots breakdown:
- defaults/main.yml: default variables (e.g. dotfile locations)
- tasks/*.yml: sequences to install packages, copy configuration files, run scripts
- files/: actual dotfiles (.gitconfig, .zshrc, init.lua for Neovim, etc.)
- handlers/main.yml: reload or restart services if needed (e.g. notify on config change)
- molecule/: scenario definitions for testing
- utils/: helper scripts for bootstrapping (ansible.sh, chroot.sh) and mirrorlist generation
- Windows/WSL specifics: caps2ctrl.reg, windows-terminal-settings.json, hosts

## Diagram (Mermaid)

```mermaid
graph TD
    ControlMachine("Control Machine<br/>(Ansible CLI)"):::provision
    Setup["setup.yml"]:::provision
    ControlMachine --> Setup
    click Setup "https://github.com/baslangenberg/dots/blob/master/setup.yml"

    RoleDots("Ansible Role: dots"):::role
    Setup -->|uses| RoleDots
    click RoleDots "https://github.com/baslangenberg/dots/tree/master/roles/dots"

    subgraph "Role: dots internals"
        Defaults["defaults/main.yml"]:::role
        TasksMain["tasks/main.yml"]:::role
        Neovim["tasks/neovim.yml"]:::role
        Handlers["handlers/main.yml"]:::role
        Meta["meta/main.yml"]:::role
        FilesDir["files"]:::role

        Defaults --> RoleDots
        TasksMain --> RoleDots
        Neovim --> TasksMain
        Handlers --> RoleDots
        Meta --> RoleDots
        RoleDots --> FilesDir

        click Defaults "https://github.com/baslangenberg/dots/blob/master/roles/dots/defaults/main.yml"
        click TasksMain "https://github.com/baslangenberg/dots/blob/master/roles/dots/tasks/main.yml"
        click Neovim "https://github.com/baslangenberg/dots/blob/master/roles/dots/tasks/neovim.yml"
        click Handlers "https://github.com/baslangenberg/dots/blob/master/roles/dots/handlers/main.yml"
        click Meta "https://github.com/baslangenberg/dots/blob/master/roles/dots/meta/main.yml"
        click FilesDir "https://github.com/baslangenberg/dots/tree/master/roles/dots/files"

        subgraph "Dotfiles"
            GitConfig[".gitconfig/.gitconfig-work"]:::role
            Zsh[".zshrc/.p10k.zsh"]:::role
            Tmux[".tmux.conf"]:::role
            Vim[".vim"]:::role
            NeovimConf["nvim/init.lua & lua"]:::role
            Polybar["polybar/config & launch.sh"]:::role
            Ranger["ranger_rc.conf"]:::role
            Wallpapers["wal/templates/colors.Xresources"]:::role
            Scripts["scripts/tmux-sessionizer"]:::role

            FilesDir --> GitConfig
            FilesDir --> Zsh
            FilesDir --> Tmux
            FilesDir --> Vim
            FilesDir --> NeovimConf
            FilesDir --> Polybar
            FilesDir --> Ranger
            FilesDir --> Wallpapers
            FilesDir --> Scripts

            click GitConfig "https://github.com/baslangenberg/dots/blob/master/roles/dots/files/.gitconfig"
            click Zsh "https://github.com/baslangenberg/dots/blob/master/roles/dots/files/.zshrc"
            click Tmux "https://github.com/baslangenberg/dots/blob/master/roles/dots/files/.tmux.conf"
            click Vim "https://github.com/baslangenberg/dots/blob/master/roles/dots/files/.vim"
            click NeovimConf "https://github.com/baslangenberg/dots/blob/master/roles/dots/files/nvim/init.lua"
            click Polybar "https://github.com/baslangenberg/dots/tree/master/roles/dots/files/polybar/config"
            click Ranger "https://github.com/baslangenberg/dots/blob/master/roles/dots/files/ranger_rc.conf"
            click Wallpapers "https://github.com/baslangenberg/dots/blob/master/roles/dots/files/wal/templates/colors.Xresources"
            click Scripts "https://github.com/baslangenberg/dots/tree/master/roles/dots/files/scripts/tmux-sessionizer"
        end
    end

    ControlMachine -->|SSH/WinRM| TargetVM["Target Environment"]:::target
    RoleDots -->|provision| TargetVM

    Vagrantfile["Vagrantfile"]:::provision
    Bootstrap["bootstrap.sh"]:::provision
    ControlMachine --> Vagrantfile
    click Vagrantfile "https://github.com/baslangenberg/dots/tree/master/Vagrantfile"
    ControlMachine --> Bootstrap
    click Bootstrap "https://github.com/baslangenberg/dots/blob/master/bootstrap.sh"
    Vagrantfile --> Bootstrap
    Bootstrap --> TargetVM

    subgraph "Testing: Molecule"
        Molecule["Molecule Test Harness"]:::test
        MoleculeYml["molecule.yml"]:::test
        Converge["converge.yml"]:::test
        Verify["verify.yml"]:::test
        Dockerfile["Dockerfile.j2"]:::test

        ControlMachine --> Molecule
        click Molecule "https://github.com/baslangenberg/dots/tree/master/roles/dots/molecule/default"
        Molecule --> MoleculeYml
        click MoleculeYml "https://github.com/baslangenberg/dots/blob/master/roles/dots/molecule/default/molecule.yml"
        MoleculeYml --> Converge
        click Converge "https://github.com/baslangenberg/dots/blob/master/roles/dots/molecule/default/converge.yml"
        MoleculeYml --> Verify
        click Verify "https://github.com/baslangenberg/dots/blob/master/roles/dots/molecule/default/verify.yml"
        MoleculeYml --> Dockerfile
        click Dockerfile "https://github.com/baslangenberg/dots/blob/master/roles/dots/molecule/default/Dockerfile.j2"
        Molecule -->|drives| TargetVM
    end

    subgraph "Utilities"
        Util1["utils/ansible.sh"]:::provision
        Util2["utils/bootstrap.sh"]:::provision
        Util3["utils/chroot.sh"]:::provision
        Util4["utils/mirrorlist"]:::provision

        ControlMachine --> Util1
        ControlMachine --> Util2
        ControlMachine --> Util3
        ControlMachine --> Util4

        click Util1 "https://github.com/baslangenberg/dots/blob/master/utils/ansible.sh"
        click Util2 "https://github.com/baslangenberg/dots/blob/master/utils/bootstrap.sh"
        click Util3 "https://github.com/baslangenberg/dots/blob/master/utils/chroot.sh"
        click Util4 "https://github.com/baslangenberg/dots/tree/master/utils/mirrorlist"
    end

    subgraph "External Services"
        APT["APT Repository"]:::external
        AUR["AUR"]:::external
        GitHub["GitHub"]:::external
        PyPI["PyPI"]:::external

        RoleDots --> APT
        RoleDots --> AUR
        RoleDots --> GitHub
        RoleDots --> PyPI
    end

    ControlMachine --> WSL["WSL2 Ubuntu"]:::target
    RoleDots --> WSL

    classDef provision fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1
    classDef test fill:#C8E6C9,stroke:#2E7D32,color:#2E7D32
    classDef external fill:#FFE0B2,stroke:#EF6C00,color:#E65100
    classDef target fill:#E1BEE7,stroke:#6A1B9A,color:#4A148C
    classDef role fill:#FFF9C4,stroke:#F9A825,color:#F57F17
```
