# natrimmer/claude_commit architecture

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

- Interactive diagram: https://gitdiagram.com/natrimmer/claude_commit
- Repository: https://github.com/natrimmer/claude_commit

## Overview

##### Project type and purpose
- This is a Go-based CLI tool (“Claude Commit”) that automates the generation of Git commit messages by calling Anthropic’s Claude API. It reads staged changes, builds a prompt, sends an HTTP request to Claude, and outputs a formatted commit message following Conventional Commits.

##### File structure
- Top-level files:
- main.go / main_test.go – entry point and unit tests
- go.mod – Go module declarations
- .github/workflows/release.yml – CI/CD pipeline for building and releasing binaries
- devenv.* – Nix/direnv dev environment setup
- No “frontend” or “backend” folders: it’s a single-binary CLI.
- External dependencies are managed via Go modules; configuration is stored in `~/.claude-commit/config.json`.

##### Key insights from the README
- Commands: config, view, models, commit
- Workflow:
a. Read API key and model from config file
b. Run `git diff --staged` to gather changes
c. POST diff + prompt to Claude API endpoint
d. Receive JSON response with suggested commit
e. And optionally run `git commit -m "<message>"`
- Zero runtime dependencies beyond Go stdlib + HTTP.

##### Main components
A. User & Terminal (CLI Interface)
B. CLI Application (“claude_commit” binary)
1. Configuration Module (reads/writes `~/.claude-commit/config.json`)
2. Git Module (executes `git diff --staged`, can shell out to `git`)
3. Prompt Builder / Service Layer (constructs request payload)
4. HTTP Client Module (sends POST to Claude API)
5. Output Formatter (parses API response, colorizes output)
C. Local File System (config file storage)
D. External Systems
1. Git Repository (your code base, staged changes)
2. Anthropic Claude API (remote LLM service)

##### Relationships and data flows
- User → CLI: user types `claude_commit commit`
- CLI Configuration Module ↔ Local FS: read/write JSON config
- CLI Git Module → Git Repo: run `git diff --staged` → returns diff text
- Prompt Builder → HTTP Client: package diff + metadata into JSON request
- HTTP Client → Claude API (HTTPS POST) → Claude API responds with JSON containing commit suggestion
- Output Formatter → Terminal: colorized commit message and exit prompt
- (Optional) CLI can shell out to `git commit -m ...` to finalize commit

##### Architectural patterns & design principles
- Layered architecture: CLI (presentation) → service (prompt builder) → infra (Git, HTTP, FS)
- Single-responsibility modules: each package/file handles one concern (config, Git, API, UI)
- Zero-dependency runtime: relies only on Go stdlib + HTTP

##### Final advice
- Be explicit about each module and its responsibility
- Local FS vs. Binary internals vs. External services
- Keep labels concise but descriptive (e.g., “PromptBuilder.buildRequest(diff)”)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    UserTerminal["User & Terminal\n(cli)"]:::presentation

    %% CLI Application with Modules
    subgraph "CLI Application (claude_commit)" 
        direction TB
        ConfigModule["Configuration Module"]:::infra
        GitModule["Git Module"]:::infra
        PromptBuilder["Prompt Builder"]:::service
        HTTPClient["HTTP Client Module"]:::infra
        OutputFormatter["Output Formatter"]:::service
    end

    %% Local and External Resources
    subgraph "Local Resources"
        direction TB
        ConfigFile[(Config File\n~/.claude-commit/config.json)]:::storage
        GitRepo["Git Repository"]:::storage
    end

    subgraph "External Services"
        direction TB
        ClaudeAPI(["Anthropic Claude API\nhttps://api.anthropic.com/v1/complete"]):::external
    end

    %% CI/CD and Dev Environment
    subgraph "Development & CI/CD"
        direction TB
        GoMod["go.mod"]:::config
        UnitTests["main_test.go"]:::config
        Workflow[".github/workflows/release.yml"]:::config
        subgraph "Dev Environment"
            direction TB
            DevenvNix["devenv.nix"]:::config
            DevenvYaml["devenv.yaml"]:::config
            DevenvLock["devenv.lock"]:::config
        end
    end

    %% Data Flows
    UserTerminal -->|"claude_commit commit"| ConfigModule
    ConfigModule -->|"reads config"| ConfigFile
    UserTerminal -->|"claude_commit commit"| GitModule
    GitModule -->|"runs git diff --staged"| GitRepo
    GitModule -->|"shell out to git commit"| GitRepo
    GitModule --> PromptBuilder
    PromptBuilder -->|"buildRequest(diff)"| HTTPClient
    HTTPClient -->|"HTTP POST diff+prompt"| ClaudeAPI
    ClaudeAPI -->|"JSON response"| HTTPClient
    HTTPClient --> OutputFormatter
    OutputFormatter -->|"output commit message"| UserTerminal

    %% Click Events
    click ConfigModule "https://github.com/natrimmer/claude_commit/blob/main/main.go"
    click GitModule "https://github.com/natrimmer/claude_commit/blob/main/main.go"
    click PromptBuilder "https://github.com/natrimmer/claude_commit/blob/main/main.go"
    click HTTPClient "https://github.com/natrimmer/claude_commit/blob/main/main.go"
    click OutputFormatter "https://github.com/natrimmer/claude_commit/blob/main/main.go"
    click UserTerminal "https://github.com/natrimmer/claude_commit/blob/main/main.go"
    click GoMod "https://github.com/natrimmer/claude_commit/blob/main/go.mod"
    click UnitTests "https://github.com/natrimmer/claude_commit/blob/main/main_test.go"
    click Workflow "https://github.com/natrimmer/claude_commit/blob/main/.github/workflows/release.yml"
    click DevenvNix "https://github.com/natrimmer/claude_commit/blob/main/devenv.nix"
    click DevenvYaml "https://github.com/natrimmer/claude_commit/blob/main/devenv.yaml"
    click DevenvLock "https://github.com/natrimmer/claude_commit/blob/main/devenv.lock"

    %% Styles
    classDef presentation fill:#daf7dc,stroke:#2e7d32,color:#2e7d32;
    classDef infra fill:#d0e8f2,stroke:#0277bd,color:#01579b;
    classDef service fill:#fff3cd,stroke:#ffb300,color:#ff6f00;
    classDef storage fill:#f1f8e9,stroke:#689f38,color:#33691e;
    classDef external fill:#fdecea,stroke:#d32f2f,color:#b71c1c;
    classDef config fill:#e8eaf6,stroke:#3949ab,color:#1a237e;
```
