# prash-kr-meena/github-bot-rabbithole architecture

> Architecture diagram of the GitHub repository prash-kr-meena/github-bot-rabbithole, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/prash-kr-meena/github-bot-rabbithole
- Repository: https://github.com/prash-kr-meena/github-bot-rabbithole

## Overview

This is a **local-development GitHub webhook integration project** consisting of **two Python bots**:
- **Issue Bot (`issue_bot.py`)**: listens for **Issue Comment** webhook events; reacts to the `/greet` command by posting a reply via the GitHub API.
- **PR Bot (`pr_bot.py`)**: listens for **Pull Request** webhook events; clones the repo for context, calls **Anthropic Claude** to generate a review, and posts review comments back to GitHub.

Both run locally as lightweight HTTP servers (very likely Flask) and rely on **ngrok** to expose local ports to GitHub Webhooks.

##### File-structure analysis (use this to derive components)
Top-level files indicate a small, script-oriented architecture (no packages/modules directory):
- **Runtime entrypoints**
- `issue_bot.py` — webhook handler + issue comment logic
- `pr_bot.py` — webhook handler + PR review logic
- **PR review logic**
- `pr_review.py` — likely encapsulates “analyze PR / call Anthropic / format review comments”
- **Testing & diagnostics**
- `run_tests.py` — orchestrates end-to-end checks
- `test_*` scripts — GitHub auth, ngrok connectivity, webhook simulation for each bot
- **Security/config utilities**
- `generate_secret.py` — webhook secret generation for signature verification
- `.env` referenced in README (not in tree, but assumed local)
- **Docs**
- `NGROK_SETUP.md`, `PR_TESTING.md`, `TESTING.md`
- **Dependencies**
- `requirements.txt` (implies Flask + GitHub API client + Anthropic client + requests, etc.)

##### README-derived architecture & runtime behavior
Key operational facts to reflect:
- **Issue bot** runs on `localhost:5000`, webhook path `/webhook`, GitHub event type: **issue_comment**
- **PR bot** runs on `localhost:5001`, webhook path `/webhook`, GitHub event type: **pull_request**
- ngrok forwards public HTTPS → local HTTP.
- Both require:
- **GitHub PAT** for calling GitHub REST APIs (posting comments/reviews)
- **Webhook secret** for validating webhook signatures (HMAC)
- PR bot additionally requires:
- **ANTHROPIC_API_KEY**, base URL, model selection.

##### Anthropic API (Claude) (PR bot only)

**Local runtime (your machine)**
##### Issue Bot Service (`issue_bot.py`, port 5000)
- Webhook endpoint: `/webhook`
- Command parser: `/greet`
- GitHub API client: “post issue comment”
- Webhook signature validator (secret)
##### PR Bot Service (`pr_bot.py`, port 5001)
- Webhook endpoint: `/webhook`
- PR event handler
- Repo cloning workspace (local filesystem temp dir)
- Diff/patch extraction
- AI review generator (via `pr_review.py`)
- GitHub API client: “create PR review / review comments”
- Webhook signature validator (secret)

**Config/secrets**
##### Environment Variables / .env
- `GITHUB_TOKEN` (PAT), `WEBHOOK_SECRET`
- `ANTHROPIC_*` (PR bot only)

**Optional but useful (for completeness)**
##### Test Harness (`run_tests.py` + `test_*.py`)
- not part of runtime path, but part of developer workflow and validation

##### GitHub → ngrok: Webhook delivery (HTTPS)
- event: `issue_comment`

##### GitHub → ngrok: Webhook delivery (HTTPS)
- event: `pull_request` (opened/synchronize/etc.)
##### GitHub → User-visible result: review comments appear on PR diff

- Developer runs: `python run_tests.py` → invokes `test_github_auth.py`, `test_ngrok.py`, `test_bot.py`, `test_pr_bot.py`
- These scripts may simulate webhook payloads directly to localhost endpoints.

##### Architectural patterns/principles actually present
Call these out visually or as annotations:
- **Event-driven webhook architecture** (GitHub events trigger handlers)
- **Two independent services** (Issue Bot and PR Bot are separate deployables/ports)
- **Tunnel-based ingress** for local development (ngrok)
- **External API orchestration** (GitHub REST + Anthropic)
- **Security boundary**: webhook signature verification + PAT-based outbound auth
- **Workspace-based analysis** for PR bot (clone repo locally for full context)

