# uliboooo/ghost_git_writer architecture

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

- Interactive diagram: https://gitdiagram.com/uliboooo/ghost_git_writer
- Repository: https://github.com/uliboooo/ghost_git_writer

## Overview

##### Project type and purpose
- This is a Rust-based command-line application (“ghost writer” / `ggw`) that invokes large-language-model APIs (OpenAI, Anthropic, Gemini, Deepseek) to automate tasks around Git: generating commit messages, summarizing diffs, producing README drafts, and suggesting semantic-version bumps.

##### File structure
- Top-level files:
- Cargo.toml / Cargo.lock (Rust package manifest)
- config_template.toml, reference/… (documentation and sample config)
- CI workflow: .github/workflows/rust.yml
- CLI executable entry point: src/main.rs
- Core modules in src/:
- cli.rs, cli_helper.rs → parse arguments, dispatch subcommands
- config.rs → load and validate configuration from file / env vars
- git.rs, get_input.rs → shell out to Git or read diffs from stdin
- commit_gen.rs, diff_sum_gen.rs, readme_gen.rs, which_sem.rs → orchestrate LLM prompt assembly and post-processing
- llm.rs → HTTP client that routes requests to the selected LLM provider
- helper.rs → shared utilities

##### README for additional insights
- Highlights four primary subcommands: `commit`, `readme`, `sumdiff`, `which-sem`.
- Emphasizes environment variables for API keys, global options (model, path, language, extra prompt, config file), and per-command flags.

a. Main components
- CLI Frontend
- Configuration Loader
- Git Interface & Diff Reader
- Source Scanner (for README generation)
- Task Orchestrators (CommitGen, ReadDiffGen, ReadmeGen, SemVerGen)
- LLM Client
- External LLM Services (Gemini, OpenAI, Anthropic, Deepseek)
- Output Handler (console, write files, git commit)

b. Relationships and data flow
1. User invokes `ggw <subcommand> [options]` → CLI Frontend
2. CLI Frontend calls Configuration Loader to merge env vars, config file, and CLI flags
3. Depending on subcommand:
- For `commit` and `sumdiff`: Git Interface shell-outs to `git diff` or reads diff from stdin
- For `readme`: Source Scanner walks the codebase or accepts explicit file lists
- For `which-sem`: Git Interface reads diff, passes to SemVerGen
4. The diff or source files are passed to the respective Task Orchestrator module
5. Task Orchestrator assembles a prompt and calls LLM Client
6. LLM Client issues HTTP requests to the chosen LLM provider and receives a response
7. Task Orchestrator post-processes the response
8. Output Handler prints results to stdout, optionally writes to README.md or invokes `git commit`

c. Architectural patterns and design principles
- Single-binary CLI structured as modular components
- Clear separation of concerns: argument parsing, config management, Git I/O, prompt generation, HTTP client, output
- Strategy pattern for LLM providers (pluggable via environment variables / flags)
- Stateless, functional tasks that transform inputs (diffs or source) into outputs (text)

d. Key technologies
- Rust and Cargo ecosystem
- clap or structopt (presumed) for CLI parsing
- reqwest or hyper for HTTP calls in llm.rs
- serde + toml for config parsing
- Standard library’s process::Command for Git interaction

