# hidehic0/custom-completion-zsh architecture

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

- Interactive diagram: https://gitdiagram.com/hidehic0/custom-completion-zsh
- Repository: https://github.com/hidehic0/custom-completion-zsh

## Overview

##### Project type and purpose
- This is a small, single-binary CLI tool (“custom-completion-zsh”) written in Go.
- Purpose: read a user’s TOML configuration, generate Zsh completion scripts, and write them into the user’s Zsh fpath so that custom completions are available.

##### File structure
- Top-level files:
- main.go – entry point, sets up the CLI with cobra
- defaultconfig.toml – a template for a user’s config
- aqua.yaml, .goreleaser.yaml – delivery/publishing configs
- go.mod/go.sum – Go module/dependency config
- No subdirectories—everything lives in main.go and imported packages.

##### README insights
- Config file lives at `$XDG_CONFIG_HOME/custom-completion-zsh/config.toml`
- Output completes go to `$XDG_DATA_HOME/zsh/custom-completion-zsh` for Zsh to consume.
- Two user-facing commands:
- `completion zsh` – prints the completion script
- `build` – writes completion files to the data directory

##### Main components & interactions
a. Components
1. User shell (Zsh)
2. File system (XDG_CONFIG_HOME, XDG_DATA_HOME)
3. CLI binary (`custom-completion-zsh`)
4. Cobra command layer (`build`, `completion zsh`)
5. TOML parser (reads user config)
6. Completion-script generator (uses cobra’s built-in capabilities)
7. Output writer (writes files to the data directory)
8. Build & release pipeline (Go toolchain, goreleaser, aqua)
b. Relationships / Data Flow
- User invokes `custom-completion-zsh <command>`.
- Cobra parses the command, dispatches to the appropriate handler.
- Handler reads `config.toml` from $XDG_CONFIG_HOME.
- BurntSushi/toml parses config into Go structs.
- Based on config, the generator produces a Zsh completion script.
- If `build`, the script is written into `$XDG_DATA_HOME/zsh/custom-completion-zsh/`.
- User adds that directory to Zsh’s fpath and reloads the shell.
- For developers: Go modules resolve dependencies; goreleaser and aqua.yaml define packaging & distribution.

##### Architectural patterns & design principles
- Command pattern (cobra commands)
- Separation of concerns: CLI parsing, config parsing, script generation, file I/O
- Single responsibility modules (each library handles a specific task)
- Declarative configuration (TOML)
- Standard XDG directory conventions for config & data

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and Environment Layer
    User["User"]:::user
    Zsh["Zsh Shell"]:::user
    Config["Config Dir\n($XDG_CONFIG_HOME)"]:::storage
    Data["Data Dir\n($XDG_DATA_HOME)"]:::storage

    %% Application Layer
    subgraph "Application Modules"
        CLI["CLI Binary\n(custom-completion-zsh)"]:::app
        Cobra["Cobra Command Layer\n(build, completion zsh)"]:::app
        Parser["TOML Parser\n(BurntSushi/toml)"]:::app
        Generator["Completion-Script Generator"]:::app
        Writer["Output Writer"]:::app
    end

    %% Build & Release Pipeline
    subgraph "Build & Release Pipeline"
        Src["Source Code"]:::dev
        Module["Go Modules\n(go.mod, go.sum)"]:::dev
        GoBuild["Go Build"]:::dev
        Goreleaser["Goreleaser\n(.goreleaser.yaml)"]:::dev
        Aqua["Aqua Spec\n(aqua.yaml)"]:::dev
        Dist["Published Binaries"]:::dev
    end

    %% Runtime Flow
    User -->|"invoke command"| CLI
    CLI -->|"dispatch"| Cobra
    Cobra -->|"read config"| Config
    Cobra -->|"calls parser"| Parser
    Parser -->|"parsed config"| Generator
    Generator -->|"generate script"| Writer
    Writer -->|"write .zsh files"| Data
    Data -->|"fpath directory"| Zsh

    %% Build Flow
    Src --> GoBuild
    GoBuild --> Module
    GoBuild --> Goreleaser
    GoBuild --> Aqua
    GoBuild --> Dist

    %% Click Events
    click CLI "https://github.com/hidehic0/custom-completion-zsh/blob/main/main.go"
    click Cobra "https://github.com/hidehic0/custom-completion-zsh/blob/main/main.go"
    click Parser "https://github.com/hidehic0/custom-completion-zsh/blob/main/main.go"
    click Generator "https://github.com/hidehic0/custom-completion-zsh/blob/main/main.go"
    click Writer "https://github.com/hidehic0/custom-completion-zsh/blob/main/main.go"
    click DefaultConfig "https://github.com/hidehic0/custom-completion-zsh/blob/main/defaultconfig.toml"
    click Goreleaser "https://github.com/hidehic0/custom-completion-zsh/blob/main/.goreleaser.yaml"
    click Aqua "https://github.com/hidehic0/custom-completion-zsh/blob/main/aqua.yaml"
    click Module "https://github.com/hidehic0/custom-completion-zsh/blob/main/go.mod"
    click Module "https://github.com/hidehic0/custom-completion-zsh/blob/main/go.sum"
    click README "https://github.com/hidehic0/custom-completion-zsh/blob/main/README.md"
    click License "https://github.com/hidehic0/custom-completion-zsh/tree/main/LICENSE"
    click Gitignore "https://github.com/hidehic0/custom-completion-zsh/blob/main/.gitignore"

    %% Styles
    classDef user fill:#BBE1FA,stroke:#1A3A5F
    classDef app fill:#C6F6D5,stroke:#2F855A
    classDef storage fill:#E2E8F0,stroke:#4A5568
    classDef dev fill:#EDF2F7,stroke:#A0AEC0
```