##### Relevant technologies (don’t guess too much, but include what’s strongly implied)
- **Python 3.6+**
- **GitHub API** (REST endpoints for issues/comments and PR reviews)
- **Anthropic Claude** (PR bot) with model/base URL from README
- **git** command usage (PR bot clone)

##### PR bot pipeline (the “meat” of the system)
- fetch PR → clone → compute changed files/patch → LLM review → map review to diff positions → post inline review comments

##### GitHub Review Publisher

This is where “separating into as many components as possible” pays off for accuracy.

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% External Systems
%% =========================
subgraph "External Systems"
direction TB
GH["GitHub (Repo + Webhooks + Events)"]:::external
NG["ngrok (Public HTTPS tunnel → localhost)"]:::external
ANTH["Anthropic API (Claude)"]:::external
end

%% =========================
%% Developer Machine (Local)
%% =========================
subgraph "Developer Machine (Local Runtime)"
direction TB

ENV["Environment Variables (.env)\n- GITHUB_TOKEN (PAT)\n- WEBHOOK_SECRET\n- ANTHROPIC_API_KEY (PR bot)"]:::secrets

subgraph "Issue Bot Service (Port 5000)"
direction TB
IB["Issue Bot HTTP Server\n:5000  /webhook"]:::service
IBH["Webhook Handler\n(event: issue_comment)"]:::component
IBSIG["Signature Validator\n(HMAC using WEBHOOK_SECRET)"]:::security
IBCMD["Command Parser\n(/greet)"]:::component
IBGH["GitHub API Client\n(Post issue comment)"]:::component
end

subgraph "PR Bot Service (Port 5001)"
direction TB
PRB["PR Bot HTTP Server\n:5001  /webhook"]:::service
PRH["Webhook Handler\n(event: pull_request)"]:::component
PRSIG["Signature Validator\n(HMAC using WEBHOOK_SECRET)"]:::security
PRFETCH["PR Data Fetcher\n(GitHub API: PR metadata/files)"]:::component

subgraph "PR Review Pipeline"
direction TB
CLONE["Repo Cloner\n(git clone + checkout PR SHA)"]:::component
WS[("Local FS Workspace\n(temp clone dir)")]:::storage
DIFF["Diff/Patch Extractor\n(changed files + hunks)"]:::component
PROMPT["Prompt Builder\n(context + diff)"]:::component
PRLOGIC["PR Review Logic\n(Claude prompt + mapping helpers)"]:::lib
LLM["LLM Client\n(Anthropic)"]:::component
MAP["Review Comment Mapper\n(diff positions → inline comments)"]:::component
PUBLISH["GitHub Review Publisher\n(create PR review + comments)"]:::component
end
end

subgraph "Test & Diagnostics (Developer Workflow)"
direction TB
TESTS["Test Harness\n(run end-to-end checks)"]:::test
T1["test_github_auth.py\n(PAT verification)"]:::test
T2["test_ngrok.py\n(tunnel connectivity)"]:::test
T3["test_bot.py\n(simulate issue_comment webhook)"]:::test
T4["test_pr_bot.py\n(simulate pull_request webhook)"]:::test
DOCS["Docs\nREADME + setup/testing guides"]:::docs
REQ["Python Dependencies\n(requirements.txt)"]:::docs
GENSEC["Webhook Secret Utility\n(generate WEBHOOK_SECRET)"]:::util
end

end

%% =========================
%% Webhook Ingress & Flows
%% =========================
GH -->|"Webhook HTTPS (issue_comment)"| NG
NG -->|"Forward HTTP POST → :5000/webhook"| IB
IB --> IBH --> IBSIG --> IBCMD -->|"if /greet"| IBGH
IBGH -->|"REST API: Create issue comment\nPAT (Authorization token)"| GH

GH -->|"Webhook HTTPS (pull_request)"| NG
NG -->|"Forward HTTP POST → :5001/webhook"| PRB
PRB --> PRH --> PRSIG --> PRFETCH
PRFETCH -->|"clone URL/refs"| CLONE
CLONE --> WS --> DIFF --> PROMPT --> PRLOGIC --> LLM
LLM -->|"HTTPS API call\nANTHROPIC_API_KEY"| ANTH
ANTH -->|"review text + suggestions"| LLM
LLM --> MAP --> PUBLISH
PUBLISH -->|"REST API: Create PR review + inline comments\nPAT (Authorization token)"| GH