##### Detail
- Every module from src/, even shared helper.rs, to show full separation of concerns
- How config_template.toml and environment variables feed into Config Loader

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data Sources"
        Env["Environment Variables"]:::datasource
        ConfigFile["config_template.toml"]:::datasource
        Manifest["Cargo.toml / Cargo.lock"]:::datasource
        Docs["reference/config.md & reference/logic_map.md"]:::datasource
        CI[".github/workflows/rust.yml"]:::datasource
    end

    subgraph "Internal Modules"
        CLI_Frontend["CLI Frontend\n(src/main.rs, cli.rs, cli_helper.rs)"]:::internal
        Config_Loader["Configuration Loader\n(src/config.rs)"]:::internal
        GitInterface["Git Interface & Diff Reader\n(src/git.rs, get_input.rs)"]:::internal
        SourceScanner["Source Scanner\n(src/get_input.rs)"]:::internal
        subgraph "Task Orchestrators"
            CommitGen["CommitGen\n(src/commit_gen.rs)"]:::internal
            DiffSumGen["DiffSumGen\n(src/diff_sum_gen.rs)"]:::internal
            ReadmeGen["ReadmeGen\n(src/readme_gen.rs)"]:::internal
            SemVerGen["SemVerGen\n(src/which_sem.rs)"]:::internal
        end
        LLM_Client["LLM Client\n(src/llm.rs)"]:::internal
        Helper["Shared Utilities\n(src/helper.rs)"]:::internal
        Output_Handler["Output Handler"]:::internal
    end

    subgraph "External LLM Services"
        OpenAI["OpenAI API"]:::external
        Anthropic["Anthropic API"]:::external
        Gemini["Gemini API"]:::external
        Deepseek["Deepseek API"]:::external
    end

    Env -->|"env vars"| Config_Loader
    ConfigFile -->|"config file"| Config_Loader
    Manifest -->|"package info"| CLI_Frontend
    Docs -->|"docs"| CLI_Frontend
    CI -->|"CI config"| CLI_Frontend

    CLI_Frontend -->|"arguments"| Config_Loader
    Config_Loader -->|"merged config"| CLI_Frontend
    CLI_Frontend -->|"subcommand"| GitInterface
    CLI_Frontend -->|"subcommand"| SourceScanner

    GitInterface -->|"git diff"| CommitGen
    GitInterface -->|"git diff"| DiffSumGen
    SourceScanner -->|"source files"| ReadmeGen
    GitInterface -->|"git diff"| SemVerGen

    CommitGen -->|"prompt"| LLM_Client
    DiffSumGen -->|"prompt"| LLM_Client
    ReadmeGen -->|"prompt"| LLM_Client
    SemVerGen -->|"prompt"| LLM_Client

    LLM_Client -->|"HTTP request"| OpenAI
    LLM_Client -->|"HTTP request"| Anthropic
    LLM_Client -->|"HTTP request"| Gemini
    LLM_Client -->|"HTTP request"| Deepseek

    OpenAI -->|"response"| LLM_Client
    Anthropic -->|"response"| LLM_Client
    Gemini -->|"response"| LLM_Client
    Deepseek -->|"response"| LLM_Client

    LLM_Client -->|"LLM response"| CommitGen
    LLM_Client -->|"LLM response"| DiffSumGen
    LLM_Client -->|"LLM response"| ReadmeGen
    LLM_Client -->|"LLM response"| SemVerGen

    CommitGen -->|"commit message"| Output_Handler
    DiffSumGen -->|"diff summary"| Output_Handler
    ReadmeGen -->|"README draft"| Output_Handler
    SemVerGen -->|"version suggestion"| Output_Handler

    Helper -->|"utilities"| CommitGen
    Helper -->|"utilities"| DiffSumGen
    Helper -->|"utilities"| ReadmeGen
    Helper -->|"utilities"| SemVerGen

    classDef internal fill:#AED6F1,stroke:#1F618D,color:#1B2631;
    classDef external fill:#F9E79F,stroke:#B7950B,color:#1B2631;
    classDef datasource fill:#A9DFBF,stroke:#196F3D,color:#1B2631;

    click CLI_Frontend "https://github.com/uliboooo/ghost_git_writer/blob/main/src/main.rs"
    click CLI_Frontend "https://github.com/uliboooo/ghost_git_writer/blob/main/src/cli.rs"
    click CLI_Frontend "https://github.com/uliboooo/ghost_git_writer/blob/main/src/cli_helper.rs"
    click Config_Loader "https://github.com/uliboooo/ghost_git_writer/blob/main/src/config.rs"
    click ConfigFile "https://github.com/uliboooo/ghost_git_writer/blob/main/config_template.toml"
    click GitInterface "https://github.com/uliboooo/ghost_git_writer/blob/main/src/git.rs"
    click GitInterface "https://github.com/uliboooo/ghost_git_writer/blob/main/src/get_input.rs"
    click SourceScanner "https://github.com/uliboooo/ghost_git_writer/blob/main/src/get_input.rs"
    click CommitGen "https://github.com/uliboooo/ghost_git_writer/blob/main/src/commit_gen.rs"
    click DiffSumGen "https://github.com/uliboooo/ghost_git_writer/blob/main/src/diff_sum_gen.rs"
    click ReadmeGen "https://github.com/uliboooo/ghost_git_writer/blob/main/src/readme_gen.rs"
    click SemVerGen "https://github.com/uliboooo/ghost_git_writer/blob/main/src/which_sem.rs"
    click LLM_Client "https://github.com/uliboooo/ghost_git_writer/blob/main/src/llm.rs"
    click Helper "https://github.com/uliboooo/ghost_git_writer/blob/main/src/helper.rs"
    click CI "https://github.com/uliboooo/ghost_git_writer/blob/main/.github/workflows/rust.yml"
    click Docs "https://github.com/uliboooo/ghost_git_writer/blob/main/reference/config.md"
    click Docs "https://github.com/uliboooo/ghost_git_writer/blob/main/reference/logic_map.md"
    click Manifest "https://github.com/uliboooo/ghost_git_writer/blob/main/Cargo.toml"
    click Manifest "https://github.com/uliboooo/ghost_git_writer/blob/main/Cargo.lock"
```
