# lgdevlop/zsh-smart-insert architecture

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

- Interactive diagram: https://gitdiagram.com/lgdevlop/zsh-smart-insert
- Repository: https://github.com/lgdevlop/zsh-smart-insert

## Overview

##### Project type and purpose
- zsh-smart-insert is a Zsh plugin (shell-level utility) that installs interactive widgets into the user’s Zsh environment.
- Purpose: let users fuzzy-search files or content (via fd, ripgrep, fzf) and insert selected paths (with optional command prefixes) directly into their command line.

##### File structure
- Top-level plugin entry point: `zsh-smart-insert.plugin.zsh`
- `functions/` directory: reusable shell functions (build exclude lists, prefix chooser, etc.)
- `internal/` directory: ZLE widgets definitions that wire into Zsh’s keybindings and call fzf/fd/rg
- `scripts/`: auxiliary scripts (release-notes generator)
- `install.sh`: installer that sets up the plugin in the user’s `.zshrc`
- `project-docs/`: user documentation samples and shortcuts
- CI/CD: `.github/workflows/*`
- Config files: `commitlint.config.js`, `package.json`, changelogs, and build scripts

a. Main components
- Zsh Environment (the host shell)
- Plugin Core (`zsh-smart-insert.plugin.zsh`)
- Reusable Functions (`functions/`)
- ZLE Widgets (`internal/`)
- External Tools (fd, rg, fzf, bat)
- User keystroke interface
- Installer (`install.sh`)
- Documentation & CI (ancillary; can be in a separate “project management” area)

b. Relationships & data flow
- User presses a hotkey (Alt+f/Alt+g/Alt+s) → ZLE Widget handler in `internal/`
- Widget calls Functions from `functions/` to build exclude lists, choose prefix, or prepare arguments
- Widget invokes external tool (fd/rg) piped into fzf (with bat preview)
- fzf returns selected file path → Widget receives it, optionally prepends chosen prefix
- Plugin writes the final string back into the Zsh command line buffer
- Installer orchestrates sourcing of plugin and keybinding setup
- CI pipeline runs linting, tests, and publishes releases

c. Architectural patterns & design principles
- Modular shell scripting: separate concerns into `functions/` vs `internal/` vs entry point
- Dependency-injection style: environment variables configure ignored dirs, prefixes
- ZLE widget pattern: extend Zsh with custom interactive commands
- Pipeline composition: chaining external binaries for search and preview

d. Key technologies & libraries
- Zsh + ZLE (Zsh Line Editor)
- fzf (fuzzy finder)
- fd (file search)
- ripgrep/rg (content search)
- bat (syntax-highlighted preview)

##### Detailed breakdown (ensure no component is omitted)
- Installer flow: `install.sh` → modifies `.zshrc` → source plugin
- Plugin entry: registers widgets via `zle -N` and `bindkey` commands
- Functions: build dynamic arguments (e.g., extract ignored directories from env)
- Internal widgets: shell functions that glue everything together
- External binaries: executed via subshells, piped into fzf, bat preview invoked via fzf’s --preview
- User sees live result and the plugin injects the final command fragment

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Shell Environment
    ZshEnv["Zsh Environment"]:::shell

    %% User Interaction
    User["User Keystroke (Alt+f/g/s)"]:::shell

    %% Plugin Code
    subgraph "Plugin Code"
        PluginCore["Plugin Core\nzsh-smart-insert.plugin.zsh"]:::plugin
        subgraph "Functions Directory"
            func1["build_fd_excludes.zsh"]:::plugin
            func2["build_rg_excludes.zsh"]:::plugin
            func3["build_ignore_dirs.zsh"]:::plugin
            func4["choose_prefix.zsh"]:::plugin
        end
        subgraph "Internal ZLE Widgets"
            widget1["search_files.zsh"]:::plugin
            widget2["search_content.zsh"]:::plugin
            widget3["file_picker.zsh"]:::plugin
        end
    end

    %% External Dependencies
    subgraph "External Tools"
        fd["fd"]:::deps
        rg["rg"]:::deps
        fzf["fzf"]:::deps
        bat["bat"]:::deps
    end

    %% Project Management
    subgraph "Project Management"
        Installer["install.sh"]:::pm
        Docs["project-docs/"]:::pm
        CI[".github/workflows/"]:::pm
        Config["Config & Metadata"]:::pm
        Scripts["scripts/generate-release-notes.js"]:::pm
        Assets[".changeset/ & assets/"]:::pm
    end

    %% Flows
    User -->|"hotkey"| widget1
    User -->|"hotkey"| widget2
    User -->|"hotkey"| widget3

    widget1 -->|"use"| func1
    widget2 -->|"use"| func2
    widget3 -->|"use"| func3

    widget1 -->|"prefix"| func4
    widget2 -->|"prefix"| func4
    widget3 -->|"prefix"| func4

    widget1 -->|"exec"| fd
    widget2 -->|"exec"| rg

    fd -->|"pipe"| fzf
    rg -->|"pipe"| fzf

    fzf -->|"preview"| bat
    fzf -->|"select"| widget1
    fzf -->|"select"| widget2
    fzf -->|"select"| widget3

    widget1 -->|"insert"| ZshEnv
    widget2 -->|"insert"| ZshEnv
    widget3 -->|"insert"| ZshEnv

    Installer -->|"sourcing"| ZshEnv
    Installer -->|"register widgets"| PluginCore

    %% Click Events
    click PluginCore "https://github.com/lgdevlop/zsh-smart-insert/blob/main/zsh-smart-insert.plugin.zsh"
    click func1 "https://github.com/lgdevlop/zsh-smart-insert/blob/main/functions/build_fd_excludes.zsh"
    click func2 "https://github.com/lgdevlop/zsh-smart-insert/blob/main/functions/build_rg_excludes.zsh"
    click func3 "https://github.com/lgdevlop/zsh-smart-insert/blob/main/functions/build_ignore_dirs.zsh"
    click func4 "https://github.com/lgdevlop/zsh-smart-insert/blob/main/functions/choose_prefix.zsh"
    click widget1 "https://github.com/lgdevlop/zsh-smart-insert/blob/main/internal/search_files.zsh"
    click widget2 "https://github.com/lgdevlop/zsh-smart-insert/blob/main/internal/search_content.zsh"
    click widget3 "https://github.com/lgdevlop/zsh-smart-insert/blob/main/internal/file_picker.zsh"
    click Installer "https://github.com/lgdevlop/zsh-smart-insert/blob/main/install.sh"
    click Docs "https://github.com/lgdevlop/zsh-smart-insert/tree/main/project-docs/"
    click CI "https://github.com/lgdevlop/zsh-smart-insert/tree/main/.github/workflows/"
    click Config "https://github.com/lgdevlop/zsh-smart-insert/blob/main/package.json"
    click Scripts "https://github.com/lgdevlop/zsh-smart-insert/blob/main/scripts/generate-release-notes.js"
    click Assets "https://github.com/lgdevlop/zsh-smart-insert/tree/main/.changeset/"

    %% Styles
    classDef shell fill:#f2f2f2,stroke:#333,stroke-width:1px
    classDef plugin fill:#d0e1f9,stroke:#0366d6,stroke-width:1px
    classDef deps fill:#d4f7d4,stroke:#228b22,stroke-width:1px
    classDef pm fill:#fff3bf,stroke:#d6a700,stroke-width:1px
```