%% =========================
%% Config/Secrets Wiring
%% =========================
ENV -->|"WEBHOOK_SECRET"| IBSIG
ENV -->|"GITHUB_TOKEN (PAT)"| IBGH
ENV -->|"WEBHOOK_SECRET"| PRSIG
ENV -->|"GITHUB_TOKEN (PAT)"| PRFETCH
ENV -->|"GITHUB_TOKEN (PAT)"| PUBLISH
ENV -->|"ANTHROPIC_API_KEY"| LLM

%% =========================
%% Tests (non-runtime paths)
%% =========================
TESTS --> T1
TESTS --> T2
TESTS --> T3
TESTS --> T4
T3 -.->|"POST to :5000/webhook"| IB
T4 -.->|"POST to :5001/webhook"| PRB
T1 -.->|"REST API auth check"| GH
T2 -.->|"verify tunnel endpoint"| NG

DOCS -.->|"setup guidance"| NG
REQ -.->|"installs deps"| IB
REQ -.->|"installs deps"| PRB
GENSEC -.->|"generates"| ENV

%% =========================
%% Click Events (Component Mapping)
%% =========================
click IB "https://github.com/prash-kr-meena/github-bot-rabbithole/blob/main/issue_bot.py"
click PRB "https://github.com/prash-kr-meena/github-bot-rabbithole/blob/main/pr_bot.py"
click PRLOGIC "https://github.com/prash-kr-meena/github-bot-rabbithole/blob/main/pr_review.py"
click GENSEC "https://github.com/prash-kr-meena/github-bot-rabbithole/blob/main/generate_secret.py"
click TESTS "https://github.com/prash-kr-meena/github-bot-rabbithole/blob/main/run_tests.py"
click T3 "https://github.com/prash-kr-meena/github-bot-rabbithole/blob/main/test_bot.py"
click T4 "https://github.com/prash-kr-meena/github-bot-rabbithole/blob/main/test_pr_bot.py"
click T1 "https://github.com/prash-kr-meena/github-bot-rabbithole/blob/main/test_github_auth.py"
click T2 "https://github.com/prash-kr-meena/github-bot-rabbithole/blob/main/test_ngrok.py"
click DOCS "https://github.com/prash-kr-meena/github-bot-rabbithole/blob/main/README.md"
click REQ "https://github.com/prash-kr-meena/github-bot-rabbithole/blob/main/requirements.txt"

%% Docs click mapping (individual files represented as invisible helpers)
NGDOC["NGROK_SETUP.md"]:::docs_hidden
PRTDOC["PR_TESTING.md"]:::docs_hidden
TSDOC["TESTING.md"]:::docs_hidden
click NGDOC "https://github.com/prash-kr-meena/github-bot-rabbithole/blob/main/NGROK_SETUP.md"
click PRTDOC "https://github.com/prash-kr-meena/github-bot-rabbithole/blob/main/PR_TESTING.md"
click TSDOC "https://github.com/prash-kr-meena/github-bot-rabbithole/blob/main/TESTING.md"
DOCS -.-> NGDOC
DOCS -.-> PRTDOC
DOCS -.-> TSDOC

%% =========================
%% Styles
%% =========================
classDef external fill:#e5e7eb,stroke:#6b7280,color:#111827,stroke-width:1.5px;
classDef service fill:#dbeafe,stroke:#1d4ed8,color:#0f172a,stroke-width:2px;
classDef component fill:#eff6ff,stroke:#3b82f6,color:#0f172a,stroke-width:1.5px;
classDef security fill:#fee2e2,stroke:#ef4444,color:#7f1d1d,stroke-width:2px;
classDef secrets fill:#fecaca,stroke:#b91c1c,color:#7f1d1d,stroke-width:2px;
classDef storage fill:#fff7ed,stroke:#f97316,color:#7c2d12,stroke-width:2px;
classDef lib fill:#ede9fe,stroke:#7c3aed,color:#2e1065,stroke-width:1.5px;
classDef test fill:#fef3c7,stroke:#f59e0b,color:#78350f,stroke-width:1.5px,stroke-dasharray: 6 4;
classDef docs fill:#f3f4f6,stroke:#9ca3af,color:#111827,stroke-width:1.2px;
classDef util fill:#dcfce7,stroke:#16a34a,color:#052e16,stroke-width:1.5px;
classDef docs_hidden fill:#ffffff,stroke:#ffffff,color:#ffffff;
```
