gourangadassamrat/dotfiles

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.