# cvsgireesh/reviewloop architecture

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

- Interactive diagram: https://gitdiagram.com/cvsgireesh/reviewloop
- Repository: https://github.com/cvsgireesh/reviewloop

## Overview

ReviewLoop is a self-hosted GitHub pull-request agent: it gathers review feedback, prepares and checks a candidate, then asks its owner in Telegram before pushing. The README documents revisions, approval invalidation when a PR changes, persistent job and preference state, and status/evidence commands. The controller excerpt supports the job, notification and publication ownership shown here; the README supplies major capabilities whose wiring was not sampled, so those links are limited to documented behavior.

Main entry points: [`src/controller.ts`](https://github.com/cvsgireesh/reviewloop/blob/main/src/controller.ts) (Workflow controller), [`src/cli.ts`](https://github.com/cvsgireesh/reviewloop/blob/main/src/cli.ts) (CLI commands), [`src/harness.ts`](https://github.com/cvsgireesh/reviewloop/blob/main/src/harness.ts) (Agent harness), [`src/github.ts`](https://github.com/cvsgireesh/reviewloop/blob/main/src/github.ts) (PR integration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Service and control"]
  node_cli["CLI commands<br/>[cli.ts]"]
  node_config["Configuration<br/>[config.ts]"]
end

subgraph group_workflow["PR workflow"]
  node_controller["Workflow controller<br/>[controller.ts]"]
  node_github["PR integration<br/>[github.ts]"]
  node_feedback["Review feedback<br/>[skills.ts]"]
  node_telegram["Telegram integration<br/>[telegram.ts]"]
  node_evidence["Check evidence<br/>[controller.ts]"]
end

subgraph group_agent["Agent execution"]
  node_harness["Agent harness<br/>[harness.ts]"]
  node_model["Model provider<br/>[model.ts]"]
  node_tools["Workspace tools<br/>[workspace-tools.ts]"]
  node_workspace["Candidate workspace<br/>[git.ts]"]
  node_patch["Patch application<br/>[codex-patch.ts]"]
  node_sandbox["Isolated checks<br/>[sandbox.ts]"]
end

subgraph group_state["State and memory"]
  node_store[("Job and preferences<br/>[store.ts]")]
  node_session["Session checkpoints<br/>[session.ts]"]
end

node_owner(("PR owner"))
node_github_service["GitHub"]
node_bedrock["AWS Bedrock"]
node_telegram_service["Telegram"]

node_owner -->|"runs commands"| node_cli
node_cli -->|"loads settings"| node_config
node_cli -->|"starts loop"| node_controller
node_controller -->|"fetches PRs"| node_github
node_github -->|"reads and pushes"| node_github_service
node_controller -->|"runs job"| node_harness
node_harness -->|"requests completion"| node_model
node_model -->|"sends prompts"| node_bedrock
node_harness -->|"dispatches tools"| node_tools
node_tools -->|"reads and edits"| node_workspace
node_harness -->|"applies patches"| node_patch
node_controller -->|"runs checks"| node_sandbox
node_controller -->|"writes results"| node_evidence
node_controller -->|"queues updates"| node_telegram
node_telegram -->|"sends messages"| node_telegram_service
node_owner -->|"replies or approves"| node_telegram_service
node_telegram_service -->|"delivers decisions"| node_controller
node_controller -->|"saves jobs and events"| node_store
node_controller -->|"checkpoints rounds"| node_session
node_cli -->|"queries state"| node_store
node_cli -->|"shows status and evidence"| node_owner
node_controller -->|"rechecks before publish"| node_github
node_controller -->|"publishes approved commit"| node_github_service
node_harness -.->|"uses review guidance"| node_feedback

click node_cli "https://github.com/cvsgireesh/reviewloop/blob/main/src/cli.ts"
click node_controller "https://github.com/cvsgireesh/reviewloop/blob/main/src/controller.ts"
click node_config "https://github.com/cvsgireesh/reviewloop/blob/main/src/config.ts"
click node_github "https://github.com/cvsgireesh/reviewloop/blob/main/src/github.ts"
click node_feedback "https://github.com/cvsgireesh/reviewloop/blob/main/src/skills.ts"
click node_harness "https://github.com/cvsgireesh/reviewloop/blob/main/src/harness.ts"
click node_model "https://github.com/cvsgireesh/reviewloop/blob/main/src/model.ts"
click node_tools "https://github.com/cvsgireesh/reviewloop/blob/main/src/workspace-tools.ts"
click node_workspace "https://github.com/cvsgireesh/reviewloop/blob/main/src/git.ts"
click node_patch "https://github.com/cvsgireesh/reviewloop/blob/main/src/codex-patch.ts"
click node_sandbox "https://github.com/cvsgireesh/reviewloop/blob/main/src/sandbox.ts"
click node_telegram "https://github.com/cvsgireesh/reviewloop/blob/main/src/telegram.ts"
click node_store "https://github.com/cvsgireesh/reviewloop/blob/main/src/store.ts"
click node_session "https://github.com/cvsgireesh/reviewloop/blob/main/src/session.ts"
click node_evidence "https://github.com/cvsgireesh/reviewloop/blob/main/src/controller.ts"

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_cli,node_config toneBlue
class node_controller,node_github,node_feedback,node_telegram,node_evidence toneAmber
class node_harness,node_model,node_tools,node_workspace,node_patch,node_sandbox toneMint
class node_store,node_session toneRose
class node_owner,node_github_service,node_bedrock,node_telegram_service toneIndigo
```

## Components

### Service and control

- [CLI commands](https://github.com/cvsgireesh/reviewloop/blob/main/src/cli.ts): `src/cli.ts`
- [Configuration](https://github.com/cvsgireesh/reviewloop/blob/main/src/config.ts): `src/config.ts`

### PR workflow

- [Workflow controller](https://github.com/cvsgireesh/reviewloop/blob/main/src/controller.ts): `src/controller.ts`
- [PR integration](https://github.com/cvsgireesh/reviewloop/blob/main/src/github.ts): `src/github.ts`
- [Review feedback](https://github.com/cvsgireesh/reviewloop/blob/main/src/skills.ts): `src/skills.ts`
- [Telegram integration](https://github.com/cvsgireesh/reviewloop/blob/main/src/telegram.ts): `src/telegram.ts`
- [Check evidence](https://github.com/cvsgireesh/reviewloop/blob/main/src/controller.ts): `src/controller.ts`

### Agent execution

- [Agent harness](https://github.com/cvsgireesh/reviewloop/blob/main/src/harness.ts): `src/harness.ts`
- [Model provider](https://github.com/cvsgireesh/reviewloop/blob/main/src/model.ts): `src/model.ts`
- [Workspace tools](https://github.com/cvsgireesh/reviewloop/blob/main/src/workspace-tools.ts): `src/workspace-tools.ts`
- [Candidate workspace](https://github.com/cvsgireesh/reviewloop/blob/main/src/git.ts): `src/git.ts`
- [Patch application](https://github.com/cvsgireesh/reviewloop/blob/main/src/codex-patch.ts): `src/codex-patch.ts`
- [Isolated checks](https://github.com/cvsgireesh/reviewloop/blob/main/src/sandbox.ts): `src/sandbox.ts`

### State and memory

- [Job and preferences](https://github.com/cvsgireesh/reviewloop/blob/main/src/store.ts): `src/store.ts`
- [Session checkpoints](https://github.com/cvsgireesh/reviewloop/blob/main/src/session.ts): `src/session.ts`

### Other components

- **PR owner**
- **GitHub**
- **AWS Bedrock**
- **Telegram**

## Connections

- PR owner → CLI commands: runs commands
- CLI commands → Configuration: loads settings
- CLI commands → Workflow controller: starts loop
- Workflow controller → PR integration: fetches PRs
- PR integration → GitHub: reads and pushes
- Workflow controller → Agent harness: runs job
- Agent harness → Model provider: requests completion
- Model provider → AWS Bedrock: sends prompts
- Agent harness → Workspace tools: dispatches tools
- Workspace tools → Candidate workspace: reads and edits
- Agent harness → Patch application: applies patches
- Workflow controller → Isolated checks: runs checks
- Workflow controller → Check evidence: writes results
- Workflow controller → Telegram integration: queues updates
- Telegram integration → Telegram: sends messages
- PR owner → Telegram: replies or approves
- Telegram → Workflow controller: delivers decisions
- Workflow controller → Job and preferences: saves jobs and events
- Workflow controller → Session checkpoints: checkpoints rounds
- CLI commands → Job and preferences: queries state
- CLI commands → PR owner: shows status and evidence
- Workflow controller → PR integration: rechecks before publish
- Workflow controller → GitHub: publishes approved commit
- Agent harness → Review feedback: uses review guidance