# gourangadassamrat/dotfiles architecture

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

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

## Overview

1. This repository is a personal dotfiles and workstation-bootstrap project, not an application runtime. Its job is to provision a terminal-centric developer environment across Linux and macOS, then manage the resulting configs as symlinked packages.

2. The top-level architecture splits into three layers: installer scripts under `scripts/`, managed configuration bundles by tool name (`zsh/`, `tmux/`, `vscode/`, `helix/`, `kitty/`, etc.), and documentation under `docs/`. The `archive/` tree holds older or preserved configs that are not part of the active provisioning path.

3. Provisioning is the main data flow. `scripts/install.sh` and `scripts/setup.sh` orchestrate setup, while `scripts/utils/detect.sh` determines OS/package-manager/sudo capability. The installer then fans out into modular steps: base software installation, shell/plugin setup, wallpaper cloning, and dotfile symlinking.

4. Dotfile deployment is centered on GNU Stow. Each managed tool has its own directory containing a `.config` or equivalent root, which becomes the source of symlinks into the user’s home directory. This is the key boundary between “repository state” and “live machine state.”

5. The shell stack is the core subsystem. `zsh/` contains the main `.zshrc`, environment setup, history behavior, color/theme settings, functions, plugins, aliases, and overrides. The README makes clear that this layer is interactive and productivity-oriented, with many shell commands implemented as custom functions and wrappers.

6. Shell behavior depends on a small set of reusable plugins and tools: `fzf`, `pass`, `oh-my-zsh`, autosuggestions, syntax highlighting, and fzf-tab. `starship.toml` defines the prompt, while `bash/` provides a simpler Bash fallback via `.bashrc` for non-zsh sessions.

7. The terminal UI layer includes `tmux/`, `kitty/`, `alacritty/`, `rofi/`, and `ytm-player/`. `tmux` is configured for persistent sessions with resurrect/continuum support, while Kitty and Alacritty provide terminal emulators. Rofi fills the launcher role, and `ytm-player` is a small media-client config rather than part of the shell itself.

8. Editor and IDE configuration is split between `helix/` and `vscode/`. Helix uses `config.toml` plus `languages.toml` to define editor behavior and language-server integration. VS Code is organized as a full user profile with settings, keybindings, and language-specific snippets, showing that the repo manages both CLI editors and a GUI IDE with distinct configuration boundaries.

9. Git and GitHub workflows are treated as first-class tooling. The `git/` directory contains `.gitconfig` plus hook scripts for commit-message validation and pre-push checks. The `gh/` directory configures GitHub CLI, and the README documents a large set of aliases for commit history, PR lookup, and repository navigation. This makes version control part of the daily shell workflow rather than an external tool.

10. Optional language-tooling installers live under `scripts/sdk-tools/`. These scripts extend the base environment with Go, Rust, and Python CLI tools, but remain separate from the core bootstrap so they can be run independently. That separation is mirrored in the README: core workstation setup is one path, language-specific augmentation is another.

11. Documentation is a meaningful architectural boundary. `docs/` explains shell architecture, setup, editor settings, termux-specific behavior, and git usage, which suggests the repo is designed to be understandable and partially self-describing rather than purely scripted. The GitHub Actions workflows appear to validate shell behavior and releases, so CI is mainly about correctness of config/scripts, not building artifacts.

12. Overall, the repo’s architecture is “declarative configs plus procedural bootstrap.” Config directories define the desired state for each tool; scripts detect the host environment and apply that state; docs explain the intended usage; archived configs preserve prior snapshots. The result is a portable terminal workspace assembled from loosely coupled, tool-specific modules.

