# g4rcez/dotfiles architecture

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

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

## Overview

##### Project type and purpose
- This is a “configuration-as-code” dotfiles management system built with TypeScript and Deno.
- Its purpose is to centralize, version-control, and programmatically generate or symlink all user configurations (shell, editor, window manager, text expander, etc.) via a plugin-based CLI.

##### File structure
Top-level components:
- bin/            → custom shell utilities and session scripts
- config/         → raw application config subfolders (nvim, wezterm, tmux, zsh, etc.)
- zsh/            → shell initialization, aliases, functions, completions
- dotbot/         → core dotfiles management library and CLI commands
- espanso.config.ts + espanso/ → text-expander plugin & dynamic snippet scripts
- karabiner.config.ts            → keyboard remapping plugin entry
- dotfiles.config.ts             → main Deno-based orchestrator
- raycast/, vscode/, snippets/   → integrations for those tools

Patterns & choices:
- Plugin system: dotbot/plugins and espanso plugins.
- CLI tasks (deno task dotfiles sync, link, pkg, migrate).
- Config directories mirror target applications.

##### README for additional insights
- Lists core technologies (Karabiner, Espanso, Zsh, Neovim, Wezterm, Tmux).
- Describes plugin model: espansoPlugin, vscodePlugin, karabinerPlugin.
- Shows end-to-end flow: “deno task dotfiles sync” reads dotfiles.config.ts, loads plugins, writes symlinks, installs packages.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core Framework Components
    CLI["CLI Orchestrator\n(dotfiles.config.ts)"]:::core
    PF["Plugin Framework\n(dotbot/)"]:::core
    Lib["Dotbot Core Library\n(dotbot/lib/)"]:::core
    Cmds["Dotbot CLI Commands\n(dotbot/commands/)"]:::core

    %% Plugin Modules
    EspPlugin["Espanso Plugin\n(dotbot/plugins/espanso/)"]:::plugin
    EspConfig["Espanso Config\n(espanso.config.ts)"]:::plugin
    EspScripts["Espanso Scripts\n(espanso/scripts/)"]:::plugin

    KarPlugin["Karabiner Plugin\n(dotbot/plugins/karabiner/)"]:::plugin
    KarConfig["Karabiner Config\n(karabiner.config.ts)"]:::plugin
    KarRaw["Karabiner Raw Config\n(config/karabiner/)"]:::data

    VSPlugin["VSCode Plugin\n(dotbot/plugins/vscode.plugin.ts)"]:::plugin
    VSData["VSCode Data\n(vscode/)"]:::data

    RaySnip["Raycast Snippets\n(raycast/snippets/)"]:::plugin
    RayWhich["Raycast WhichKey\n(raycast/whichkey/)"]:::plugin

    ZshMod["Zsh Module\n(zsh/)"]:::plugin
    NvimMod["Neovim Config\n(config/nvim/)"]:::data
    WezMod["WezTerm Config\n(config/wezterm/)"]:::data
    TmuxMod["Tmux Config\n(config/tmux/)"]:::data

    Bin["Shell Utilities\n(bin/)"]:::data
    SnipLib["Snippets Library\n(snippets/)"]:::data

    %% External Tools & OS
    Deno["Deno Runtime"]:::external
    Brew["Homebrew"]:::external
    Git["Git"]:::external
    OSApps["Target Applications\n(Karabiner Elements, Espanso, Zsh, Neovim, Wezterm, Tmux, Raycast, VSCode)"]:::external
    FS["Host File System\nSymlink Layer"]:::external

    %% User Flow
    User["User"]:::external

    %% Connections
    User -->|"invokes"| CLI
    CLI -->|"loads"| PF
    PF --> Lib
    PF --> Cmds

    PF -->|"registers"| EspPlugin
    PF -->|"registers"| KarPlugin
    PF -->|"registers"| VSPlugin
    PF -->|"registers"| RaySnip
    PF -->|"registers"| RayWhich
    PF -->|"registers"| ZshMod

    EspPlugin --> EspConfig
    EspPlugin --> EspScripts
    KarPlugin --> KarConfig
    KarPlugin --> KarRaw
    VSPlugin --> VSData

    EspPlugin -->|"reads config"| EspConfig
    KarPlugin -->|"reads config"| KarRaw
    VSPlugin -->|"reads config"| VSData
    ZshMod -->|"reads config"| ZshMod
    EspPlugin -->|"symlinks to"| FS
    KarPlugin -->|"symlinks to"| FS
    VSPlugin -->|"symlinks to"| FS
    ZshMod -->|"symlinks to"| FS
    NvimMod -->|"symlinks to"| FS
    WezMod -->|"symlinks to"| FS
    TmuxMod -->|"symlinks to"| FS
    RaySnip -->|"symlinks to"| FS
    RayWhich -->|"symlinks to"| FS

    CLI -->|"invokes tasks"| Deno
    CLI -->|"invokes installer"| Brew
    CLI -->|"uses version control"| Git
    CLI -->|"runs scripts"| Bin

    FS -->|"configs applied"| OSApps

    %% Click Events
    click CLI "https://github.com/g4rcez/dotfiles/blob/master/dotfiles.config.ts"
    click PF "https://github.com/g4rcez/dotfiles/tree/master/dotbot/"
    click Lib "https://github.com/g4rcez/dotfiles/tree/master/dotbot/lib/"
    click Cmds "https://github.com/g4rcez/dotfiles/tree/master/dotbot/commands/"
    click EspPlugin "https://github.com/g4rcez/dotfiles/tree/master/dotbot/plugins/espanso/"
    click EspConfig "https://github.com/g4rcez/dotfiles/blob/master/espanso.config.ts"
    click EspScripts "https://github.com/g4rcez/dotfiles/tree/master/espanso/scripts/"
    click KarPlugin "https://github.com/g4rcez/dotfiles/tree/master/dotbot/plugins/karabiner/"
    click KarConfig "https://github.com/g4rcez/dotfiles/blob/master/karabiner.config.ts"
    click KarRaw "https://github.com/g4rcez/dotfiles/tree/master/config/karabiner/"
    click VSPlugin "https://github.com/g4rcez/dotfiles/blob/master/dotbot/plugins/vscode.plugin.ts"
    click VSData "https://github.com/g4rcez/dotfiles/tree/master/vscode/"
    click RaySnip "https://github.com/g4rcez/dotfiles/tree/master/raycast/snippets/"
    click RayWhich "https://github.com/g4rcez/dotfiles/tree/master/raycast/whichkey/"
    click ZshMod "https://github.com/g4rcez/dotfiles/tree/master/zsh/"
    click NvimMod "https://github.com/g4rcez/dotfiles/tree/master/config/nvim/"
    click WezMod "https://github.com/g4rcez/dotfiles/tree/master/config/wezterm/"
    click TmuxMod "https://github.com/g4rcez/dotfiles/tree/master/config/tmux/"
    click Bin "https://github.com/g4rcez/dotfiles/tree/master/bin/"
    click SnipLib "https://github.com/g4rcez/dotfiles/tree/master/snippets/"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#0366d6,stroke-width:2px
    classDef plugin fill:#DFFFE0,stroke:#0f7c0e,stroke-width:2px
    classDef data fill:#FFF8DC,stroke:#d69e2e,stroke-width:2px
    classDef external fill:#F0F0F0,stroke:#888888,stroke-width:1px,stroke-dasharray: 3 3
```
