# arakiss/commitloom architecture

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

- Interactive diagram: https://gitdiagram.com/arakiss/commitloom
- Repository: https://github.com/arakiss/commitloom

## Overview

##### Project Type and Purpose
- CommitLoom is an open-source CLI tool written in Python.
- Purpose: Analyze staged Git changes, call an AI service (OpenAI API), generate structured commit messages, batch large changes, and track usage metrics.
- Key features: CLI front-end, core modules for analysis and batching, AI integration, local metrics storage, and Git operations.

##### High-Level Architectural Components
a. CLI Layer
- Entry point (commitloom/__main__.py)
- CLI handler (commitloom/cli/cli_handler.py)
- Console module for rich output (commitloom/cli/console.py)
b. Core Layer
- Analyzer (commitloom/core/analyzer.py): inspects diffs, complexity, binary files
- Batch processor (commitloom/core/batch.py): splits or groups changes
- Git wrapper (commitloom/core/git.py): interacts with local Git (staging, commits)
c. Service Layer
- AI service (commitloom/services/ai_service.py): builds prompts, calls OpenAI API
- Metrics service (commitloom/services/metrics.py): records token usage, cost, time, writes to local metrics store
d. Configuration
- Settings loader (commitloom/config/settings.py): reads environment variables, .env files, global config
e. External Systems
- Git CLI / repository (local file system)
- OpenAI API (external cloud service)
- Local metrics storage (filesystem under ~/.local/share/commitloom/metrics or configured path)

##### Component Relationships and Data Flow
1. User invokes `loom` or `cl` command → CLI Layer.
2. CLI handler loads settings from Configuration.
3. CLI invokes Core Analyzer to parse and classify staged changes.
4. Batch processor in Core decides whether to split into multiple commits.
5. Core uses Git wrapper to gather diffs and staging info.
6. Core sends data to AI Service, which:
- Formats prompt
- Sends HTTP request to OpenAI API
- Receives generated commit message
7. Core invokes Git wrapper to create the commit(s) with AI-generated message(s).
8. Metrics Service collects data (tokens, cost, time saved), writes to local metrics storage.
9. CLI Console displays results and metrics to the user.

##### Architectural Patterns and Principles
- Layered Architecture: clear separation between CLI, core logic, external services, and configuration.
- Single Responsibility: each module handles one concern (analysis, batching, Git ops, AI calls, metrics).
- Dependency Injection: core modules take service instances (AIService, MetricsService) rather than hardcoding.
- Configuration-over-convention: settings module centralizes environment and file-based config.
- Testability: modules are decoupled, enabling comprehensive unit tests.

##### Technologies, Frameworks, Libraries
- Python (typing, modules), PyPI distribution via pyproject.toml.
- Click or argparse for CLI (inferred from cli_handler signature).
- Requests or OpenAI Python SDK for API calls.
- Ruff and MyPy for linting and type checking.
- Git CLI or GitPython for repository operations.
- Local file system for metrics (YAML/JSON or SQLite).
- GitHub Actions workflows for CI/CD.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration Layer
    subgraph "Configuration Layer"
        Settings["Settings Loader"]:::config
    end

    %% CLI Layer
    subgraph "CLI Layer"
        EntryPoint["Entry Point (__main__.py)"]:::cli
        CLIHandler["CLI Handler"]:::cli
        Console["Console Module"]:::cli
    end

    %% Core Layer
    subgraph "Core Layer"
        Analyzer["Analyzer"]:::core
        BatchProcessor["Batch Processor"]:::core
        GitWrapper["Git Wrapper"]:::core
    end

    %% Service Layer
    subgraph "Service Layer"
        AIService["AI Service"]:::service
        MetricsService["Metrics Service"]:::service
    end

    %% External Systems
    subgraph "External Systems"
        GitCLI(("Git CLI / Repo")):::external
        OpenAI["OpenAI API"]:::external
        MetricsStore[(Local Metrics Store)]:::external
    end

    %% Data Flow
    User((User)):::external -->|invokes `loom`/`cl`| EntryPoint
    EntryPoint -->|calls| CLIHandler
    CLIHandler -->|loads config| Settings
    CLIHandler -->|requests analysis| Analyzer
    Analyzer -->|fetches diffs| GitWrapper
    GitWrapper -->|provides staging info| Analyzer
    Analyzer -->|sends changes| BatchProcessor
    BatchProcessor -->|groups/splits| Analyzer
    Analyzer -->|formats prompt| AIService
    AIService -->|HTTP request| OpenAI
    OpenAI -->|commit message| AIService
    AIService -->|response| Analyzer
    Analyzer -->|create commit| GitWrapper
    GitWrapper -->|executes| GitCLI
    Analyzer -->|collects metrics| MetricsService
    MetricsService -->|writes metrics| MetricsStore
    MetricsService -->|reports| CLIHandler
    CLIHandler -->|displays results| Console

    %% Click Events
    click EntryPoint "https://github.com/arakiss/commitloom/blob/main/commitloom/__main__.py"
    click CLIHandler "https://github.com/arakiss/commitloom/blob/main/commitloom/cli/cli_handler.py"
    click Console "https://github.com/arakiss/commitloom/blob/main/commitloom/cli/console.py"
    click Analyzer "https://github.com/arakiss/commitloom/blob/main/commitloom/core/analyzer.py"
    click BatchProcessor "https://github.com/arakiss/commitloom/blob/main/commitloom/core/batch.py"
    click GitWrapper "https://github.com/arakiss/commitloom/blob/main/commitloom/core/git.py"
    click AIService "https://github.com/arakiss/commitloom/blob/main/commitloom/services/ai_service.py"
    click MetricsService "https://github.com/arakiss/commitloom/blob/main/commitloom/services/metrics.py"
    click Settings "https://github.com/arakiss/commitloom/blob/main/commitloom/config/settings.py"

    %% Styles
    classDef cli fill:#e0f7e9,stroke:#2a7f55,color:#2a7f55;
    classDef core fill:#e8f1fb,stroke:#1f4e79,color:#1f4e79;
    classDef service fill:#ffe8cc,stroke:#d97706,color:#d97706;
    classDef config fill:#f0f0f0,stroke:#6b7280,color:#374151;
    classDef external fill:#f0e6ff,stroke:#7c3aed,color:#7c3aed;
```
