# mr-ezo949/aicommits architecture

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

- Interactive diagram: https://gitdiagram.com/mr-ezo949/aicommits
- Repository: https://github.com/mr-ezo949/aicommits

## Overview

aicommits is a CLI that turns staged Git changes into validated Conventional Commit messages. Its main workflow reads staged paths and diffs, filters and truncates model context, checks for secrets, generates and validates a message, then offers regeneration, commit, copy, or dry-run. Repository rules and recent commit subjects provide optional local context. The sampled source shows the CLI orchestrating these stages and the Groq provider; some wiring for README-documented features is inferred only where the CLI excerpt is incomplete, so uncertain links are omitted.

Main entry points: [`src/cli.ts`](https://github.com/mr-ezo949/aicommits/blob/main/src/cli.ts) (CLI orchestrator), [`src/cli/generation.ts`](https://github.com/mr-ezo949/aicommits/blob/main/src/cli/generation.ts) (Generation retries), [`src/providers/groq.ts`](https://github.com/mr-ezo949/aicommits/blob/main/src/providers/groq.ts) (Groq provider), [`src/cli/git.ts`](https://github.com/mr-ezo949/aicommits/blob/main/src/cli/git.ts) (Git operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflow"]
  node_cli["CLI orchestrator<br/>[cli.ts]"]
  node_options["Option parsing<br/>[options.ts]"]
end

subgraph group_context["Change context"]
  node_git["Git operations<br/>[git.ts]"]
  node_payload["Diff filtering<br/>[payload.ts]"]
  node_rules[("Saved repo rules<br/>[git.ts]")]
end

subgraph group_messages["Message generation"]
  node_generation["Generation retries<br/>[generation.ts]"]
  node_validation["Commit validation<br/>[commitMessage.ts]"]
end

subgraph group_integrations["External integrations"]
  node_provider["Groq provider<br/>[groq.ts]"]
  node_provider_contract["Provider interface<br/>[types.ts]"]
end

node_user(("CLI user"))
node_git_host[("Git repository")]
node_groq_service{{"Groq API"}}
node_clipboard{{"System clipboard"}}

node_user -->|"runs CLI"| node_cli
node_cli -->|"parses arguments"| node_options
node_cli -->|"reads staged changes"| node_git
node_git -->|"queries Git"| node_git_host
node_cli -->|"loads or saves"| node_rules
node_rules -->|"stores under .git"| node_git_host
node_cli -->|"builds model context"| node_payload
node_cli -->|"requests message"| node_generation
node_generation -->|"generates candidate"| node_provider
node_generation -->|"validates output"| node_validation
node_provider -.->|"implements"| node_provider_contract
node_provider -->|"requests completion"| node_groq_service
node_cli -->|"commits accepted message"| node_git_host
node_cli -->|"copies message"| node_clipboard

click node_cli "https://github.com/mr-ezo949/aicommits/blob/main/src/cli.ts"
click node_options "https://github.com/mr-ezo949/aicommits/blob/main/src/cli/options.ts"
click node_git "https://github.com/mr-ezo949/aicommits/blob/main/src/cli/git.ts"
click node_payload "https://github.com/mr-ezo949/aicommits/blob/main/src/cli/payload.ts"
click node_rules "https://github.com/mr-ezo949/aicommits/blob/main/src/cli/git.ts"
click node_generation "https://github.com/mr-ezo949/aicommits/blob/main/src/cli/generation.ts"
click node_validation "https://github.com/mr-ezo949/aicommits/blob/main/src/cli/commitMessage.ts"
click node_provider "https://github.com/mr-ezo949/aicommits/blob/main/src/providers/groq.ts"
click node_provider_contract "https://github.com/mr-ezo949/aicommits/blob/main/src/providers/types.ts"

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_cli,node_options,node_user toneBlue
class node_git,node_payload,node_rules,node_git_host toneAmber
class node_generation,node_validation,node_groq_service toneMint
class node_provider,node_provider_contract toneRose
class node_clipboard toneIndigo
```

## Components

### CLI workflow

- [CLI orchestrator](https://github.com/mr-ezo949/aicommits/blob/main/src/cli.ts): `src/cli.ts`
- [Option parsing](https://github.com/mr-ezo949/aicommits/blob/main/src/cli/options.ts): `src/cli/options.ts`

### Change context

- [Git operations](https://github.com/mr-ezo949/aicommits/blob/main/src/cli/git.ts): `src/cli/git.ts`
- [Diff filtering](https://github.com/mr-ezo949/aicommits/blob/main/src/cli/payload.ts): `src/cli/payload.ts`
- [Saved repo rules](https://github.com/mr-ezo949/aicommits/blob/main/src/cli/git.ts): `src/cli/git.ts`

### Message generation

- [Generation retries](https://github.com/mr-ezo949/aicommits/blob/main/src/cli/generation.ts): `src/cli/generation.ts`
- [Commit validation](https://github.com/mr-ezo949/aicommits/blob/main/src/cli/commitMessage.ts): `src/cli/commitMessage.ts`

### External integrations

- [Groq provider](https://github.com/mr-ezo949/aicommits/blob/main/src/providers/groq.ts): `src/providers/groq.ts`
- [Provider interface](https://github.com/mr-ezo949/aicommits/blob/main/src/providers/types.ts): `src/providers/types.ts`

### Other components

- **CLI user**
- **Git repository**
- **Groq API**
- **System clipboard**

## Connections

- CLI user → CLI orchestrator: runs CLI
- CLI orchestrator → Option parsing: parses arguments
- CLI orchestrator → Git operations: reads staged changes
- Git operations → Git repository: queries Git
- CLI orchestrator → Saved repo rules: loads or saves
- Saved repo rules → Git repository: stores under .git
- CLI orchestrator → Diff filtering: builds model context
- CLI orchestrator → Generation retries: requests message
- Generation retries → Groq provider: generates candidate
- Generation retries → Commit validation: validates output
- Groq provider → Provider interface: implements
- Groq provider → Groq API: requests completion
- CLI orchestrator → Git repository: commits accepted message
- CLI orchestrator → System clipboard: copies message