# vasily-sviridov/dotfiles architecture

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

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

## Overview

This repository is a personal dotfiles system centered on a single install pipeline: `./install` bootstraps the machine, and Dotbot applies the selected setup steps to place config files, run installers, and wire everything together.

The main architectural boundary is between **orchestration** and **payload**. Orchestration lives in the install script, Dotbot, and the step files under `steps/`. The payload is the actual configuration content in `config/`, `shell/`, `nvim/`, and `dependencies/`.

`dotbot/` is vendored in the repo and used as the configuration engine. The README notes that installation is step-based: the user can enable or disable pieces by commenting out `run_dotbot 'steps/...'` entries. That means the setup is intentionally modular rather than a monolithic “install everything” flow.

`steps/terminal.yaml` is the visible Dotbot step definition in the tree. It is likely the top-level wiring for terminal-related symlinks or commands, while the rest of the repo provides the files those steps install or source.

The `config/` directory contains host-level configuration artifacts that are typically linked into standard locations: editor formatting, Git behavior, shell startup, and plugin manager settings. The presence of `editorconfig`, `gitattributes`, `gitconfig`, `zplugrc`, and `zshrc` suggests this repo configures the developer environment across editor, VCS, and shell layers.

The `shell/` directory is a shell-profile composition layer. Files like `.exports`, `.aliases`, `.external`, `.std`, and `.wsl` imply the shell environment is split into reusable fragments rather than one large profile. This allows the Zsh startup config to source common definitions while keeping platform-specific behavior isolated.

The `dependencies/` subtree is a separate bootstrap subsystem for software installation. `dependencies/install` is the entry point, and `dependencies/lib/*.sh` breaks the logic into shared helpers plus OS/runtime-specific installers for macOS, Ubuntu, Go, Rust, NVM, and `uv`. That makes dependency provisioning a distinct phase from dotfile linking.

The `nvim/` directory is a complete Neovim configuration boundary. It has its own `init.lua`, plugin lock files, and Lua modules under `lua/config` and `lua/plugins`. This is not just a single plugin file; it is a structured editor stack with options, keymaps, autocommands, and plugin registration separated into layers.

Neovim plugin management appears to be based on LazyVim/Lazy.nvim conventions. `nvim/lazy-lock.json` and `nvim/lazyvim.json` indicate pinned plugin state and a preset/configuration baseline. The plugin modules (`blink.lua`, `gitsigns.lua`, `snacks.lua`, `theme.lua`, `cyrillic.lua`) define the editor’s functional pieces and UI behavior.

The repo also contains automation for keeping editor dependencies current. `.github/workflows/update-lazy-plugins.yml` likely updates the Neovim plugin lockfile, and Dependabot is configured to monitor dependencies. That means the repo has an explicit maintenance path for both system packages and editor plugins.

Overall, the architecture is: **Dotbot-driven bootstrap** at the center, **OS/runtime installers** for dependencies, **shell and Git/editor configs** as installable artifacts, and **Neovim as a self-contained subplatform** with its own dependency tracking and update automation.

