# pyara-singh/pr-agent architecture

> Architecture diagram of the GitHub repository pyara-singh/pr-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pyara-singh/pr-agent
- Repository: https://github.com/pyara-singh/pr-agent

## Overview

PR_Agent combines a human-approved local coding workflow with evidence-driven GitHub pull-request review. The review path accepts webhooks or dashboard requests, dispatches review execution, runs five independent analyses, records evidence and an advisory decision, then awaits human approval; optional GitHub comments and Kafka workers extend that path. The graph includes documented but unsampled coding and dashboard capabilities. Connections for those features are documented at the README level; source excerpts do not show their internal routing.

Main entry points: [`PR_Agent/orchestrator.py`](https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/orchestrator.py) (Review orchestrator), [`PR_Agent/agents/base.py`](https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/agents/base.py) (Agent base), [`PR_Agent/routes/reviews.py`](https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/routes/reviews.py) (Review routes), [`PR_Agent/routes/webhooks.py`](https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/routes/webhooks.py) (GitHub webhook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Dashboard and API"]
  node_dashboard["Next.js dashboard<br/>[page.tsx]"]
  node_coding_page["Coding page<br/>[page.tsx]"]
  node_api["FastAPI application<br/>[api.py]"]
  node_review_routes["Review routes<br/>[reviews.py]"]
  node_webhook_route["GitHub webhook<br/>[webhooks.py]"]
  node_coding_route["Coding routes<br/>[coding.py]"]
end

subgraph group_review["Review execution"]
  node_orchestrator["Review orchestrator<br/>[orchestrator.py]"]
  node_alignment_agent["Strategic alignment<br/>[alignment.py]"]
  node_reproduction_agent["Scientific reproduction<br/>[reproduction.py]"]
  node_security_agent["Security and quality<br/>[security.py]"]
  node_adversarial_agent["Adversarial hardening<br/>[adversarial.py]"]
  node_behavioral_agent["Behavioral compatibility<br/>[behavioral.py]"]
  node_agent_base["Agent base<br/>[base.py]"]
  node_worker["Queue worker<br/>[worker.py]"]
  node_demo_data["Demo reviews<br/>[demo.py]"]
end

subgraph group_evidence["Evidence and persistence"]
  node_github_client["GitHub client<br/>[github.py]"]
  node_sandbox["Test sandbox<br/>[sandbox.py]"]
  node_knowledge["Knowledge store<br/>[knowledge.py]"]
  node_llm["LLM provider<br/>[llm.py]"]
  node_review_store["Review persistence<br/>[repository.py]"]
  node_database[("SQL database<br/>[database.py]")]
  node_models["Review models<br/>[models.py]"]
  node_artifact_store[("Evidence artifacts<br/>[storage.py]")]
  node_event_queue["Review queue<br/>[events.py]"]
end

subgraph group_coding["Guarded coding"]
  node_coding_engine["Coding agent<br/>[coding.py]"]
  node_local_repository["Local Git repository<br/>[coding.py]"]
end

node_developer(("Developer"))
node_github(("GitHub"))
node_llm_service(("LLM providers"))

node_developer -->|"uses"| node_dashboard
node_dashboard -->|"calls API"| node_api
node_github -->|"sends PR event"| node_webhook_route
node_webhook_route -->|"fetches diff"| node_github_client
node_webhook_route -->|"records review"| node_review_store
node_webhook_route -->|"publishes review"| node_event_queue
node_webhook_route -->|"dispatches review"| node_orchestrator
node_dashboard -->|"requests reviews"| node_review_routes
node_review_routes -->|"dispatches review"| node_orchestrator
node_review_routes -->|"reads and decides"| node_review_store
node_review_routes -->|"creates demo"| node_demo_data
node_review_routes -->|"requests approval"| node_developer
node_orchestrator -->|"updates review"| node_review_store
node_orchestrator -->|"runs analysis"| node_alignment_agent
node_orchestrator -->|"runs analysis"| node_reproduction_agent
node_orchestrator -->|"runs analysis"| node_security_agent
node_orchestrator -->|"runs analysis"| node_adversarial_agent
node_orchestrator -->|"runs analysis"| node_behavioral_agent
node_orchestrator -->|"writes report"| node_artifact_store
node_orchestrator -->|"builds provider"| node_llm
node_orchestrator -->|"builds store"| node_knowledge
node_orchestrator -.->|"posts summary"| node_github_client
node_reproduction_agent -->|"downloads commits"| node_github_client
node_reproduction_agent -->|"runs tests"| node_sandbox
node_alignment_agent -.->|"extends"| node_agent_base
node_reproduction_agent -->|"extends"| node_agent_base
node_security_agent -->|"extends"| node_agent_base
node_adversarial_agent -->|"extends"| node_agent_base
node_behavioral_agent -.->|"extends"| node_agent_base
node_agent_base -.->|"requests observations"| node_llm
node_llm -->|"calls provider"| node_llm_service
node_database -->|"creates schema"| node_models
node_review_store -.->|"persists reviews"| node_database
node_worker -->|"consumes reviews"| node_event_queue
node_worker -->|"runs review"| node_orchestrator
node_developer -->|"requests changes"| node_coding_page
node_coding_page -.->|"submits request"| node_coding_route
node_coding_route -.->|"delegates coding"| node_coding_engine
node_coding_engine -->|"drafts and commits"| node_local_repository
node_coding_engine -.->|"generates draft"| node_llm_service
node_coding_page -->|"presents diffs"| node_developer
node_coding_engine -.->|"optionally pushes"| node_github

click node_dashboard "https://github.com/pyara-singh/pr-agent/blob/main/web/app/page.tsx"
click node_coding_page "https://github.com/pyara-singh/pr-agent/blob/main/web/app/coding/page.tsx"
click node_api "https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/api.py"
click node_review_routes "https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/routes/reviews.py"
click node_webhook_route "https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/routes/webhooks.py"
click node_coding_route "https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/routes/coding.py"
click node_coding_engine "https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/coding.py"
click node_local_repository "https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/coding.py"
click node_orchestrator "https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/orchestrator.py"
click node_alignment_agent "https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/agents/alignment.py"
click node_reproduction_agent "https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/agents/reproduction.py"
click node_security_agent "https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/agents/security.py"
click node_adversarial_agent "https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/agents/adversarial.py"
click node_behavioral_agent "https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/agents/behavioral.py"
click node_agent_base "https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/agents/base.py"
click node_github_client "https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/github.py"
click node_sandbox "https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/sandbox.py"
click node_knowledge "https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/knowledge.py"
click node_llm "https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/llm.py"
click node_review_store "https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/repository.py"
click node_database "https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/database.py"
click node_models "https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/models.py"
click node_artifact_store "https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/storage.py"
click node_event_queue "https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/events.py"
click node_worker "https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/worker.py"
click node_demo_data "https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/demo.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_dashboard,node_coding_page,node_api,node_review_routes,node_webhook_route,node_coding_route toneBlue
class node_orchestrator,node_alignment_agent,node_reproduction_agent,node_security_agent,node_adversarial_agent,node_behavioral_agent,node_agent_base,node_worker,node_demo_data toneAmber
class node_github_client,node_sandbox,node_knowledge,node_llm,node_review_store,node_database,node_models,node_artifact_store,node_event_queue toneMint
class node_coding_engine,node_local_repository toneRose
class node_developer,node_github,node_llm_service toneIndigo
```

## Components

### Dashboard and API

- [Next.js dashboard](https://github.com/pyara-singh/pr-agent/blob/main/web/app/page.tsx): `web/app/page.tsx`
- [Coding page](https://github.com/pyara-singh/pr-agent/blob/main/web/app/coding/page.tsx): `web/app/coding/page.tsx`
- [FastAPI application](https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/api.py): `PR_Agent/api.py`
- [Review routes](https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/routes/reviews.py): `PR_Agent/routes/reviews.py`
- [GitHub webhook](https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/routes/webhooks.py): `PR_Agent/routes/webhooks.py`
- [Coding routes](https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/routes/coding.py): `PR_Agent/routes/coding.py`

### Review execution

- [Review orchestrator](https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/orchestrator.py): `PR_Agent/orchestrator.py`
- [Strategic alignment](https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/agents/alignment.py): `PR_Agent/agents/alignment.py`
- [Scientific reproduction](https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/agents/reproduction.py): `PR_Agent/agents/reproduction.py`
- [Security and quality](https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/agents/security.py): `PR_Agent/agents/security.py`
- [Adversarial hardening](https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/agents/adversarial.py): `PR_Agent/agents/adversarial.py`
- [Behavioral compatibility](https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/agents/behavioral.py): `PR_Agent/agents/behavioral.py`
- [Agent base](https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/agents/base.py): `PR_Agent/agents/base.py`
- [Queue worker](https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/worker.py): `PR_Agent/worker.py`
- [Demo reviews](https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/demo.py): `PR_Agent/demo.py`

### Evidence and persistence

- [GitHub client](https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/github.py): `PR_Agent/github.py`
- [Test sandbox](https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/sandbox.py): `PR_Agent/sandbox.py`
- [Knowledge store](https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/knowledge.py): `PR_Agent/knowledge.py`
- [LLM provider](https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/llm.py): `PR_Agent/llm.py`
- [Review persistence](https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/repository.py): `PR_Agent/repository.py`
- [SQL database](https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/database.py): `PR_Agent/database.py`
- [Review models](https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/models.py): `PR_Agent/models.py`
- [Evidence artifacts](https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/storage.py): `PR_Agent/storage.py`
- [Review queue](https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/events.py): `PR_Agent/events.py`

### Guarded coding

- [Coding agent](https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/coding.py): `PR_Agent/coding.py`
- [Local Git repository](https://github.com/pyara-singh/pr-agent/blob/main/PR_Agent/coding.py): `PR_Agent/coding.py`

### Other components

- **Developer**
- **GitHub**
- **LLM providers**

## Connections

- Developer → Next.js dashboard: uses (evidence: `README.md`)
- Next.js dashboard → FastAPI application: calls API (evidence: `README.md`)
- GitHub → GitHub webhook: sends PR event (evidence: `README.md`)
- GitHub webhook → GitHub client: fetches diff (evidence: `PR_Agent/routes/webhooks.py`)
- GitHub webhook → Review persistence: records review (evidence: `PR_Agent/routes/webhooks.py`)
- GitHub webhook → Review queue: publishes review (evidence: `PR_Agent/routes/webhooks.py`)
- GitHub webhook → Review orchestrator: dispatches review (evidence: `PR_Agent/routes/webhooks.py`)
- Next.js dashboard → Review routes: requests reviews (evidence: `README.md`)
- Review routes → Review orchestrator: dispatches review (evidence: `PR_Agent/routes/reviews.py`)
- Review routes → Review persistence: reads and decides (evidence: `PR_Agent/routes/reviews.py`)
- Review routes → Demo reviews: creates demo (evidence: `PR_Agent/routes/reviews.py`)
- Review routes → Developer: requests approval (evidence: `README.md`)
- Review orchestrator → Review persistence: updates review (evidence: `PR_Agent/orchestrator.py`)
- Review orchestrator → Strategic alignment: runs analysis (evidence: `PR_Agent/orchestrator.py`)
- Review orchestrator → Scientific reproduction: runs analysis (evidence: `PR_Agent/orchestrator.py`)
- Review orchestrator → Security and quality: runs analysis (evidence: `PR_Agent/orchestrator.py`)
- Review orchestrator → Adversarial hardening: runs analysis (evidence: `PR_Agent/orchestrator.py`)
- Review orchestrator → Behavioral compatibility: runs analysis (evidence: `PR_Agent/orchestrator.py`)
- Review orchestrator → Evidence artifacts: writes report (evidence: `PR_Agent/orchestrator.py`)
- Review orchestrator → LLM provider: builds provider (evidence: `PR_Agent/orchestrator.py`)
- Review orchestrator → Knowledge store: builds store (evidence: `PR_Agent/orchestrator.py`)
- Review orchestrator → GitHub client: posts summary (evidence: `PR_Agent/orchestrator.py`)
- Scientific reproduction → GitHub client: downloads commits (evidence: `PR_Agent/agents/reproduction.py`)
- Scientific reproduction → Test sandbox: runs tests (evidence: `PR_Agent/agents/reproduction.py`)
- Strategic alignment → Agent base: extends
- Scientific reproduction → Agent base: extends (evidence: `PR_Agent/agents/reproduction.py`)
- Security and quality → Agent base: extends (evidence: `PR_Agent/agents/security.py`)
- Adversarial hardening → Agent base: extends (evidence: `PR_Agent/agents/adversarial.py`)
- Behavioral compatibility → Agent base: extends
- Agent base → LLM provider: requests observations
- LLM provider → LLM providers: calls provider (evidence: `README.md`)
- SQL database → Review models: creates schema (evidence: `PR_Agent/database.py`)
- Review persistence → SQL database: persists reviews
- Queue worker → Review queue: consumes reviews (evidence: `PR_Agent/worker.py`)
- Queue worker → Review orchestrator: runs review (evidence: `PR_Agent/worker.py`)
- Developer → Coding page: requests changes (evidence: `README.md`)
- Coding page → Coding routes: submits request
- Coding routes → Coding agent: delegates coding
- Coding agent → Local Git repository: drafts and commits (evidence: `README.md`)
- Coding agent → LLM providers: generates draft (evidence: `README.md`)
- Coding page → Developer: presents diffs (evidence: `README.md`)
- Coding agent → GitHub: optionally pushes (evidence: `README.md`)