# ammar-ahmed22/chlog architecture

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

- Interactive diagram: https://gitdiagram.com/ammar-ahmed22/chlog
- Repository: https://github.com/ammar-ahmed22/chlog

## Overview

##### Project type and purpose
- chlog is a Go-based CLI tool for generating structured JSON changelogs from Git history via AI models (OpenAI, Gemini).
- It’s not a web app or microservice platform, but a single binary that orchestrates a series of modules: Git integration, prompt generation, AI invocation, JSON formatting, and file I/O.

##### File structure
- Top-level files:
- main.go – starts the CLI (using Cobra)
- cmd/ – cobra command definitions (root, init, generate, models)
- ai/ – AI provider abstractions (openai.go, gemini.go, generic ai.go)
- git/ – Git interaction logic (retrieving commits, diffs)
- models/ – data structures for changelog entries and schemas
- utils/ – helpers for config loading, prompt construction, I/O utilities
- config & generate helpers in utils
- .github, goreleaser.yaml, Makefile, install scripts – CI/CD and release pipelines
- Patterns:
- Layered CLI → command handlers → domain modules (git, ai, models, utils)
- Modular provider design for easy extension
- Separation of concerns: prompting, I/O, formatting, business logic

##### Key insights from README
- CLI-first design, JSON to stdout, verbose logs to stderr
- Configurable via YAML or flags; flags override config
- Prepend entries in existing file vs. create new
- Support for multiple LLM providers via a provider interface

##### Detail is key
- Git Service calling out to the local Git repo via the Git CLI.
- Config loader reading chlog.yaml or CLI flags.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    subgraph "CLI Layer"
        Entrypoint["main.go"]:::internal
        RootCmd["cmd/root.go"]:::internal
        InitCmd["cmd/init.go"]:::internal
        GenCmd["cmd/generate.go"]:::internal
        ModelsCmd["cmd/models.go"]:::internal
    end

    %% Configuration
    subgraph "Configuration Manager"
        Config["utils/config.go"]:::internal
    end

    %% Domain Services
    subgraph "Domain Services"
        GitSvc["git/git.go"]:::internal
        Prompt["utils/prompt.go"]:::internal
        AIIface["ai/ai.go (Provider Interface)"]:::internal
        OpenAI["ai/openai.go"]:::internal
        Gemini["ai/gemini.go"]:::internal
        JSONModel["models/models.go"]:::internal
        Schema["changelog.json"]:::internal
        FileGen["utils/generate.go"]:::internal
        IOUtils["utils/utils.go"]:::internal
    end

    %% External Services
    subgraph "External Services"
        GitRepo["Local Git Repo"]:::external
        OpenAIAPI["OpenAI API"]:::external
        GeminiAPI["Gemini API"]:::external
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        GHBuild[".github/workflows/build.yaml"]:::pipeline
        GHRelease[".github/workflows/release.yaml"]:::pipeline
        GoReleaser[".goreleaser.yaml"]:::pipeline
        Makefile["Makefile"]:::pipeline
        Install["install.sh"]:::pipeline
    end

    %% Flows
    Entrypoint --> RootCmd
    Entrypoint --> InitCmd
    Entrypoint --> GenCmd
    Entrypoint --> ModelsCmd

    RootCmd --> Config
    InitCmd --> Config
    GenCmd --> Config

    GenCmd --> GitSvc
    GitSvc -->|"exec git CLI"| GitRepo

    GenCmd --> Prompt
    Prompt --> AIIface
    AIIface --> OpenAI
    AIIface --> Gemini
    OpenAI -->|"HTTP"| OpenAIAPI
    Gemini -->|"HTTP"| GeminiAPI

    OpenAI --> JSONModel
    Gemini --> JSONModel
    JSONModel --> Schema

    JSONModel --> FileGen
    FileGen --> IOUtils
    FileGen -->|"JSON stdout"| StdErr["stdout / stderr"]:::external

    ModelsCmd --> JSONModel

    %% CI/CD triggers
    GitRepo --> GHBuild
    GHBuild --> Makefile
    GHBuild --> Install
    GHBuild --> GoReleaser
    GHRelease --> GoReleaser

    %% Click Events
    click Entrypoint "https://github.com/ammar-ahmed22/chlog/blob/main/main.go"
    click RootCmd "https://github.com/ammar-ahmed22/chlog/blob/main/cmd/root.go"
    click InitCmd "https://github.com/ammar-ahmed22/chlog/blob/main/cmd/init.go"
    click GenCmd "https://github.com/ammar-ahmed22/chlog/blob/main/cmd/generate.go"
    click ModelsCmd "https://github.com/ammar-ahmed22/chlog/blob/main/cmd/models.go"
    click Config "https://github.com/ammar-ahmed22/chlog/blob/main/utils/config.go"
    click GitSvc "https://github.com/ammar-ahmed22/chlog/blob/main/git/git.go"
    click Prompt "https://github.com/ammar-ahmed22/chlog/blob/main/utils/prompt.go"
    click AIIface "https://github.com/ammar-ahmed22/chlog/blob/main/ai/ai.go"
    click OpenAI "https://github.com/ammar-ahmed22/chlog/blob/main/ai/openai.go"
    click Gemini "https://github.com/ammar-ahmed22/chlog/blob/main/ai/gemini.go"
    click JSONModel "https://github.com/ammar-ahmed22/chlog/blob/main/models/models.go"
    click Schema "https://github.com/ammar-ahmed22/chlog/blob/main/changelog.json"
    click FileGen "https://github.com/ammar-ahmed22/chlog/blob/main/utils/generate.go"
    click IOUtils "https://github.com/ammar-ahmed22/chlog/blob/main/utils/utils.go"
    click GHBuild "https://github.com/ammar-ahmed22/chlog/blob/main/.github/workflows/build.yaml"
    click GHRelease "https://github.com/ammar-ahmed22/chlog/blob/main/.github/workflows/release.yaml"
    click GoReleaser "https://github.com/ammar-ahmed22/chlog/blob/main/.goreleaser.yaml"
    click Makefile "https://github.com/ammar-ahmed22/chlog/tree/main/Makefile"
    click Install "https://github.com/ammar-ahmed22/chlog/blob/main/install.sh"

    %% Styles
    classDef internal fill:#D6EAF8,stroke:#1B4F72,color:#1B2631
    classDef external fill:#FADBD8,stroke:#7B241C,color:#641E16
    classDef pipeline fill:#F9E79F,stroke:#7D6608,color:#4D4D4D
```