Main entry points: [`dependencies/install`](https://github.com/vasily-sviridov/dotfiles/tree/develop/dependencies/install) (Deps install), [`steps/terminal.yaml`](https://github.com/vasily-sviridov/dotfiles/blob/develop/steps/terminal.yaml) (Terminal step), [`nvim`](https://github.com/vasily-sviridov/dotfiles/tree/develop/nvim) (Neovim), [`install`](https://github.com/vasily-sviridov/dotfiles/tree/develop/install) (install)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Orchestration"]
  node_install["install<br/>bootstrap script"]
  node_dotbot["Dotbot<br/>installer engine"]
  node_terminal_step["Terminal step<br/>dotbot step<br/>[terminal.yaml]"]
  node_dependencies_install["Deps install<br/>bootstrap entrypoint"]
end

subgraph group_payload["Payload"]
  node_config_bundle["Host config<br/>dotfile bundle"]
  node_shell_bundle["Shell env<br/>profile fragments"]
  node_nvim_root["Neovim<br/>editor stack"]
  node_nvim_init["init.lua<br/>editor entrypoint<br/>[init.lua]"]
  node_nvim_config["Config layer<br/>editor core"]
  node_nvim_plugins["Plugins<br/>plugin modules"]
  node_dep_common["Common lib<br/>installer helpers<br/>[common.sh]"]
  node_dep_macos["macOS<br/>os installer<br/>[macos.sh]"]
  node_dep_ubuntu["Ubuntu<br/>os installer<br/>[ubuntu.sh]"]
  node_dep_go["Go<br/>runtime installer<br/>[go.sh]"]
  node_dep_rust["Rust<br/>runtime installer<br/>[rust.sh]"]
  node_dep_nvm["NVM<br/>runtime installer<br/>[nvm.sh]"]
  node_dep_uv["uv<br/>runtime installer<br/>[uv.sh]"]
end

subgraph group_automation["Automation"]
  node_lazy_update["Plugin update<br/>CI workflow"]
  node_dependabot["Dependabot<br/>dependency automation<br/>[dependabot.yml]"]
end

node_install -->|"boots"| node_dotbot
node_install -->|"enables"| node_terminal_step
node_dotbot -->|"applies"| node_terminal_step
node_terminal_step -->|"links"| node_config_bundle
node_terminal_step -->|"sources"| node_shell_bundle
node_terminal_step -->|"installs"| node_nvim_root
node_install -->|"can run"| node_dependencies_install
node_dependencies_install -->|"uses"| node_dep_common
node_dependencies_install -->|"dispatches"| node_dep_macos
node_dependencies_install -->|"dispatches"| node_dep_ubuntu
node_dependencies_install -->|"installs"| node_dep_go
node_dependencies_install -->|"installs"| node_dep_rust
node_dependencies_install -->|"installs"| node_dep_nvm
node_dependencies_install -->|"installs"| node_dep_uv
node_nvim_root -->|"starts with"| node_nvim_init
node_nvim_init -->|"loads"| node_nvim_config
node_nvim_init -->|"loads"| node_nvim_plugins
node_nvim_config -->|"coordinates"| node_nvim_plugins
node_lazy_update -->|"updates"| node_nvim_root
node_dependabot -->|"monitors"| node_dependencies_install
node_dependabot -->|"monitors"| node_nvim_root

click node_install "https://github.com/vasily-sviridov/dotfiles/tree/develop/install"
click node_dotbot "https://github.com/vasily-sviridov/dotfiles/tree/develop/dotbot"
click node_terminal_step "https://github.com/vasily-sviridov/dotfiles/blob/develop/steps/terminal.yaml"
click node_dependencies_install "https://github.com/vasily-sviridov/dotfiles/tree/develop/dependencies/install"
click node_config_bundle "https://github.com/vasily-sviridov/dotfiles/tree/develop/config"
click node_shell_bundle "https://github.com/vasily-sviridov/dotfiles/tree/develop/shell"
click node_nvim_root "https://github.com/vasily-sviridov/dotfiles/tree/develop/nvim"
click node_nvim_init "https://github.com/vasily-sviridov/dotfiles/blob/develop/nvim/init.lua"
click node_nvim_config "https://github.com/vasily-sviridov/dotfiles/tree/develop/nvim/lua/config"
click node_nvim_plugins "https://github.com/vasily-sviridov/dotfiles/tree/develop/nvim/lua/plugins"
click node_dep_common "https://github.com/vasily-sviridov/dotfiles/blob/develop/dependencies/lib/common.sh"
click node_dep_macos "https://github.com/vasily-sviridov/dotfiles/blob/develop/dependencies/lib/macos.sh"
click node_dep_ubuntu "https://github.com/vasily-sviridov/dotfiles/blob/develop/dependencies/lib/ubuntu.sh"
click node_dep_go "https://github.com/vasily-sviridov/dotfiles/blob/develop/dependencies/lib/go.sh"
click node_dep_rust "https://github.com/vasily-sviridov/dotfiles/blob/develop/dependencies/lib/rust.sh"
click node_dep_nvm "https://github.com/vasily-sviridov/dotfiles/blob/develop/dependencies/lib/nvm.sh"
click node_dep_uv "https://github.com/vasily-sviridov/dotfiles/blob/develop/dependencies/lib/uv.sh"
click node_lazy_update "https://github.com/vasily-sviridov/dotfiles/blob/develop/.github/workflows/update-lazy-plugins.yml"
click node_dependabot "https://github.com/vasily-sviridov/dotfiles/blob/develop/.github/dependabot.yml"

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_install,node_dotbot,node_terminal_step,node_dependencies_install toneBlue
class node_config_bundle,node_shell_bundle,node_nvim_root,node_nvim_init,node_nvim_config,node_nvim_plugins,node_dep_common,node_dep_macos,node_dep_ubuntu,node_dep_go,node_dep_rust,node_dep_nvm,node_dep_uv toneAmber
class node_lazy_update,node_dependabot toneMint
```

## Components

### Orchestration

Bootstrap entrypoints and step-based install flow.

- [install](https://github.com/vasily-sviridov/dotfiles/tree/develop/install): bootstrap script · Top-level machine bootstrap entrypoint. · `install`
- [Dotbot](https://github.com/vasily-sviridov/dotfiles/tree/develop/dotbot): installer engine · Vendored configuration engine that executes install steps. · `dotbot`
- [Terminal step](https://github.com/vasily-sviridov/dotfiles/blob/develop/steps/terminal.yaml): dotbot step · Visible Dotbot step that wires terminal-related setup. · `steps/terminal.yaml`
- [Deps install](https://github.com/vasily-sviridov/dotfiles/tree/develop/dependencies/install): bootstrap entrypoint · Entry script for dependency provisioning. · `dependencies/install`

### Payload

Installable configuration and runtime content.

- [Host config](https://github.com/vasily-sviridov/dotfiles/tree/develop/config): dotfile bundle · Host-level config artifacts for editor, VCS, and shell integration. · `config`
- [Shell env](https://github.com/vasily-sviridov/dotfiles/tree/develop/shell): profile fragments · Composable shell startup fragments and platform-specific behavior. · `shell`
- [Neovim](https://github.com/vasily-sviridov/dotfiles/tree/develop/nvim): editor stack · Self-contained Neovim configuration boundary. · `nvim`
- [init.lua](https://github.com/vasily-sviridov/dotfiles/blob/develop/nvim/init.lua): editor entrypoint · Neovim startup entry that loads the editor stack. · `nvim/init.lua`
- [Config layer](https://github.com/vasily-sviridov/dotfiles/tree/develop/nvim/lua/config): editor core · Core options, mappings, autocommands, and lazy loader setup. · `nvim/lua/config`
- [Plugins](https://github.com/vasily-sviridov/dotfiles/tree/develop/nvim/lua/plugins): plugin modules · Plugin registrations and editor behavior modules. · `nvim/lua/plugins`
- [Common lib](https://github.com/vasily-sviridov/dotfiles/blob/develop/dependencies/lib/common.sh): installer helpers · Shared shell helpers for dependency installation. · `dependencies/lib/common.sh`
- [macOS](https://github.com/vasily-sviridov/dotfiles/blob/develop/dependencies/lib/macos.sh): os installer · macOS-specific dependency installation logic. · `dependencies/lib/macos.sh`
- [Ubuntu](https://github.com/vasily-sviridov/dotfiles/blob/develop/dependencies/lib/ubuntu.sh): os installer · Ubuntu-specific dependency installation logic. · `dependencies/lib/ubuntu.sh`
- [Go](https://github.com/vasily-sviridov/dotfiles/blob/develop/dependencies/lib/go.sh): runtime installer · Go toolchain provisioning logic. · `dependencies/lib/go.sh`
- [Rust](https://github.com/vasily-sviridov/dotfiles/blob/develop/dependencies/lib/rust.sh): runtime installer · Rust toolchain provisioning logic. · `dependencies/lib/rust.sh`
- [NVM](https://github.com/vasily-sviridov/dotfiles/blob/develop/dependencies/lib/nvm.sh): runtime installer · Node version manager provisioning logic. · `dependencies/lib/nvm.sh`
- [uv](https://github.com/vasily-sviridov/dotfiles/blob/develop/dependencies/lib/uv.sh): runtime installer · Python package/runtime tool provisioning logic. · `dependencies/lib/uv.sh`

### Automation

Update and dependency maintenance tooling.

- [Plugin update](https://github.com/vasily-sviridov/dotfiles/blob/develop/.github/workflows/update-lazy-plugins.yml): CI workflow · Automated refresh of Neovim plugin lock state. · `.github/workflows/update-lazy-plugins.yml`
- [Dependabot](https://github.com/vasily-sviridov/dotfiles/blob/develop/.github/dependabot.yml): dependency automation · Automated dependency monitoring and updates. · `.github/dependabot.yml`

## Connections

- install → Dotbot: boots · Bootstrap hands off to the Dotbot engine.
- install → Terminal step: enables · Install script selects which step files to run.
- Dotbot → Terminal step: applies · Dotbot executes the terminal setup step.
- Terminal step → Host config: links · Step consumes host config artifacts for installation.
- Terminal step → Shell env: sources · Step wires shell fragments into the login shell.
- Terminal step → Neovim: installs · Step wires the editor configuration boundary.
- install → Deps install: can run · Dependency provisioning is a separate bootstrap phase.
- Deps install → Common lib: uses · Installer entrypoint relies on shared helpers.
- Deps install → macOS: dispatches · Selects macOS-specific installation path when needed.
- Deps install → Ubuntu: dispatches · Selects Ubuntu-specific installation path when needed.
- Deps install → Go: installs · Provisioning can install the Go toolchain.
- Deps install → Rust: installs · Provisioning can install the Rust toolchain.
- Deps install → NVM: installs · Provisioning can install Node version management.
- Deps install → uv: installs · Provisioning can install the uv toolchain.
- Neovim → init.lua: starts with · Neovim loads its init entrypoint first.
- init.lua → Config layer: loads · Startup delegates core setup to config modules.
- init.lua → Plugins: loads · Startup delegates plugin definitions to plugin modules.
- Config layer → Plugins: coordinates · Core config and plugins work together through lazy loading.
- Plugin update → Neovim: updates · Workflow refreshes pinned Neovim plugin state.
- Dependabot → Deps install: monitors · Automation watches repository dependency surfaces.
- Dependabot → Neovim: monitors · Automation also watches the editor stack and lock files.