# presubmit/ai-reviewer architecture

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

- Interactive diagram: https://gitdiagram.com/presubmit/ai-reviewer
- Repository: https://github.com/presubmit/ai-reviewer

## Overview

##### Project Type and Purpose
- This project is a GitHub Action designed to perform intelligent, context-aware pull request (PR) reviews. Its purpose is to catch bugs, identify improvements, generate summaries, and interact intelligently via PR comments—all powered by an external Large Language Model (LLM) and working in concert with GitHub’s APIs.
- Key indicators from the README (e.g., “instant PR analysis,” “line-by-line review,” and “LLM integration”) confirm this as an automated code reviewer for GitHub repositories.

##### Analyzing the File Structure
- Top-level artifacts include configuration files (.env.example, tsconfig.json, package.json), workflow definitions in the .github directory (e.g. presubmit-review.yml), and source code (src folder with multiple modules).
- Within src, several modules (ai.ts, comments.ts, config.ts, context.ts, diff.ts, main.ts, messages.ts, octokit.ts, prompts.ts, pull_request.ts, pull_request_comment.ts) indicate a separation of concerns where:
- ai.ts likely handles interactions with the chosen LLM provider using the provided LLM_API_KEY.
- octokit.ts, pull_request.ts, and pull_request_comment.ts manage interactions with GitHub’s REST API via the Octokit library.
- diff.ts, messages.ts, and prompts.ts contribute the analysis logic, formatting review messages, and generating PR titles/descriptions.
- The presence of a jest.config, __tests__ directory, and mocks signals a robust structure for testing and isolating external service dependencies.

a. Main Components to Include:
- Entry Point (main.ts)
- LLM Integration (ai.ts) – responsible for sending the code/context to the external LLM.
- GitHub API Interface (octokit.ts, pull_request.ts, and pull_request_comment.ts) – interfacing with GitHub to fetch PR data and post review comments.
- Analysis & Diff Processing (diff.ts, messages.ts, prompts.ts) – performing the key logic to analyze code differences and generate feedback.
- Config and Context (config.ts, context.ts) – managing environment/configuration for the action.
- External Interactions:

b. Relationships and Data Flow:
- Start at main.ts, which calls config and context modules to set up the environment.
- Then, branch out to two paths:
▪ One path to GitHub API Interface modules that retrieve PR data (e.g., diff, PR details).
▪ Another path to the LLM Integration (ai.ts), which sends code snippets/prompts to the external LLM.

c. Architectural Patterns & Design Principles:
- Modularity: The clear separation of concerns among modules (review analysis, GitHub API handling, LLM integration) adheres to modular design.
- Integration with External Services: Highlights the dependency injection of sensitive secrets (LLM_API_KEY) and the streamlined communication with external APIs.
- Testability: The inclusion of __tests__ and mocks indicates a design that favors unit testing and mockable components.

d. Relevant Technologies & Frameworks:
- GitHub Actions for automation and workflow management.
- Node.js (with TypeScript) as the runtime environment.
- Octokit for interacting with GitHub’s API.
- External LLM providers (referenced through LLM_API_KEY and LLM_MODEL settings) like Claude, GPT-4, or Gemini.
- Jest for testing purposes.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Components
    GA["GitHub Actions: PR Events"]:::event
    RJR["Review Job Runner (ubuntu-latest)"]:::action
    GH["GitHub API (External)"]:::external
    LLM_Service["LLM Service"]:::cloud

    %% Internal Modules
    subgraph "Internal Modules"
        direction TB
        ME["Main Entry: main.ts"]:::internal
        subgraph "Setup & Config"
            direction TB
            CFG["Config: config.ts"]:::internal
            CTX["Context: context.ts"]:::internal
        end
        subgraph "API Interface"
            direction TB
            OCT["Octokit: octokit.ts"]:::internal
            PRD["PR Data: pull_request.ts"]:::internal
            PRC["PR Comment: pull_request_comment.ts"]:::internal
        end
        subgraph "Analysis & Diff Processing"
            direction TB
            DFF["Diff Processing: diff.ts"]:::internal
            MSG["Message Formatting: messages.ts"]:::internal
            PRM["Prompts: prompts.ts"]:::internal
        end
        LLMI["LLM Integration: ai.ts"]:::internal
    end

    %% Data Flow
    GA -->|"triggers"| RJR
    RJR -->|"executes"| ME
    ME -->|"loads"| CFG
    ME --> CTX
    ME -->|"fetch PR data"| OCT
    ME -->|"analyzes diff"| DFF
    DFF --> MSG
    MSG --> PRM
    PRM -->|"prepares prompt"| LLMI
    LLMI -->|"calls"| LLM_Service
    LLM_Service -->|"returns feedback"| OCT
    OCT -->|"retrieves details"| PRD
    OCT -->|"posts comments"| PRC
    PRC -->|"sends review to"| GH

    %% Classes
    classDef event fill:#f9c,stroke:#333,stroke-width:2px;
    classDef action fill:#fc9,stroke:#333,stroke-width:2px;
    classDef internal fill:#bbf,stroke:#333,stroke-width:2px;
    classDef external fill:#cff,stroke:#333,stroke-width:2px;
    classDef cloud fill:#cfc,stroke:#333,stroke-width:2px;

    %% Click Events
    click GA "https://github.com/presubmit/ai-reviewer/blob/main/.github/workflows/presubmit-review.yml"
    click RJR "https://github.com/presubmit/ai-reviewer/blob/main/action.yml"
    click ME "https://github.com/presubmit/ai-reviewer/blob/main/src/main.ts"
    click LLMI "https://github.com/presubmit/ai-reviewer/blob/main/src/ai.ts"
    click OCT "https://github.com/presubmit/ai-reviewer/blob/main/src/octokit.ts"
    click PRD "https://github.com/presubmit/ai-reviewer/blob/main/src/pull_request.ts"
    click PRC "https://github.com/presubmit/ai-reviewer/blob/main/src/pull_request_comment.ts"
    click DFF "https://github.com/presubmit/ai-reviewer/blob/main/src/diff.ts"
    click MSG "https://github.com/presubmit/ai-reviewer/blob/main/src/messages.ts"
    click PRM "https://github.com/presubmit/ai-reviewer/blob/main/src/prompts.ts"
    click CFG "https://github.com/presubmit/ai-reviewer/blob/main/src/config.ts"
    click CTX "https://github.com/presubmit/ai-reviewer/blob/main/src/context.ts"
```
