# abhishekmishragithub/codestory architecture

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

- Interactive diagram: https://gitdiagram.com/abhishekmishragithub/codestory
- Repository: https://github.com/abhishekmishragithub/codestory

## Overview

##### Project type and purpose
- This is a Python-based CLI tool (“codestory”) that generates clear, concise commit messages (and PR descriptions) by:
- Inspecting the user’s Git repository state (diffs, staged changes)
- Calling out to an LLM (configurable model) to draft messages
- Formatting the LLM output according to preset commit/PR templates (with optional emojis or detailed descriptions)

##### File structure
- Top-level files
- pyproject.toml / setup.py / requirements.txt – packaging / dependencies
- .env.example / config.py – environment / configuration management
- codestory/ package
- cli.py – entry point for the `codestory` command
- config.py – loads user preferences (model, flags, emojis)
- git_utils.py – gathers diffs, staged files, repo metadata
- llm_utils.py – handles API calls to the chosen LLM (e.g., OpenAI, Gemini)
- commit_formats.py – defines message/PR templates and applies styling
- debug_script.py – a self-serve debugging tool or dev sandbox
- tests/ – unit tests for git_utils and commit_formats modules
- thoughts/ – internal design notes

##### README for additional insights
- The “Architecture/Workflow” section shows a flowchart:
- User invokes CLI → config is loaded → git utilities collect context → LLM is called → formatted output is returned
- Environment variables and model selection can be overridden via CLI flags

a. Main components
1. CLI Layer
– codestory/cli.py
– Argument parsing (model, include-description, emoji flags)
2. Configuration Loader
– codestory/config.py
– Environment variables / .env file / defaults
3. Git Utility
– codestory/git_utils.py
– Staged changes, diffs, repo metadata
4. LLM Integration
– codestory/llm_utils.py
– API client, request/response handling, rate limiting
5. Message Formatter
– codestory/commit_formats.py
– Templates, emojis, detailed descriptions
6. Debug Module (optional)
– codestory/debug_script.py
– Local testing of flows without actual Git repo or API calls
7. External Services
– Git CLI / local repo
– LLM Provider API (OpenAI, Gemini, etc.)
b. Relationships & interactions
- User → CLI Layer
- CLI Layer → Configuration Loader → returns settings
- CLI Layer → Git Utility → retrieves diff/context
- CLI Layer → LLM Integration (with settings + context) → gets raw message
- CLI Layer → Message Formatter → final commit/PR text
- CLI Layer → Output (stdout or direct Git commit)
- Optional: Debug Module can bypass Git/LLM calls and work with canned data
c. Architectural patterns / design principles
– Single Responsibility: each module has a distinct role (config, git, LLM, formatting)
– Dependency Injection: CLI passes config into downstream modules
– Extensibility: supports multiple models, toggles (description, emoji)
– Testability: clear separation allows unit testing of git_utils and formatting
d. Key technologies / libraries
– Python 3.x, click or argparse (in cli.py)
– python-dotenv or built-in os.environ (config.py)
– subprocess or GitPython (git_utils.py)
– requests / official SDK (llm_utils.py)
– pytest (tests/)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User
    User["User"]:::external

    %% codestory package
    subgraph "codestory package"
        direction TB
        CLI["CLI Parser"]:::internal
        Config["Config Loader"]:::internal
        GitUtil["Git Utility"]:::internal
        LLMClient["LLM Client"]:::internal
        Formatter["Message Formatter"]:::internal
        Debug["Debug Module"]:::optional
    end

    %% External services
    GitRepo["Git CLI / Local Repo"]:::external
    LLMAPI["LLM Provider API"]:::external
    Output["Output (stdout / Git commit)"]:::external

    %% Test harness
    TestGit["Test: git_utils"]:::test
    TestFmt["Test: commit_formats"]:::test

    %% Flow
    User -->|"invokes codestory"| CLI
    CLI -->|"loads CLI args"| Config
    CLI -->|"passes args & config"| GitUtil
    GitUtil -->|"retrieves diff/context"| GitRepo
    CLI -->|"passes context & config"| LLMClient
    LLMClient -->|"sends JSON request"| LLMAPI
    LLMClient -->|"receives raw message"| CLI
    CLI -->|"passes raw message & config"| Formatter
    Formatter -->|"formatted text"| Output

    %% Debug path
    CLI -->|"--debug flag"| Debug
    Debug -->|"canned data"| Formatter

    %% Tests connections
    TestGit --> GitUtil
    TestFmt --> Formatter

    %% Click events
    click CLI "https://github.com/abhishekmishragithub/codestory/blob/main/codestory/cli.py"
    click Config "https://github.com/abhishekmishragithub/codestory/blob/main/codestory/config.py"
    click GitUtil "https://github.com/abhishekmishragithub/codestory/blob/main/codestory/git_utils.py"
    click LLMClient "https://github.com/abhishekmishragithub/codestory/blob/main/codestory/llm_utils.py"
    click Formatter "https://github.com/abhishekmishragithub/codestory/blob/main/codestory/commit_formats.py"
    click Debug "https://github.com/abhishekmishragithub/codestory/blob/main/codestory/debug_script.py"
    click TestGit "https://github.com/abhishekmishragithub/codestory/blob/main/tests/test_git_utlis.py"
    click TestFmt "https://github.com/abhishekmishragithub/codestory/blob/main/tests/test_commit_formats.py"

    %% Styles
    classDef internal fill:#blue,stroke:#000,color:#fff
    classDef external fill:#2ecc71,stroke:#000,color:#000
    classDef optional fill:#95a5a6,stroke:#000,color:#fff
    classDef test fill:#f1c40f,stroke:#000,color:#000
```