Main entry points: [`zsh/.config/zsh/.zshrc`](https://github.com/gourangadassamrat/dotfiles/blob/main/zsh/.config/zsh/.zshrc) (Zsh), [`scripts/setup.sh`](https://github.com/gourangadassamrat/dotfiles/blob/main/scripts/setup.sh) (Setup), [`git/.gitconfig`](https://github.com/gourangadassamrat/dotfiles/blob/main/git/.gitconfig) (Git), [`.github/workflows`](https://github.com/gourangadassamrat/dotfiles/blob/main/.github/workflows) (Workflows)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_provisioning["Provisioning"]
  node_n_install["Install<br/>bootstrap script<br/>[install.sh]"]
  node_n_setup["Setup<br/>bootstrap script<br/>[setup.sh]"]
  node_n_detect["Detect<br/>[detect.sh]"]
  node_n_dotfiles["Dotfiles<br/>stow helpers<br/>[dotfiles.sh]"]
  node_n_softwares["Softwares<br/>install helpers<br/>[softwares.sh]"]
  node_n_plugins["Plugins<br/>shell setup<br/>[plugins.sh]"]
  node_n_wallpapers["Wallpapers<br/>asset setup<br/>[wallpapers.sh]"]
  node_n_sdktools["SDK tools<br/>optional installers"]
end

subgraph group_g_shell["Shell"]
  node_n_zsh["Zsh<br/>interactive shell<br/>[.zshrc]"]
  node_n_starship["Starship<br/>prompt config<br/>[starship.toml]"]
  node_n_bash["Bash<br/>fallback shell<br/>[.bashrc]"]
end

subgraph group_g_terminal["Terminal UI"]
  node_n_tmux["Tmux<br/>session manager<br/>[.tmux.conf]"]
  node_n_kitty["Kitty<br/>terminal emulator<br/>[kitty.conf]"]
  node_n_alacritty["Alacritty<br/>terminal emulator<br/>[alacritty.toml]"]
  node_n_rofi["Rofi<br/>launcher<br/>[config.rasi]"]
  node_n_ytm["YTM Player<br/>media client<br/>[config.toml]"]
end

subgraph group_g_editor["Editor"]
  node_n_helix["Helix<br/>editor config<br/>[config.toml]"]
  node_n_vscode["VS Code<br/>ide profile<br/>[settings.json]"]
end

subgraph group_g_vcs["Version Control"]
  node_n_git["Git<br/>vcs config<br/>[.gitconfig]"]
  node_n_gh["GitHub CLI<br/>cli config<br/>[config.yml]"]
end

subgraph group_g_docs["Docs"]
  node_n_docs["Docs<br/>documentation"]
end

subgraph group_g_archive["Archive"]
  node_n_archive["Archive<br/>legacy configs"]
end

subgraph group_g_ci["CI"]
  node_n_ci["Workflows<br/>ci automation<br/>[workflows]"]
end

node_n_install -->|"calls"| node_n_setup
node_n_setup -->|"uses"| node_n_detect
node_n_setup -->|"installs"| node_n_softwares
node_n_setup -->|"configures"| node_n_plugins
node_n_setup -->|"fetches"| node_n_wallpapers
node_n_setup -->|"stows"| node_n_dotfiles
node_n_sdktools -->|"extends"| node_n_softwares
node_n_zsh -->|"prompts"| node_n_starship
node_n_zsh -->|"loads"| node_n_plugins
node_n_zsh -.->|"fallbacks to"| node_n_bash
node_n_tmux -->|"supports"| node_n_zsh
node_n_kitty -->|"hosts"| node_n_zsh
node_n_alacritty -.->|"hosts"| node_n_zsh
node_n_rofi -->|"launches from"| node_n_zsh
node_n_ytm -->|"integrates with"| node_n_zsh
node_n_helix -->|"documented by"| node_n_docs
node_n_vscode -->|"documented by"| node_n_docs
node_n_git -->|"pairs with"| node_n_gh
node_n_git -->|"used from"| node_n_zsh
node_n_ci -->|"validates"| node_n_install
node_n_ci -->|"validates"| node_n_zsh
node_n_archive -.->|"preserves"| node_n_dotfiles

click node_n_install "https://github.com/gourangadassamrat/dotfiles/blob/main/scripts/install.sh"
click node_n_setup "https://github.com/gourangadassamrat/dotfiles/blob/main/scripts/setup.sh"
click node_n_detect "https://github.com/gourangadassamrat/dotfiles/blob/main/scripts/utils/detect.sh"
click node_n_dotfiles "https://github.com/gourangadassamrat/dotfiles/blob/main/scripts/lib/dotfiles.sh"
click node_n_softwares "https://github.com/gourangadassamrat/dotfiles/blob/main/scripts/lib/softwares.sh"
click node_n_plugins "https://github.com/gourangadassamrat/dotfiles/blob/main/scripts/lib/plugins.sh"
click node_n_wallpapers "https://github.com/gourangadassamrat/dotfiles/blob/main/scripts/lib/wallpapers.sh"
click node_n_sdktools "https://github.com/gourangadassamrat/dotfiles/tree/main/scripts/sdk-tools"
click node_n_zsh "https://github.com/gourangadassamrat/dotfiles/blob/main/zsh/.config/zsh/.zshrc"
click node_n_starship "https://github.com/gourangadassamrat/dotfiles/blob/main/zsh/.config/starship.toml"
click node_n_bash "https://github.com/gourangadassamrat/dotfiles/blob/main/bash/.bashrc"
click node_n_tmux "https://github.com/gourangadassamrat/dotfiles/blob/main/archive/tmux/.tmux.conf"
click node_n_kitty "https://github.com/gourangadassamrat/dotfiles/blob/main/kitty/.config/kitty/kitty.conf"
click node_n_alacritty "https://github.com/gourangadassamrat/dotfiles/blob/main/archive/alacritty/.config/alacritty/alacritty.toml"
click node_n_rofi "https://github.com/gourangadassamrat/dotfiles/blob/main/rofi/.config/rofi/config.rasi"
click node_n_ytm "https://github.com/gourangadassamrat/dotfiles/blob/main/ytm-player/.config/ytm-player/config.toml"
click node_n_helix "https://github.com/gourangadassamrat/dotfiles/blob/main/helix/.config/helix/config.toml"
click node_n_vscode "https://github.com/gourangadassamrat/dotfiles/blob/main/vscode/.config/Visual Studio Code/User/settings.json"
click node_n_git "https://github.com/gourangadassamrat/dotfiles/blob/main/git/.gitconfig"
click node_n_gh "https://github.com/gourangadassamrat/dotfiles/blob/main/gh/.config/gh/config.yml"
click node_n_docs "https://github.com/gourangadassamrat/dotfiles/tree/main/docs"
click node_n_archive "https://github.com/gourangadassamrat/dotfiles/tree/main/archive"
click node_n_ci "https://github.com/gourangadassamrat/dotfiles/blob/main/.github/workflows"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_install,node_n_setup,node_n_detect,node_n_dotfiles,node_n_softwares,node_n_plugins,node_n_wallpapers,node_n_sdktools,node_n_archive toneBlue
class node_n_zsh,node_n_starship,node_n_bash,node_n_ci toneAmber
class node_n_tmux,node_n_kitty,node_n_alacritty,node_n_rofi,node_n_ytm toneMint
class node_n_helix,node_n_vscode toneRose
class node_n_git,node_n_gh toneIndigo
class node_n_docs toneTeal
```

## Components

### Provisioning

Bootstrap scripts and host detection that apply the dotfiles to a machine.

- [Install](https://github.com/gourangadassamrat/dotfiles/blob/main/scripts/install.sh): bootstrap script · Entry point for workstation provisioning. · `scripts/install.sh`
- [Setup](https://github.com/gourangadassamrat/dotfiles/blob/main/scripts/setup.sh): bootstrap script · Coordinates install phases and environment setup. · `scripts/setup.sh`
- [Detect](https://github.com/gourangadassamrat/dotfiles/blob/main/scripts/utils/detect.sh): host detection · Detects OS, package manager, and privilege capabilities. · `scripts/utils/detect.sh`
- [Dotfiles](https://github.com/gourangadassamrat/dotfiles/blob/main/scripts/lib/dotfiles.sh): stow helpers · Applies managed config bundles as symlinked packages. · `scripts/lib/dotfiles.sh`
- [Softwares](https://github.com/gourangadassamrat/dotfiles/blob/main/scripts/lib/softwares.sh): install helpers · Installs base software needed for the workstation. · `scripts/lib/softwares.sh`
- [Plugins](https://github.com/gourangadassamrat/dotfiles/blob/main/scripts/lib/plugins.sh): shell setup · Installs or wires shell plugins and extensions. · `scripts/lib/plugins.sh`
- [Wallpapers](https://github.com/gourangadassamrat/dotfiles/blob/main/scripts/lib/wallpapers.sh): asset setup · Fetches wallpaper assets used by the desktop setup. · `scripts/lib/wallpapers.sh`
- [SDK tools](https://github.com/gourangadassamrat/dotfiles/tree/main/scripts/sdk-tools): optional installers · Language-specific CLI tool installers for Go, Rust, and Python. · `scripts/sdk-tools`

### Shell

Interactive shell setup and prompt behavior.

- [Zsh](https://github.com/gourangadassamrat/dotfiles/blob/main/zsh/.config/zsh/.zshrc): interactive shell · Main shell stack with env, history, functions, plugins, and overrides. · `zsh/.config/zsh/.zshrc`
- [Starship](https://github.com/gourangadassamrat/dotfiles/blob/main/zsh/.config/starship.toml): prompt config · Cross-shell prompt configuration. · `zsh/.config/starship.toml`
- [Bash](https://github.com/gourangadassamrat/dotfiles/blob/main/bash/.bashrc): fallback shell · Minimal Bash session configuration for non-Zsh shells. · `bash/.bashrc`

### Terminal UI

Terminal, launcher, and media-client configs.

- [Tmux](https://github.com/gourangadassamrat/dotfiles/blob/main/archive/tmux/.tmux.conf): session manager · Persistent terminal multiplexing with resurrect/continuum support. · `archive/tmux/.tmux.conf`
- [Kitty](https://github.com/gourangadassamrat/dotfiles/blob/main/kitty/.config/kitty/kitty.conf): terminal emulator · Kitty terminal configuration and theme selection. · `kitty/.config/kitty/kitty.conf`
- [Alacritty](https://github.com/gourangadassamrat/dotfiles/blob/main/archive/alacritty/.config/alacritty/alacritty.toml): terminal emulator · Archived terminal emulator configuration. · `archive/alacritty/.config/alacritty/alacritty.toml`
- [Rofi](https://github.com/gourangadassamrat/dotfiles/blob/main/rofi/.config/rofi/config.rasi): launcher · Application launcher and prompt menu configuration. · `rofi/.config/rofi/config.rasi`
- [YTM Player](https://github.com/gourangadassamrat/dotfiles/blob/main/ytm-player/.config/ytm-player/config.toml): media client · Terminal media-player configuration. · `ytm-player/.config/ytm-player/config.toml`

### Editor

CLI editor and GUI IDE configuration.

- [Helix](https://github.com/gourangadassamrat/dotfiles/blob/main/helix/.config/helix/config.toml): editor config · Helix editor behavior and language-server setup. · `helix/.config/helix/config.toml`
- [VS Code](https://github.com/gourangadassamrat/dotfiles/blob/HEAD/vscode/.config/Visual%20Studio%20Code/User/settings.json): ide profile · Full VS Code user profile with settings, keybindings, and snippets. · `vscode/.config/Visual Studio Code/User/settings.json`

### Version Control

Git and GitHub workflow tooling.

- [Git](https://github.com/gourangadassamrat/dotfiles/blob/main/git/.gitconfig): vcs config · Git configuration plus hook scripts for commit and push checks. · `git/.gitconfig`
- [GitHub CLI](https://github.com/gourangadassamrat/dotfiles/blob/main/gh/.config/gh/config.yml): cli config · GitHub CLI configuration. · `gh/.config/gh/config.yml`

### Docs

Usage and architecture documentation.

- [Docs](https://github.com/gourangadassamrat/dotfiles/tree/main/docs): documentation · Architecture and usage documentation for setup, shell, editor, and git workflows. · `docs`

### Archive

Preserved legacy configs outside the active path.

- [Archive](https://github.com/gourangadassamrat/dotfiles/tree/main/archive): legacy configs · Preserved historical configs not used in the active provisioning path. · `archive`

### CI

Workflow validation and release automation.

- [Workflows](https://github.com/gourangadassamrat/dotfiles/blob/main/.github/workflows): ci automation · Validation and release workflows for scripts and shell behavior. · `.github/workflows`

## Connections

- Install → Setup: calls · Install delegates to the setup orchestrator.
- Setup → Detect: uses · Setup first determines host capabilities and package manager.
- Setup → Softwares: installs · Base software is installed as part of provisioning.
- Setup → Plugins: configures · Shell plugins and related tooling are prepared.
- Setup → Wallpapers: fetches · Desktop assets are cloned or downloaded.
- Setup → Dotfiles: stows · Managed config bundles are linked into the live home directory.
- SDK tools → Softwares: extends · Optional language tooling builds on the core workstation setup.
- Zsh → Starship: prompts · Zsh loads the shared prompt theme.
- Zsh → Plugins: loads · Interactive shell behavior depends on plugin setup.
- Zsh → Bash: fallbacks to · Bash provides a simpler non-Zsh session path.
- Tmux → Zsh: supports · Tmux complements the shell-centric workflow.
- Kitty → Zsh: hosts · Kitty is one of the main terminal environments for the shell.
- Alacritty → Zsh: hosts · Archived terminal configuration for the shell workflow.
- Rofi → Zsh: launches from · Launcher config supports the terminal-first desktop workflow.
- YTM Player → Zsh: integrates with · Media client is part of the broader terminal toolkit.
- Helix → Docs: documented by · Editor architecture and language servers are explained in docs.
- VS Code → Docs: documented by · VS Code settings and keybindings have dedicated docs.
- Git → GitHub CLI: pairs with · Git workflow is complemented by GitHub CLI configuration.
- Git → Zsh: used from · Git aliases and hooks are intended for shell-driven daily use.
- Workflows → Install: validates · Workflows check scripts and shell behavior.
- Workflows → Zsh: validates · Shell validation workflow covers interactive shell config.
- Archive → Dotfiles: preserves · Archived configs are historical snapshots rather than active targets.