# qzhao19/auto-commit architecture

> Architecture diagram of the GitHub repository qzhao19/auto-commit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/qzhao19/auto-commit
- Repository: https://github.com/qzhao19/auto-commit

## Overview

auto-commit is a Rust CLI that turns staged Git changes—or an in-progress Git operation—into a Conventional Commits message, then lets the user accept, regenerate, or switch candidates before committing. The principal path loads configuration, inspects repository state, classifies and budgets staged diffs, assembles a prompt, calls an LLM, validates its response, and enters an interactive review loop. The README also documents OpenAI-compatible and Ollama backends and layered configuration. Unsampled subsystem links are included only where the README or source index supports them.

Main entry points: [`src/main.rs`](https://github.com/qzhao19/auto-commit/blob/main/src/main.rs) (CLI workflow), [`src/core/inter/cycle.rs`](https://github.com/qzhao19/auto-commit/blob/main/src/core/inter/cycle.rs) (Candidate review), [`src/infra/git/runner.rs`](https://github.com/qzhao19/auto-commit/blob/main/src/infra/git/runner.rs) (Git command runner), [`src/core/git/preflight/collector.rs`](https://github.com/qzhao19/auto-commit/blob/main/src/core/git/preflight/collector.rs) (Repository preflight)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI entry"]
  node_main["CLI workflow<br/>[main.rs]"]
end

subgraph group_gitflow["Git analysis"]
  node_preflight["Repository preflight<br/>[collector.rs]"]
  node_operation["Operation detection<br/>[detector.rs]"]
  node_staged["Staged metadata<br/>[collector.rs]"]
  node_classify["Diff classification<br/>[classifier.rs]"]
  node_budget["Diff budgeting<br/>[planner.rs]"]
  node_extract["Diff extraction<br/>[extractor.rs]"]
  node_context["Assembly context<br/>[context.rs]"]
end

subgraph group_generation["Message generation"]
  node_assembler["Prompt assembly<br/>[assembler.rs]"]
  node_client["LLM client<br/>[client.rs]"]
  node_providers["Provider adapters"]
  node_validator["Message validation<br/>[validator.rs]"]
end

subgraph group_review["Review and commit"]
  node_interactive["Candidate review<br/>[cycle.rs]"]
  node_terminal["Terminal UI<br/>[ui.rs]"]
  node_cache["Candidate cache<br/>[candidates.rs]"]
end

subgraph group_foundation["Runtime support"]
  node_config["Configuration loading<br/>[loader.rs]"]
  node_gitrunner["Git command runner<br/>[runner.rs]"]
end

node_user(("Developer"))
node_llmservices(("LLM services"))
node_gitrepo[("Git repository")]

node_user -->|"runs"| node_main
node_main -->|"loads config"| node_config
node_main -->|"creates runner"| node_gitrunner
node_main -->|"starts pipeline"| node_preflight
node_preflight -->|"queries repository"| node_gitrunner
node_main -->|"detects state"| node_operation
node_main -->|"collects staged data"| node_staged
node_main -->|"classifies files"| node_classify
node_main -->|"plans budget"| node_budget
node_main -->|"extracts diff"| node_extract
node_preflight -->|"inspects"| node_gitrepo
node_operation -->|"inspects state"| node_gitrepo
node_staged -.->|"reads index"| node_gitrepo
node_extract -->|"reads diff"| node_gitrepo
node_main -->|"receives result"| node_context
node_main -->|"assembles prompt"| node_assembler
node_assembler -->|"uses context"| node_context
node_main -->|"requests message"| node_client
node_client -->|"dispatches request"| node_providers
node_providers -.->|"sends request"| node_llmservices
node_main -->|"validates response"| node_validator
node_main -->|"starts review"| node_interactive
node_interactive -->|"renders interface"| node_terminal
node_interactive -->|"uses candidates"| node_cache
node_main -->|"commits accepted"| node_gitrunner
node_gitrunner -->|"runs Git commands"| node_gitrepo
node_user -->|"reviews choices"| node_interactive

click node_main "https://github.com/qzhao19/auto-commit/blob/main/src/main.rs"
click node_config "https://github.com/qzhao19/auto-commit/blob/main/src/infra/config/loader.rs"
click node_preflight "https://github.com/qzhao19/auto-commit/blob/main/src/core/git/preflight/collector.rs"
click node_operation "https://github.com/qzhao19/auto-commit/blob/main/src/core/git/operation/detector.rs"
click node_staged "https://github.com/qzhao19/auto-commit/blob/main/src/core/git/staged/collector.rs"
click node_classify "https://github.com/qzhao19/auto-commit/blob/main/src/core/git/diff/classifier.rs"
click node_budget "https://github.com/qzhao19/auto-commit/blob/main/src/core/git/diff/planner.rs"
click node_extract "https://github.com/qzhao19/auto-commit/blob/main/src/core/git/diff/extractor.rs"
click node_gitrunner "https://github.com/qzhao19/auto-commit/blob/main/src/infra/git/runner.rs"
click node_context "https://github.com/qzhao19/auto-commit/blob/main/src/core/pipe/context.rs"
click node_assembler "https://github.com/qzhao19/auto-commit/blob/main/src/core/pipe/assembler.rs"
click node_client "https://github.com/qzhao19/auto-commit/blob/main/src/core/llm/client.rs"
click node_providers "https://github.com/qzhao19/auto-commit/tree/main/src/core/llm/provider"
click node_validator "https://github.com/qzhao19/auto-commit/blob/main/src/core/pipe/validator.rs"
click node_interactive "https://github.com/qzhao19/auto-commit/blob/main/src/core/inter/cycle.rs"
click node_terminal "https://github.com/qzhao19/auto-commit/blob/main/src/infra/terminal/ui.rs"
click node_cache "https://github.com/qzhao19/auto-commit/blob/main/src/infra/cache/candidates.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main toneBlue
class node_preflight,node_operation,node_staged,node_classify,node_budget,node_extract,node_context,node_gitrepo toneAmber
class node_assembler,node_client,node_providers,node_validator toneMint
class node_interactive,node_terminal,node_cache toneRose
class node_config,node_gitrunner,node_user,node_llmservices toneIndigo
```

## Components

### CLI entry

- [CLI workflow](https://github.com/qzhao19/auto-commit/blob/main/src/main.rs): `src/main.rs`

### Git analysis

- [Repository preflight](https://github.com/qzhao19/auto-commit/blob/main/src/core/git/preflight/collector.rs): `src/core/git/preflight/collector.rs`
- [Operation detection](https://github.com/qzhao19/auto-commit/blob/main/src/core/git/operation/detector.rs): `src/core/git/operation/detector.rs`
- [Staged metadata](https://github.com/qzhao19/auto-commit/blob/main/src/core/git/staged/collector.rs): `src/core/git/staged/collector.rs`
- [Diff classification](https://github.com/qzhao19/auto-commit/blob/main/src/core/git/diff/classifier.rs): `src/core/git/diff/classifier.rs`
- [Diff budgeting](https://github.com/qzhao19/auto-commit/blob/main/src/core/git/diff/planner.rs): `src/core/git/diff/planner.rs`
- [Diff extraction](https://github.com/qzhao19/auto-commit/blob/main/src/core/git/diff/extractor.rs): `src/core/git/diff/extractor.rs`
- [Assembly context](https://github.com/qzhao19/auto-commit/blob/main/src/core/pipe/context.rs): `src/core/pipe/context.rs`

### Message generation

- [Prompt assembly](https://github.com/qzhao19/auto-commit/blob/main/src/core/pipe/assembler.rs): `src/core/pipe/assembler.rs`
- [LLM client](https://github.com/qzhao19/auto-commit/blob/main/src/core/llm/client.rs): `src/core/llm/client.rs`
- [Provider adapters](https://github.com/qzhao19/auto-commit/tree/main/src/core/llm/provider): `src/core/llm/provider`
- [Message validation](https://github.com/qzhao19/auto-commit/blob/main/src/core/pipe/validator.rs): `src/core/pipe/validator.rs`

### Review and commit

- [Candidate review](https://github.com/qzhao19/auto-commit/blob/main/src/core/inter/cycle.rs): `src/core/inter/cycle.rs`
- [Terminal UI](https://github.com/qzhao19/auto-commit/blob/main/src/infra/terminal/ui.rs): `src/infra/terminal/ui.rs`
- [Candidate cache](https://github.com/qzhao19/auto-commit/blob/main/src/infra/cache/candidates.rs): `src/infra/cache/candidates.rs`

### Runtime support

- [Configuration loading](https://github.com/qzhao19/auto-commit/blob/main/src/infra/config/loader.rs): `src/infra/config/loader.rs`
- [Git command runner](https://github.com/qzhao19/auto-commit/blob/main/src/infra/git/runner.rs): `src/infra/git/runner.rs`

### Other components

- **Developer**
- **LLM services**
- **Git repository**

## Connections

- Developer → CLI workflow: runs (evidence: `README.md`)
- CLI workflow → Configuration loading: loads config (evidence: `src/main.rs`)
- CLI workflow → Git command runner: creates runner (evidence: `src/main.rs`)
- CLI workflow → Repository preflight: starts pipeline
- Repository preflight → Git command runner: queries repository (evidence: `src/core/git/preflight/collector.rs`)
- CLI workflow → Operation detection: detects state
- CLI workflow → Staged metadata: collects staged data
- CLI workflow → Diff classification: classifies files
- CLI workflow → Diff budgeting: plans budget
- CLI workflow → Diff extraction: extracts diff
- Repository preflight → Git repository: inspects (evidence: `src/core/git/preflight/collector.rs`)
- Operation detection → Git repository: inspects state (evidence: `src/core/git/operation/detector.rs`)
- Staged metadata → Git repository: reads index
- Diff extraction → Git repository: reads diff (evidence: `src/core/git/diff/extractor.rs`)
- CLI workflow → Assembly context: receives result (evidence: `src/main.rs`)
- CLI workflow → Prompt assembly: assembles prompt (evidence: `src/main.rs`)
- Prompt assembly → Assembly context: uses context (evidence: `src/core/pipe/assembler.rs`)
- CLI workflow → LLM client: requests message (evidence: `src/main.rs`)
- LLM client → Provider adapters: dispatches request (evidence: `src/core/llm/client.rs`)
- Provider adapters → LLM services: sends request (evidence: `README.md`)
- CLI workflow → Message validation: validates response (evidence: `src/main.rs`)
- CLI workflow → Candidate review: starts review (evidence: `src/main.rs`)
- Candidate review → Terminal UI: renders interface (evidence: `src/core/inter/cycle.rs`)
- Candidate review → Candidate cache: uses candidates (evidence: `src/core/inter/cycle.rs`)
- CLI workflow → Git command runner: commits accepted (evidence: `src/main.rs`)
- Git command runner → Git repository: runs Git commands (evidence: `src/infra/git/runner.rs`)
- Developer → Candidate review: reviews choices (evidence: `README.md`)