# jsburckhardt/gic architecture

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

- Interactive diagram: https://gitdiagram.com/jsburckhardt/gic
- Repository: https://github.com/jsburckhardt/gic

## Overview

Step 1: Identify Project Type and Purpose
- This is a CLI tool (“gic”) written in Go.
- Purpose: Automate git commit message generation by reading staged diffs, feeding them (with user‐provided instructions) to an LLM, and applying the resulting commit message.

Step 2: Analyze the File Structure
- Top‐level binaries:
- main.go + cmd/root.go – entrypoint and cobra CLI commands
- internal/ – core packages:
- config – parses `.gic`/`.env` config
- git – wrappers around Git CLI to fetch diffs, stage commits
- llm – abstraction over multiple LLM providers (OpenAI, Azure, Ollama)
- logger – structured logging
- script/install-gic.sh – installs the CLI binary

Step 3: Extract Insights from the README
- Configuration model: `.gic` or `.gic.yaml` with llm_instructions
- Environment variables select SERVICE_PROVIDER and credentials
- Workflow: CLI reads config → gathers git diff → calls LLM → prints/applies commit

A. Main Components
1. CLI Frontend
- Cobra-based command (`cmd/root.go`)
- main.go initialises config & logger
2. Config Loader
- Reads `.gic` file and `.env`
- Populates internal/config
3. Git Adapter
- Fetch staged diff (`git diff --staged`)
- Execute `git commit -m` or print
4. LLM Adapter
- internal/llm abstracts providers
- Chooses implementation based on SERVICE_PROVIDER
- Communicates over REST/HTTP to OpenAI, Azure, Ollama
5. Logger
- Structured output of errors/info
6. External Services
- OpenAI / Azure OpenAI / Ollama endpoints

1. User invokes `gic` → CLI Frontend
2. CLI → Config Loader → Config object
3. CLI → Logger initialized
4. CLI → Git Adapter (fetch diff)
5. CLI → LLM Adapter (pass diff + instructions) → External LLM API
6. External LLM API → LLM Adapter (response)
7. CLI → Git Adapter (`git commit`) or print to stdout

C. Architectural Patterns & Principles
- Single-binary CLI with package-level isolation
- Dependency injection for LLM provider
- Separation of concerns: config, git I/O, LLM I/O, logging
- Interface-based adapters for testability (see internal/git_test.go)

D. Key Technologies and Frameworks
- Go modules (go.mod)
- Cobra (CLI)
- net/http (LLM REST calls)
- Git CLI (shell out)
- Environment configuration (`.env`, cspell, devcontainer)

- Core functionality: prompt generation, LLM call, git integration
- Extension points: how new LLM providers fit into internal/llm
- Config file and env var injection

Step 6: Diagramming Guidelines
- Internal modules (solid blue)
- Environment variables feeding into config loader

Step 7: Emphasize Detail Without Overcomplicating
- Script or build step only if it affects runtime (e.g., install-gic.sh)
- That each component’s primary responsibility is annotated

- main.go & cmd/root.go at the top
- internal/config, internal/logger feeding into the CLI runtime
- internal/git and internal/llm side by side, each pointing to external systems (Git CLI and LLM APIs)
This will fully capture the gic architecture, highlight extension points, and clearly communicate flows.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Frontend
    subgraph "CLI Frontend"
        A1["main.go"]:::internal
        A2["cmd/root.go"]:::internal
    end

    %% Configuration
    subgraph "Configuration Loader"
        B["config.go\n(internal/config)"]:::internal
        E[".gic/.gic.yaml"]:::external
    end

    %% Logger
    C["logger.go\n(internal/logger)"]:::internal

    %% Core Adapters
    subgraph "Core Adapters"
        D1["git.go\n(internal/git)"]:::internal
        D1Test["git_test.go\n(internal/git)"]:::internal
        D2["llm.go\n(internal/llm)"]:::internal
    end

    %% External Systems
    subgraph "External Systems"
        G1["Git CLI"]:::external
        G2["LLM APIs\n(OpenAI/Azure/Ollama)"]:::external
    end

    %% Installer and Docs
    S["install-gic.sh\n(script/)"]:::external
    Doc["flow.excalidraw\n(docs/)"]:::external

    %% Data Flow
    A1 -->|"invokes CLI"| A2
    A2 -->|"initialize config"| B
    B -->|"reads file"| E
    A2 -->|"initialize logger"| C
    A2 -->|"GetDiff()"| D1
    D1 -->|"shell out"| G1
    A2 -->|"GenerateMessage(diff,instructions)"| D2
    D2 -->|"REST call"| G2
    G2 -->|"response"| D2
    A2 -->|"git commit -m"| D1
    S -->|"install binary"| A1
    Doc -->|"documentation"| A2

    %% Click Events
    click A1 "https://github.com/jsburckhardt/gic/blob/main/main.go"
    click A2 "https://github.com/jsburckhardt/gic/blob/main/cmd/root.go"
    click B "https://github.com/jsburckhardt/gic/blob/main/internal/config/config.go"
    click D1 "https://github.com/jsburckhardt/gic/blob/main/internal/git/git.go"
    click D1Test "https://github.com/jsburckhardt/gic/blob/main/internal/git/git_test.go"
    click D2 "https://github.com/jsburckhardt/gic/blob/main/internal/llm/llm.go"
    click C "https://github.com/jsburckhardt/gic/blob/main/internal/logger/logger.go"
    click S "https://github.com/jsburckhardt/gic/blob/main/script/install-gic.sh"
    click Doc "https://github.com/jsburckhardt/gic/blob/main/docs/flow.excalidraw"
    click E "https://github.com/jsburckhardt/gic/blob/main/.gic"

    %% Styles
    classDef internal fill:#D0E8FF,stroke:blue,stroke-width:2px
    classDef external fill:#E8FFE8,stroke:green,stroke-dasharray:5 5,stroke-width:2px
```
