# kratos06/codedog architecture

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

- Interactive diagram: https://gitdiagram.com/kratos06/codedog
- Repository: https://github.com/kratos06/codedog

## Overview

##### Project Type & Purpose
- Codedog is an open-source, Python-based AI-powered code-review assistant. It’s shipped both as a library and a command-line tool (CLI) that integrates with GitHub/GitLab, uses Large Language Models (OpenAI, Azure OpenAI, DeepSeek) to fetch pull/merge requests, generate summaries, suggestions, and optionally email reports.

##### File-Structure Analysis
- Top-level:
- codedog/ : core library
– actors/ (reporters)
– chains/ (LLM-prompt chains)
– models/ (data structures: PR, diff, commit, etc.)
– processors/ (business logic orchestrator)
– retrievers/ (GitHub/GitLab connectors)
– templates/ (language-specific prompt templates)
– utils/ (config loader, diff utils, email, Git hooks, LangChain helpers)
- run_codedog*.py, examples/ : CLI entrypoints & examples
- tests/ : unit + integration tests
- docs/ : user/setup guides + auto-generated API docs
- Config files: .env.sample, pyproject.toml/poetry.toml, GitHub Actions/workflows for CI/CD.

##### README Insights
- Purpose: “Automatically review your pull requests… provide summaries and suggestions”
- Features: PR summarization, diff summarization, code review feedback, multi-LLM & multi-language support, email notifications, commit hooks.
- Architecture hints: retriever → LLM chains → reporters.

a. Main Components:
- CLI / Runner
- Config Loader (.env, env vars)
- Processor
- Retrievers (GitHub, GitLab)
- Models (PR, Diff, Commit, Repository)
- Chains (Prompt builders + LLM clients)
- Actors / Reporters (PR summary, code review, email reporter)
- Templates (EN/CN prompts)
- External Services:
– VCS APIs (GitHub, GitLab REST APIs)
– LLM Providers (OpenAI / Azure / DeepSeek)
– Email / SMTP server (optional)
b. Relationships & Data Flow:
1. User runs CLI (run_codedog.py) → CLI loads Config
2. CLI → Processor.pull_request_processor
3. Processor selects Retriever → calls VCS API → returns raw PR data
4. Retriever maps to Models (PullRequest, Diff, etc.)
5. Processor invokes Chains:
– For diff: code_review_chain (build prompts via templates) → LLM API → returns suggestions
– For PR: pr_summary_chain → LLM API → returns summary
6. Actors/Reporters format LLM results into Markdown/Email
7. Reporter outputs to console or via EmailUtils to SMTP
c. Architectural Patterns & Principles:
- Modular plugin architecture for retrievers & LLM models
- Chain-of-Responsibility pattern via LangChain-style chains
- Separation of concerns: data modeling vs. prompt building vs. output formatting
- Dependency injection for easy testing/mocking (see tests/)
d. Key Technologies & Frameworks:
- Python 3.10+, Poetry for dependency management
- Requests or HTTPX for API calls (wrapped in retrievers)
- LangChain utilities (codedog/utils/langchain_utils.py)
- dotenv for config (.env)
- SMTP (smtplib) for email
- pytest for testing

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "CLI & Config"
        CLI["CLI / Runner"]:::internal
        Config["Config Loader (.env)"]:::config
    end

    subgraph "Processing"
        Processor["PullRequestProcessor"]:::internal
    end

    subgraph "Retrievers"
        BaseRet["BaseRetriever"]:::internal
        GHRet["GitHubRetriever"]:::internal
        GLRet["GitLabRetriever"]:::internal
    end

    subgraph "Models"
        PRModel["PullRequest"]:::internal
        DiffModel["Diff"]:::internal
        CommitModel["Commit"]:::internal
        RepoModel["Repository"]:::internal
    end

    subgraph "Chains"
        CRC["CodeReviewChain"]:::internal
        PRSC["PrSummaryChain"]:::internal
        Prompts["CommonPrompts"]:::internal
    end

    subgraph "Reporters"
        CRR["CodeReviewReporter"]:::internal
        PRR["PRSummaryReporter"]:::internal
        PullReqR["PullRequestReporter"]:::internal
    end

    subgraph "External Services"
        VCS["VCS APIs (GitHub/GitLab)"]:::external
        LLM["LLM Providers"]:::external
        SMTP["SMTP Server"]:::external
    end

    CLI --> Config
    CLI --> Processor
    Processor --> BaseRet
    BaseRet --> GHRet
    BaseRet --> GLRet
    GHRet -->|"calls API"| VCS
    GLRet -->|"calls API"| VCS
    GHRet --> PRModel
    GHRet --> DiffModel
    GLRet --> PRModel
    GLRet --> DiffModel
    Processor --> CRC
    Processor --> PRSC
    CRC --> Prompts
    PRSC --> Prompts
    CRC -->|"calls LLM"| LLM
    PRSC -->|"calls LLM"| LLM
    Processor --> CRR
    Processor --> PRR
    Processor --> PullReqR
    CRR -->|"outputs to console"| CLI
    PRR -->|"outputs to console"| CLI
    PullReqR -->|"outputs to console"| CLI
    CRR -->|"email via"| SMTP
    PRR -->|"email via"| SMTP
    PullReqR -->|"email via"| SMTP

    click CLI "https://github.com/kratos06/codedog/blob/master/run_codedog.py"
    click Config "https://github.com/kratos06/codedog/blob/master/.env.sample"
    click Processor "https://github.com/kratos06/codedog/blob/master/codedog/processors/pull_request_processor.py"
    click BaseRet "https://github.com/kratos06/codedog/blob/master/codedog/retrievers/base.py"
    click GHRet "https://github.com/kratos06/codedog/blob/master/codedog/retrievers/github_retriever.py"
    click GLRet "https://github.com/kratos06/codedog/blob/master/codedog/retrievers/gitlab_retriever.py"
    click PRModel "https://github.com/kratos06/codedog/blob/master/codedog/models/pull_request.py"
    click DiffModel "https://github.com/kratos06/codedog/blob/master/codedog/models/diff.py"
    click CommitModel "https://github.com/kratos06/codedog/blob/master/codedog/models/commit.py"
    click RepoModel "https://github.com/kratos06/codedog/blob/master/codedog/models/repository.py"
    click CRC "https://github.com/kratos06/codedog/blob/master/codedog/chains/code_review/base.py"
    click PRSC "https://github.com/kratos06/codedog/blob/master/codedog/chains/pr_summary/base.py"
    click Prompts "https://github.com/kratos06/codedog/blob/master/codedog/chains/prompts.py"
    click CRR "https://github.com/kratos06/codedog/blob/master/codedog/actors/reporters/code_review.py"
    click PRR "https://github.com/kratos06/codedog/blob/master/codedog/actors/reporters/pr_summary.py"
    click PullReqR "https://github.com/kratos06/codedog/blob/master/codedog/actors/reporters/pull_request.py"

    classDef internal fill:#e0f7ff,stroke:#00aaff,color:#000;
    classDef external fill:#e0ffee,stroke:#00aa00,color:#000;
    classDef config fill:#fff0e0,stroke:#ff9900,color:#000;
```
