# mkusaka/gptcommit architecture

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

- Interactive diagram: https://gitdiagram.com/mkusaka/gptcommit
- Repository: https://github.com/mkusaka/gptcommit

## Overview

##### Project Identification
- gptcommit is a command‐line tool written in Rust that integrates with Git. Its purpose is to automatically generate descriptive commit messages using GPT-3 (or other LLMs) by analyzing commit diffs.
- The README confirms that it installs as a Git hook and interfaces with the OpenAI API. The file tree shows clear separation between source code (“src”), test files (“tests”), configuration and packaging directories, as well as prompt templates (“prompts”).

##### Analyzing the File Structure
- Key Directories:
- src – Contains the main application logic.
- src/main.rs, src/cli.rs, src/cmd.rs: Manage command-line operations.
- src/actions – Modules for installing, uninstalling, configuring, and preparing commit messages.
- src/llms – Contains modules for interacting with language model providers (e.g., openai.rs).
- Other files (e.g., src/git.rs, src/prompt.rs) indicate handling Git operations and prompt management.
- tests – Contains unit, benchmark, and e2e tests reinforcing robust behavior.
- prompts – Template files drive the generation of commit messages.
- Configuration Files:
- README, Cargo.toml, etc., signal that it’s a Rust project with CI/CD and packaging (winget) related scripts.
- Multiple configuration levels (global user, repository, environment variables) exist as implied in the README and in configuration handling within the source.

##### Components
a. Main Application (CLI Tool)
- This is the core Rust binary that is invoked as a result of Git actions. It serves as the entry point (via src/main.rs) and dispatches commands (install, uninstall, config, etc.).

b. Git Hook Integration
- A Git prepare-commit-msg hook triggers the tool when a commit is made. The hook installation and execution are managed by modules in src/actions (e.g., install.rs, prepare_commit_msg.rs) and associated shell scripts.

c. Command Dispatcher and CLI Interface
- Components such as src/cli.rs and src/cmd.rs process command-line arguments, offering subcommands (install, config, help, etc.).

d. Diff Extraction and Processing Module
- The application extracts file diffs from Git (likely via src/git.rs) that are fed into the logic that generates commit prompts.

e. Prompt Generation and Template Engine
- The tool uses Tera templates (as seen in the prompts folder) to build commit messages – incorporating diff data, commit titles, and summaries.

f. Configuration Management
- Multiple configuration sources (user, repo, and environment variables) are managed by modules (e.g., src/settings.rs and configuration parts in actions) to determine settings such as the OpenAI API key, model, language, etc.

g. LLM API Client and Communication
- Modules under src/llms (like openai.rs) handle HTTP requests to external OpenAI endpoints, getting GPT-generated responses.

h. External Dependencies
- Git System (triggers hooks, supplies diffs).
- OpenAI (or another LLM service) that processes prompts.
- Packaging/Deployment tools (Cargo for Rust, Homebrew or Winget for installation).

##### Interactions & Data Flow
- When a developer initiates a Git commit:
1. The Git hook (installed via the gptcommit install command) intercepts the commit process.
2. The CLI tool is invoked.
3. The tool collects commit diffs via Git commands (handled by src/git.rs).
4. The prompt generation module uses templates (from the prompts directory) and configuration settings (from the configuration management modules) to craft a request.
5. The LLM client (from src/llms/openai.rs) sends the prompt to the OpenAI API and awaits a response.
6. The response (the generated commit title/summary) is presented—with user options for editing before finalizing the commit.
- Git Hook → Main Application
- Main Application → Diff Extraction Module → Prompt Generation Module
- Prompt Generation Module → LLM API Client → External OpenAI Service
- API Response → Main Application → Git Commit Update

##### Important Architectural Patterns
- Separation of concerns: Each module (Git integration, configuration, LLM communication) is focused on a single responsibility.
- Extensibility: The design allows for potential future language model providers by abstracting LLM operations under dedicated modules.
- Configurable workflow: The layered configuration approach (user > repo > env) is a key design aspect.

- Labeled components for CLI, Git hook integration, diff extraction, prompt construction, configuration management, LLM client, and external services.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Git System"]:::external
    B["Git Hook Integration"]:::internal
    C["Main Application (CLI Tool)"]:::internal
    D["Command Dispatcher and CLI Interface"]:::internal
    E["Diff Extraction & Processing"]:::internal
    F["Configuration Management"]:::internal
    G["Prompt Generation & Template Engine"]:::internal
    H["LLM API Client"]:::internal
    I["OpenAI API"]:::external

    A -->|"triggers"| B
    B -->|"invokes"| C
    C -->|"dispatches"| D
    C -->|"extractsDiff"| E
    E -->|"generatesPrompt"| G
    F -->|"suppliesConfig"| G
    G -->|"callsLLM"| H
    H -->|"sendsPrompt"| I
    I -->|"returnsResp"| H
    H -->|"deliversResult"| C
    C -->|"updatesCommit"| A

    click C "https://github.com/mkusaka/gptcommit/blob/main/src/main.rs"
    click D "https://github.com/mkusaka/gptcommit/blob/main/src/cli.rs"
    click D "https://github.com/mkusaka/gptcommit/blob/main/src/cmd.rs"
    click B "https://github.com/mkusaka/gptcommit/blob/main/src/actions/prepare_commit_msg.rs"
    click B "https://github.com/mkusaka/gptcommit/blob/main/src/actions/install.rs"
    click E "https://github.com/mkusaka/gptcommit/blob/main/src/git.rs"
    click G "https://github.com/mkusaka/gptcommit/tree/main/prompts/"
    click G "https://github.com/mkusaka/gptcommit/blob/main/src/prompt.rs"
    click F "https://github.com/mkusaka/gptcommit/blob/main/src/settings.rs"
    click F "https://github.com/mkusaka/gptcommit/blob/main/src/actions/config.rs"
    click H "https://github.com/mkusaka/gptcommit/blob/main/src/llms/openai.rs"
    click H "https://github.com/mkusaka/gptcommit/blob/main/src/llms/llm_client.rs"

    classDef internal fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef external fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
```
