# kaarut/testpilot architecture

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

- Interactive diagram: https://gitdiagram.com/kaarut/testpilot
- Repository: https://github.com/kaarut/testpilot

## Overview

##### Project type and purpose
- This is a GitHub‐integrated code review bot (ChatGPT-powered) that can be used either as:
- A GitHub Action (runs on GitHub’s hosted runners)
- A GitHub App (Probot) self-hosted on AWS Lambda or in a Docker/PM2 container
- Purpose: Automatically review pull request diffs, generate review comments via OpenAI (or GitHub/Azure LLMs), and post results back to the PR.

##### File structure
- Top-level deployment configs:
- .github/workflows/cr.yml – GitHub Action workflow
- serverless.yml + src/aws-lambda.cjs – AWS Lambda (Probot App) deployment
- Dockerfile + pm2.config.cjs – Docker/PM2 self-hosting
- “action/” directory – bundled Action code (rollup output), includes:
- index.cjs, github-action.js – entry points
- worker*.js, middleware, vocab.bpe, _tiktoken_bg.wasm – tokenization pipeline
- “src/” directory – TypeScript source for core bot logic:
- bot.ts, chat.ts, log.ts, github-action.cjs, aws-lambda.cjs
- “api/github/webhooks/index.ts” – optional webhook handler for a custom API
- Test suite and fixtures in “test/”
- Config files: package.json, tsconfig.json, rollup.config.ts, jest.config.js

##### README insights
- Explains two integration modes: GitHub Action vs. self-hosted Probot App
- Describes environment variables (OPENAI_API_KEY, MODEL, USE_GITHUB_MODELS, etc.)
- Deployment instructions for AWS Lambda (via serverless) and Docker/PM2

##### Main components and interactions
A. GitHub Platform
– Triggers: pull_request events (opened, reopened, synchronize)
– Destination: either a workflow that runs the Action or a webhook delivery to the Probot App
B. GitHub Actions Runner (if using Action)
– Checks out code, loads anc95/ChatGPT-CodeReview@main, and invokes the Action container
C. Action Container
– Node.js process running bundled code in “action/”
– Parses PR diff, passes it through the tokenization pipeline (vocab.bpe + WASM)
– Calls Bot Core Logic
D. Bot Core Logic
– chat.ts builds the prompt, selects model endpoint (OpenAI, Azure, or GitHub models)
– bot.ts orchestrates API call and formats the response
– log.ts records metrics/errors
– middleware.ts handles multipart parsing if needed
E. LLM Endpoint (external)
– OpenAI API or GitHub models endpoint, returning review suggestions
F. GitHub API
– Posts comments to the PR timeline or file-diff annotations
G. Alternate self-host mode (Probot App)
– An HTTP server (src/index.ts) listens for webhooks
– Deployed via AWS Lambda (serverless.yml) or Docker (Dockerfile + PM2)
– Same Bot Core Logic invoked inside the Lambda handler or Express app

##### Architectural patterns and design principles
- Separation of concerns: tokenization, prompt construction, API invocation, and logging are modular
- Polyglot deployment: single codebase works as Action or Probot App
- Serverless-first with fallback to containerized hosting
- Use of WASM for efficient on-the-fly token encoding

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% GitHub Platform
    A["PR Events & API"]:::platform

    %% Deployment Paths
    A -->|"GitHub Action event"| B["GitHub Actions Runner"]:::hosting
    A -->|"webhook POST /pull_request"| C["HTTP Webhook Endpoint"]:::hosting

    %% GitHub Action Workflow
    subgraph "GitHub Action Workflow" 
        WA["GitHub Action Workflow"]:::hosting
    end
    WA --> B

    %% Action Container
    subgraph "Action Container"
        Metadata["Action Metadata"]:::hosting
        Container["Action Container Code Bundle"]:::hosting
    end
    B --> Container
    Metadata --> Container

    %% Tokenizer Layer
    Container --> Tokenizer["Tokenizer Layer"]:::core

    %% Bot Core Logic
    subgraph "Bot Core Logic"
        Chat["chat.ts"]:::core
        Bot["bot.ts"]:::core
        Log["log.ts"]:::core
        Middleware["middleware.ts"]:::core
        Fetch["fetch-polyfill.cjs"]:::core
        Shim["github-action.cjs"]:::core
    end
    Tokenizer --> Chat
    Chat --> Bot
    Bot --> Log
    Bot --> Middleware
    Middleware --> Fetch
    Shim --> Bot

    %% External LLM and GitHub API
    Bot -->|"OpenAI Chat API: /v1/chat/completions"| LLM(("OpenAI/GitHub/Azure LLM")):::external
    LLM --> Bot
    Bot -->|"POST comments"| GitHubAPI(("GitHub API")):::platform
    GitHubAPI --> A

    %% Probot App Deployment
    subgraph "Probot App Deployment"
        Lambda["AWS Lambda Handler"]:::hosting
        Serverless["Serverless Config"]:::config
        Express["Entry Point (src/index.ts)"]:::hosting
    end
    C --> Lambda
    Express --> C
    Lambda --> Chat

    %% Self-Hosting Container
    subgraph "Self-Hosting Container"
        Docker["Dockerfile"]:::hosting
        PM2["pm2.config.cjs"]:::hosting
    end
    Docker --> Lambda
    PM2 --> Lambda

    %% Config & Tests
    subgraph "Config & Tests"
        Build["rollup.config.ts"]:::config
        TSConfig["tsconfig.json"]:::config
        TestSuite["Test Suite"]:::config
    end

    %% Click Events
    click WA "https://github.com/kaarut/testpilot/blob/main/.github/workflows/cr.yml"
    click Metadata "https://github.com/kaarut/testpilot/blob/main/action.yml"
    click Container "https://github.com/kaarut/testpilot/tree/main/action/"
    click Tokenizer "https://github.com/kaarut/testpilot/blob/main/action/_tiktoken_bg.wasm"
    click Chat "https://github.com/kaarut/testpilot/blob/main/src/chat.ts"
    click Bot "https://github.com/kaarut/testpilot/blob/main/src/bot.ts"
    click Log "https://github.com/kaarut/testpilot/blob/main/src/log.ts"
    click Middleware "https://github.com/kaarut/testpilot/blob/main/middleware.ts"
    click Fetch "https://github.com/kaarut/testpilot/blob/main/src/fetch-polyfill.cjs"
    click Shim "https://github.com/kaarut/testpilot/blob/main/src/github-action.cjs"
    click Lambda "https://github.com/kaarut/testpilot/blob/main/src/aws-lambda.cjs"
    click Serverless "https://github.com/kaarut/testpilot/blob/main/serverless.yml"
    click Express "https://github.com/kaarut/testpilot/blob/main/src/index.ts"
    click Docker "https://github.com/kaarut/testpilot/tree/main/Dockerfile"
    click PM2 "https://github.com/kaarut/testpilot/blob/main/pm2.config.cjs"
    click Build "https://github.com/kaarut/testpilot/blob/main/rollup.config.ts"
    click TSConfig "https://github.com/kaarut/testpilot/blob/main/tsconfig.json"
    click TestSuite "https://github.com/kaarut/testpilot/tree/main/test/"

    %% Styles
    classDef platform fill:#D8B4FE,stroke:#7C3AED,color:#000;
    classDef hosting fill:#DBEAFE,stroke:#3B82F6,color:#000;
    classDef core fill:#CFFAFE,stroke:#06B6D4,color:#000;
    classDef external fill:#D1FAE5,stroke:#10B981,color:#000;
    classDef config fill:#FDE68A,stroke:#D97706,color:#000;
```
