# jaydoubleu/pycomet architecture

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

- Interactive diagram: https://gitdiagram.com/jaydoubleu/pycomet
- Repository: https://github.com/jaydoubleu/pycomet

## Overview

##### Main Components
- CLI Layer (Entry Point): Represented by the “cli.py” module, this is where user commands (like commit, preview, and config) are handled.
- Configuration Manager: “config.py” reads user settings from the YAML file (~/.config/pycomet/config.yaml) and applies necessary configurations (including API keys and preference flags).
- AI Integration Module: “ai.py” is dedicated to interfacing with external AI providers (such as Anthropic Claude, OpenAI, Google Gemini, and Azure OpenAI) for generating commit messages.
- Git Interaction Module: “git.py” manages interactions with the local Git repository, facilitating the addition, preview, and actual commit actions.
- Core Models & Helpers: “models.py” and potential utility functions (in other modules) encapsulate core data structures and common logic.

##### Relationships and Data Flows
- Config Flow: Show that the “Configuration Manager” loads and updates settings from the config file which influences how the AI module and Git module operate.
- Testing and Quality Control: Optionally, note that the “tests” directory includes tests designed to verify behavior across modules (this component can be depicted separately or as annotations to the main modules).

##### Architectural Patterns and Technologies
- Separation of Concerns: The architecture neatly separates command handling, configuration management, external API integration, and Git interactions.
- Modular Structure: Each Python module (cli.py, config.py, ai.py, git.py, models.py) is designed to tackle a specific aspect of the tool’s functionality.
- External Integration: Emphasize the dependency on AI providers, with the provider chosen via configuration. Also include references to key libraries such as Click (for CLI) and litellm (for AI calls).

- Start from the User Terminal (depicting the user’s execution of commands such as "pycomet commit", "pycomet preview", "pycomet config").
- CLI layer (from cli.py) intercepting these commands.
- From the CLI, branch out:
- One branch to the Configuration module (config.py) which loads settings from the YAML config.
- Another branch to the AI Integration module (ai.py) which handles message generation by making requests to external AI providers.
- After message generation, link to the Git Interaction module (git.py) that processes the commit (using git commands) into the local repository.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["User Terminal"]:::external
    B["CLI Layer (cli.py)"]:::internal
    C1["Configuration Manager (config.py)"]:::internal
    C2["AI Integration Module (ai.py)"]:::internal
    C3["Git Interaction Module (git.py)"]:::internal
    D["Core Models & Helpers (models.py)"]:::internal
    E["Tests (tests)"]:::test

    F["Config File (~/.config/pycomet/config.yaml)"]:::external
    G["AI Providers"]:::external
    H["CLI Library (Click)"]:::external
    I["AI Library (litellm)"]:::external
    J["Local Git Repository"]:::external

    %% User initiates command
    A -->|"issues_command"| B

    %% CLI Module interactions
    B -->|"invokes_config"| C1
    B -->|"invokes_AI"| C2
    B -->|"triggers_commit"| C3
    B -->|"uses_Click"| H

    %% Configuration Manager loads settings
    C1 -->|"loads_settings"| F
    C1 -->|"configures_AI"| C2
    C1 -->|"configures_Git"| C3

    %% AI Module calls external providers and uses AI library
    C2 -->|"calls_provider"| G
    C2 -->|"uses_litellm"| I

    %% Git Module interacts with local repo
    C3 -->|"executes_git_cmds"| J

    %% Core Models & Helpers supports internal modules
    D ---|"supports"| C1
    D ---|"supports"| C2
    D ---|"supports"| C3

    %% Testing verifies core functionalities
    E ---|"tests"| B
    E ---|"tests"| C1
    E ---|"tests"| C2
    E ---|"tests"| C3

    %% Click Events for direct file mapping
    click B "https://github.com/jaydoubleu/pycomet/blob/main/src/pycomet/cli.py"
    click C1 "https://github.com/jaydoubleu/pycomet/blob/main/src/pycomet/config.py"
    click C2 "https://github.com/jaydoubleu/pycomet/blob/main/src/pycomet/ai.py"
    click C3 "https://github.com/jaydoubleu/pycomet/blob/main/src/pycomet/git.py"
    click D "https://github.com/jaydoubleu/pycomet/blob/main/src/pycomet/models.py"
    click E "https://github.com/jaydoubleu/pycomet/tree/main/tests"

    %% Styles
    classDef internal fill:#bbf,stroke:#333,stroke-width:2px;
    classDef external fill:#fdd,stroke:#333,stroke-width:2px;
    classDef test fill:#dfd,stroke:#333,stroke-width:2px;
```
