# di-sukharev/opencommit architecture

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

- Interactive diagram: https://gitdiagram.com/di-sukharev/opencommit
- Repository: https://github.com/di-sukharev/opencommit

## Overview

##### Project Type & Purpose
- This is a TypeScript-based CLI tool (opencommit) plus a companion GitHub Action that auto-generates git commit messages via AI.
- The core functionality lives in a reusable “engine” layer that wraps HTTP calls to various LLM providers (OpenAI, Anthropic, Ollama, etc.), and a set of “commands” that expose that functionality to the CLI and Git hooks.

##### High-Level File Structure & Architectural Patterns
- src/cli.ts: the single entrypoint for the `oco` CLI.
- src/commands/*: each file is a subcommand (commit, config, hook management, commitlint integration).
- src/engine/*: adapter pattern—one engine per LLM provider, all implementing a common Engine interface.
- src/modules/commitlint: plugin/module that integrates @commitlint as an optional prompt module.
- src/utils: shared helper functions (git diff extraction, token counting, sleep, etc.).
- src/i18n: internationalization JSON files and loader.
- src/migrations: lightweight migration system for evolving the local/global config schema.
- src/github-action.ts: entrypoint for the GitHub Action.
- out/*.cjs & wasm: compiled artifacts distributed on npm.

##### Main Components
a. CLI Layer
- oco CLI entrypoint (src/cli.ts)
- Command dispatcher (maps CLI args to src/commands/*)
b. Command Modules
- Commit generation (`commit.ts`, `generateCommitMessageFromGitDiff.ts`)
- Config management (`config.ts`)
- Git hook install/uninstall (`githook.ts`, `prepare-commit-msg-hook.ts`)
- Commitlint adapter (`modules/commitlint`)
c. Engine Layer (Adapter Pattern)
- Abstract Engine interface (Engine.ts)
- Concrete providers (openAi.ts, anthropic.ts, azure.ts, flowise.ts, ollama.ts, etc.)
- HTTP client component to call external LLM APIs (configured via OCO_API_URL, custom headers)
d. Persistence & Configuration
- Local repo config (`.env`, `.opencommitignore`)
- Global config in `~/.opencommit` (managed by migrations and utils)
e. Git Integration
- Git CLI (diff extraction, staging, commit API)
- Git hooks (`prepare-commit-msg`)
f. GitHub Action
- GitHub runner (actions/checkout + setup-node)
- github-action.ts: wraps the same engine/commands as the CLI but triggered on push
g. External Services
- LLM Providers (OpenAI, Anthropic, Ollama, Flowise, etc.)
- GitHub API (for action metadata & write permissions)

##### Component Relationships & Data Flow
- User → `oco`
→ CLI parses args → Dispatch to a Command Module →
- Reads git diff via utils/git.ts
- Loads config via migrations & utils
- Calls EngineManager → selects a provider → makes HTTP request → receives AI-generated commit message →
- Writes Git commit via `git commit` → optionally pushes
- User → `git commit` (with prepare-commit-msg hook)
→ Hook script calls into CLI layer to prefill commit message
- GitHub Action workflow
→ on.push → checkout → node runner → github-action.ts → invokes the same commit-improvement logic for all new commits → pushes back

##### Technologies & Frameworks
- Node.js + TypeScript
- esbuild for bundling
- Jest for unit & e2e tests
- Git (hooks & CLI)
- GitHub Actions
- HTTP to LLM endpoints
- i18n JSON files

##### Architectural Patterns & Design Principles
- Adapter pattern for engine providers (common interface, pluggable)
- Modular command architecture (each command encapsulates its own logic)
- Hexagonal / clean separation: CLI layer → application logic (commands) → domain (engine) → infrastructure (HTTP, Git)
- Migrations for evolving local/global config
- Plugin-style modules for optional features (commitlint)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "CLI Layer"
        CLI["oco CLI entrypoint"]:::internal
        click CLI "https://github.com/di-sukharev/opencommit/blob/master/src/cli.ts"
        Dispatcher["Command Dispatcher"]:::internal
        click Dispatcher "https://github.com/di-sukharev/opencommit/blob/master/src/CommandsEnum.ts"
    end
    CLI -->|"parses args"| Dispatcher

    subgraph "Command Modules"
        CommitCmd["commit.ts"]:::internal
        click CommitCmd "https://github.com/di-sukharev/opencommit/blob/master/src/commands/commit.ts"
        GenCmd["generateCommitMessageFromGitDiff.ts"]:::internal
        click GenCmd "https://github.com/di-sukharev/opencommit/blob/master/src/generateCommitMessageFromGitDiff.ts"
        ConfigCmd["config.ts"]:::internal
        click ConfigCmd "https://github.com/di-sukharev/opencommit/blob/master/src/commands/config.ts"
        HookCmd["githook.ts"]:::internal
        click HookCmd "https://github.com/di-sukharev/opencommit/blob/master/src/commands/githook.ts"
        PrepareHook["prepare-commit-msg-hook.ts"]:::internal
        click PrepareHook "https://github.com/di-sukharev/opencommit/blob/master/src/commands/prepare-commit-msg-hook.ts"
        CommitlintCmd["commitlint.ts"]:::internal
        click CommitlintCmd "https://github.com/di-sukharev/opencommit/blob/master/src/commands/commitlint.ts"
        CommitlintMod["modules/commitlint"]:::internal
        click CommitlintMod "https://github.com/di-sukharev/opencommit/tree/master/src/modules/commitlint/"
    end
    Dispatcher --> CommitCmd
    Dispatcher --> GenCmd
    Dispatcher --> ConfigCmd
    Dispatcher --> HookCmd
    Dispatcher --> PrepareHook
    Dispatcher --> CommitlintCmd
    CommitlintCmd --> CommitlintMod

    subgraph "Utils & Infrastructure"
        GitUtils["utils/git.ts"]:::internal
        click GitUtils "https://github.com/di-sukharev/opencommit/blob/master/src/utils/git.ts"
        EngineUtil["utils/engine.ts"]:::internal
        click EngineUtil "https://github.com/di-sukharev/opencommit/blob/master/src/utils/engine.ts"
        DiffUtil["mergeDiffs"]:::internal
        click DiffUtil "https://github.com/di-sukharev/opencommit/blob/master/src/utils/mergeDiffs.ts"
        TokenUtil["tokenCount"]:::internal
        click TokenUtil "https://github.com/di-sukharev/opencommit/blob/master/src/utils/tokenCount.ts"
        SleepUtil["sleep"]:::internal
        click SleepUtil "https://github.com/di-sukharev/opencommit/blob/master/src/utils/sleep.ts"
        RemoveTags["removeContentTags"]:::internal
        click RemoveTags "https://github.com/di-sukharev/opencommit/blob/master/src/utils/removeContentTags.ts"
        RemoveConv["removeConventionalCommitWord"]:::internal
        click RemoveConv "https://github.com/di-sukharev/opencommit/blob/master/src/utils/removeConventionalCommitWord.ts"
        RandomInt["randomIntFromInterval"]:::internal
        click RandomInt "https://github.com/di-sukharev/opencommit/blob/master/src/utils/randomIntFromInterval.ts"
        CheckVersion["checkIsLatestVersion"]:::internal
        click CheckVersion "https://github.com/di-sukharev/opencommit/blob/master/src/utils/checkIsLatestVersion.ts"
        TryTm["trytm"]:::internal
        click TryTm "https://github.com/di-sukharev/opencommit/blob/master/src/utils/trytm.ts"
    end
    CommitCmd -->|"reads diff"| GitUtils
    GenCmd --> GitUtils
    CommitCmd --> DiffUtil
    GenCmd --> DiffUtil
    CommitCmd --> TokenUtil
    CommitCmd --> SleepUtil

    subgraph "Engine Adapters"
        EngineInt["Engine.ts"]:::internal
        click EngineInt "https://github.com/di-sukharev/opencommit/blob/master/src/engine/Engine.ts"
        OpenAI["openAi.ts"]:::internal
        click OpenAI "https://github.com/di-sukharev/opencommit/blob/master/src/engine/openAi.ts"
        Anthropic["anthropic.ts"]:::internal
        click Anthropic "https://github.com/di-sukharev/opencommit/blob/master/src/engine/anthropic.ts"
        Azure["azure.ts"]:::internal
        click Azure "https://github.com/di-sukharev/opencommit/blob/master/src/engine/azure.ts"
        Flowise["flowise.ts"]:::internal
        click Flowise "https://github.com/di-sukharev/opencommit/blob/master/src/engine/flowise.ts"
        Ollama["ollama.ts"]:::internal
        click Ollama "https://github.com/di-sukharev/opencommit/blob/master/src/engine/ollama.ts"
        Gemini["gemini.ts"]:::internal
        click Gemini "https://github.com/di-sukharev/opencommit/blob/master/src/engine/gemini.ts"
        Groq["groq.ts"]:::internal
        click Groq "https://github.com/di-sukharev/opencommit/blob/master/src/engine/groq.ts"
        Mistral["mistral.ts"]:::internal
        click Mistral "https://github.com/di-sukharev/opencommit/blob/master/src/engine/mistral.ts"
        MLX["mlx.ts"]:::internal
        click MLX "https://github.com/di-sukharev/opencommit/blob/master/src/engine/mlx.ts"
        Openrouter["openrouter.ts"]:::internal
        click Openrouter "https://github.com/di-sukharev/opencommit/blob/master/src/engine/openrouter.ts"
        TestAI["testAi.ts"]:::internal
        click TestAI "https://github.com/di-sukharev/opencommit/blob/master/src/engine/testAi.ts"
        Deepseek["deepseek.ts"]:::internal
        click Deepseek "https://github.com/di-sukharev/opencommit/blob/master/src/engine/deepseek.ts"
    end
    CommitCmd -->|"calls engine"| EngineInt
    GenCmd --> EngineInt
    EngineInt --> EngineUtil
    EngineUtil -->|"HTTP request"| LLM

    subgraph "Config Store & Migrations"
        ConfigStore["Config Store (local/global)"]:::config
        Migrations["Migrations"]:::config
        click Migrations "https://github.com/di-sukharev/opencommit/tree/master/_src_migrations_dirs_"
        click Migrations1 "https://github.com/di-sukharev/opencommit/blob/master/src/migrations/_migrations.ts"
        click Migrations2 "https://github.com/di-sukharev/opencommit/blob/master/src/migrations/_run.ts"
        click Migrations3 "https://github.com/di-sukharev/opencommit/blob/master/src/migrations/00_use_single_api_key_and_url.ts"
        click Migrations4 "https://github.com/di-sukharev/opencommit/blob/master/src/migrations/01_remove_obsolete_config_keys_from_global_file.ts"
        click Migrations5 "https://github.com/di-sukharev/opencommit/blob/master/src/migrations/02_set_missing_default_values.ts"
    end
    ConfigCmd -->|"loads config"| ConfigStore
    ConfigStore --> Migrations

    subgraph "GitHub Action"
        ActionEntrypoint["github-action.ts"]:::internal
        click ActionEntrypoint "https://github.com/di-sukharev/opencommit/blob/master/src/github-action.ts"
        ActionYaml["action.yml"]:::internal
    end
    ActionEntrypoint --> Dispatcher
    ActionEntrypoint --> ActionYaml

    subgraph "External Services"
        LLM["LLM Providers"]:::external
        GitHubAPI["GitHub API"]:::external
    end
    EngineUtil --> LLM
    ActionEntrypoint --> GitHubAPI

    classDef internal fill:#D0E8FF,stroke:#024eaa,color:#024eaa
    classDef config fill:#E0FFD0,stroke:#3a8f11,color:#3a8f11
    classDef external fill:#FFE0B2,stroke:#a65e00,color:#a65e00
```
