# kimjune01/sweep architecture

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

- Interactive diagram: https://gitdiagram.com/kimjune01/sweep
- Repository: https://github.com/kimjune01/sweep

## Overview

Sweep is an autonomous, paced GitHub contribution pipeline for finding acknowledged bugs, producing and reviewing fixes, and submitting pull requests; it also offers maintainers an advisory quality gate. The principal flow is discovery, issue screening, investigation and fix, QA and adversarial review, attestation, submission, and paced delivery, with separate engagement and operator branches. Temporal supervises unattended actors; CLI commands provide operator views and controls. The graph follows the README and supplied excerpts; several subsystem links use documented behavior because their source was not sampled.

Main entry points: [`sweep/workflows/qa_actor.py`](https://github.com/kimjune01/sweep/blob/main/sweep/workflows/qa_actor.py) (QA actor), [`sweep/worker.py`](https://github.com/kimjune01/sweep/blob/main/sweep/worker.py) (Worker), [`sweep/activities/sift.py`](https://github.com/kimjune01/sweep/blob/main/sweep/activities/sift.py) (Issue discovery), [`sweep/activities/submit.py`](https://github.com/kimjune01/sweep/blob/main/sweep/activities/submit.py) (PR submission)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pipeline["Contribution pipeline"]
  node_discovery["Issue discovery<br/>[sift.py]"]
  node_investigation["Investigation"]
  node_fix["Fix implementation<br/>[skill_runner.py]"]
  node_qa["QA actor<br/>[qa_actor.py]"]
  node_submission["PR submission<br/>[submit.py]"]
  node_drip["Paced delivery"]
  node_engagement["PR engagement<br/>[reinvestigate.py]"]
end

subgraph group_supervision["Temporal supervision"]
  node_worker["Worker<br/>[worker.py]"]
  node_temporal["Temporal"]
  node_prstate["PR classifier<br/>[pr_state.py]"]
end

subgraph group_quality["Quality and evidence"]
  node_qaactivities["Test and review<br/>[qa.py]"]
  node_attestation["Attestation gates"]
  node_verifier["Push verifier<br/>[verifier.py]"]
  node_qualityaction["Advisory quality gate<br/>[qa.py]"]
end

subgraph group_operations["Operator surfaces"]
  node_cockpit["Cockpit and lanes<br/>[cockpit.py]"]
  node_retro["Retro pager<br/>[retro.py]"]
  node_tui["Flag action bar<br/>[main.go]"]
end

subgraph group_state["State and observability"]
  node_inbox[("Actor inboxes<br/>[inbox_state.py]")]
  node_receipts[("Attestation records<br/>[attestations.py]")]
  node_observe[("Events and metrics<br/>[observe.py]")]
end

node_contributor(("Contributor"))
node_maintainer(("Maintainer"))
node_operator(("Operator"))
node_github["GitHub"]

node_contributor -->|"acknowledges bugs"| node_github
node_worker -->|"connects to"| node_temporal
node_temporal -->|"dispatches tasks"| node_worker
node_worker -->|"registers activity"| node_discovery
node_worker -->|"registers workflow"| node_qa
node_discovery -->|"searches issues"| node_github
node_discovery -->|"routes candidates"| node_investigation
node_investigation -->|"prepares work"| node_fix
node_fix -->|"queues fix"| node_qa
node_qa -->|"runs checks"| node_qaactivities
node_qaactivities -->|"records evidence"| node_attestation
node_qa -->|"advances passing work"| node_submission
node_submission -->|"checks receipts"| node_verifier
node_submission -->|"opens pull request"| node_github
node_drip -->|"paces delivery"| node_github
node_prstate -->|"routes PR work"| node_inbox
node_prstate -->|"classifies pull requests"| node_github
node_engagement -->|"updates existing PR"| node_github
node_qaactivities -->|"caches LLM calls"| node_receipts
node_attestation -->|"writes hashed receipts"| node_receipts
node_qa -->|"emits outcomes"| node_observe
node_operator -->|"inspects status"| node_cockpit
node_cockpit -->|"reads queues"| node_inbox
node_operator -->|"manages retros"| node_retro
node_retro -->|"reads events"| node_observe
node_operator -->|"sets flags"| node_tui
node_tui -.->|"influences actors"| node_temporal
node_maintainer -.->|"runs advisory checks"| node_qualityaction
node_qualityaction -.->|"checks proposed changes"| node_github

click node_worker "https://github.com/kimjune01/sweep/blob/main/sweep/worker.py"
click node_discovery "https://github.com/kimjune01/sweep/blob/main/sweep/activities/sift.py"
click node_investigation "https://github.com/kimjune01/sweep/blob/main/sweep/activities/investigate_prep.py"
click node_fix "https://github.com/kimjune01/sweep/blob/main/sweep/activities/skill_runner.py"
click node_qa "https://github.com/kimjune01/sweep/blob/main/sweep/workflows/qa_actor.py"
click node_qaactivities "https://github.com/kimjune01/sweep/blob/main/sweep/activities/qa.py"
click node_attestation "https://github.com/kimjune01/sweep/blob/main/sweep/attestation_writer.py"
click node_verifier "https://github.com/kimjune01/sweep/blob/main/sweep/_gate/verifier.py"
click node_submission "https://github.com/kimjune01/sweep/blob/main/sweep/activities/submit.py"
click node_engagement "https://github.com/kimjune01/sweep/blob/main/sweep/activities/reinvestigate.py"
click node_prstate "https://github.com/kimjune01/sweep/blob/main/sweep/activities/pr_state.py"
click node_inbox "https://github.com/kimjune01/sweep/blob/main/sweep/inbox_state.py"
click node_receipts "https://github.com/kimjune01/sweep/blob/main/sweep/attestations.py"
click node_observe "https://github.com/kimjune01/sweep/blob/main/sweep/observe.py"
click node_cockpit "https://github.com/kimjune01/sweep/blob/main/sweep/cli/cockpit.py"
click node_retro "https://github.com/kimjune01/sweep/blob/main/sweep/cli/retro.py"
click node_tui "https://github.com/kimjune01/sweep/blob/main/tui/main.go"
click node_qualityaction "https://github.com/kimjune01/sweep/blob/main/sweep/activities/qa.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_discovery,node_investigation,node_fix,node_qa,node_submission,node_drip,node_engagement toneBlue
class node_worker,node_temporal,node_prstate toneAmber
class node_qaactivities,node_attestation,node_verifier,node_qualityaction toneMint
class node_cockpit,node_retro,node_tui toneRose
class node_inbox,node_receipts,node_observe,node_contributor,node_maintainer,node_operator,node_github toneIndigo
```

## Components

### Contribution pipeline

- [Issue discovery](https://github.com/kimjune01/sweep/blob/main/sweep/activities/sift.py): `sweep/activities/sift.py`
- [Investigation](https://github.com/kimjune01/sweep/blob/main/sweep/activities/investigate_prep.py): `sweep/activities/investigate_prep.py`
- [Fix implementation](https://github.com/kimjune01/sweep/blob/main/sweep/activities/skill_runner.py): `sweep/activities/skill_runner.py`
- [QA actor](https://github.com/kimjune01/sweep/blob/main/sweep/workflows/qa_actor.py): `sweep/workflows/qa_actor.py`
- [PR submission](https://github.com/kimjune01/sweep/blob/main/sweep/activities/submit.py): `sweep/activities/submit.py`
- **Paced delivery**
- [PR engagement](https://github.com/kimjune01/sweep/blob/main/sweep/activities/reinvestigate.py): `sweep/activities/reinvestigate.py`

### Temporal supervision

- [Worker](https://github.com/kimjune01/sweep/blob/main/sweep/worker.py): `sweep/worker.py`
- **Temporal**
- [PR classifier](https://github.com/kimjune01/sweep/blob/main/sweep/activities/pr_state.py): `sweep/activities/pr_state.py`

### Quality and evidence

- [Test and review](https://github.com/kimjune01/sweep/blob/main/sweep/activities/qa.py): `sweep/activities/qa.py`
- [Attestation gates](https://github.com/kimjune01/sweep/blob/main/sweep/attestation_writer.py): `sweep/attestation_writer.py`
- [Push verifier](https://github.com/kimjune01/sweep/blob/main/sweep/_gate/verifier.py): `sweep/_gate/verifier.py`
- [Advisory quality gate](https://github.com/kimjune01/sweep/blob/main/sweep/activities/qa.py): `sweep/activities/qa.py`

### Operator surfaces

- [Cockpit and lanes](https://github.com/kimjune01/sweep/blob/main/sweep/cli/cockpit.py): `sweep/cli/cockpit.py`
- [Retro pager](https://github.com/kimjune01/sweep/blob/main/sweep/cli/retro.py): `sweep/cli/retro.py`
- [Flag action bar](https://github.com/kimjune01/sweep/blob/main/tui/main.go): `tui/main.go`

### State and observability

- [Actor inboxes](https://github.com/kimjune01/sweep/blob/main/sweep/inbox_state.py): `sweep/inbox_state.py`
- [Attestation records](https://github.com/kimjune01/sweep/blob/main/sweep/attestations.py): `sweep/attestations.py`
- [Events and metrics](https://github.com/kimjune01/sweep/blob/main/sweep/observe.py): `sweep/observe.py`

### Other components

- **Contributor**
- **Maintainer**
- **Operator**
- **GitHub**

## Connections

- Contributor → GitHub: acknowledges bugs
- Worker → Temporal: connects to
- Temporal → Worker: dispatches tasks
- Worker → Issue discovery: registers activity
- Worker → QA actor: registers workflow
- Issue discovery → GitHub: searches issues
- Issue discovery → Investigation: routes candidates
- Investigation → Fix implementation: prepares work
- Fix implementation → QA actor: queues fix
- QA actor → Test and review: runs checks
- Test and review → Attestation gates: records evidence
- QA actor → PR submission: advances passing work
- PR submission → Push verifier: checks receipts
- PR submission → GitHub: opens pull request
- Paced delivery → GitHub: paces delivery
- PR classifier → Actor inboxes: routes PR work
- PR classifier → GitHub: classifies pull requests
- PR engagement → GitHub: updates existing PR
- Test and review → Attestation records: caches LLM calls
- Attestation gates → Attestation records: writes hashed receipts
- QA actor → Events and metrics: emits outcomes
- Operator → Cockpit and lanes: inspects status
- Cockpit and lanes → Actor inboxes: reads queues
- Operator → Retro pager: manages retros
- Retro pager → Events and metrics: reads events
- Operator → Flag action bar: sets flags
- Flag action bar → Temporal: influences actors
- Maintainer → Advisory quality gate: runs advisory checks
- Advisory quality gate → GitHub: checks proposed changes