# vimalyad/oss-pipeline-stale architecture

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

- Interactive diagram: https://gitdiagram.com/vimalyad/oss-pipeline-stale
- Repository: https://github.com/vimalyad/oss-pipeline-stale

## Overview

oss-pipeline automates open-source contributions, from issue discovery through proposal, human approval, implementation, pull-request submission, and ongoing CI/review follow-up. The Go CLI is the scheduled runtime; the README describes the Python implementation as an unscheduled rollback and parity counterpart. The graph preserves the distinct domain stages and safety boundaries. Some implementation files were not sampled, so their connections are shown only where the README or source index supports them; unsampled details are not inferred.

Main entry points: [`internal/implement/implement.go`](https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/implement/implement.go) (Implementation stage), [`src/oss_pipeline/submit.py`](https://github.com/vimalyad/oss-pipeline-stale/blob/main/src/oss_pipeline/submit.py) (Python PR submission), [`cmd/pipeline/main.go`](https://github.com/vimalyad/oss-pipeline-stale/blob/main/cmd/pipeline/main.go) (Pipeline CLI), [`internal/store/store.go`](https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/store/store.go) (JSON candidate store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Discovery and triage"]
  node_pipeline_cli["Pipeline CLI<br/>[main.go]"]
  node_discovery["Issue discovery<br/>[discover.go]"]
  node_harvest["Issue harvesting<br/>[harvest.go]"]
  node_brief["Issue brief<br/>[brief.go]"]
  node_repo_facts["Repository facts<br/>[repofacts.go]"]
end

subgraph group_decisions["Candidate decisions"]
  node_candidate_model["Candidate state<br/>[candidate.go]"]
  node_candidate_store[("JSON candidate store<br/>[store.go]")]
  node_scoring["Candidate scoring<br/>[score.go]"]
  node_proposal["Proposal report<br/>[propose.go]"]
  node_human_gate["Human approval gate<br/>[gate.go]"]
  node_machine_gate["Machine capability gate<br/>[machine.go]"]
end

subgraph group_implementation["Implementation and verification"]
  node_implement_stage["Implementation stage<br/>[implement.go]"]
  node_recipe["Build recipe derivation<br/>[derive.go]"]
  node_sandbox["Isolated execution<br/>[sandbox.go]"]
  node_reproduction["Failure reproduction<br/>[repro.go]"]
  node_llm["Model CLI<br/>[llm.go]"]
end

subgraph group_publication["Safe publication"]
  node_identity["Git identity boundary<br/>[identity.go]"]
  node_submission["PR submission<br/>[submit.go]"]
  node_guard["Publication guards<br/>[guard.go]"]
  node_watch["CI and PR watch<br/>[poll.go]"]
  node_replies["Maintainer replies<br/>[replies.go]"]
end

subgraph group_python["Python rollback"]
  node_python_cli["Python CLI<br/>[cli.py]"]
  node_python_models["Python candidate models<br/>[models.py]"]
  node_python_submit["Python PR submission<br/>[submit.py]"]
  node_python_identity["Python identity<br/>[identity.py]"]
  node_python_repo["Python repository access<br/>[repo.py]"]
  node_python_ghapi["Python GitHub API<br/>[ghapi.py]"]
  node_python_audit["Python audit<br/>[audit.py]"]
end

node_operator(("Operator"))

node_operator -->|"runs stages"| node_pipeline_cli
node_pipeline_cli -->|"starts discovery"| node_discovery
node_pipeline_cli -->|"records decisions"| node_human_gate
node_pipeline_cli -->|"starts implementation"| node_implement_stage
node_pipeline_cli -->|"starts watch"| node_watch
node_discovery -.->|"finds issue context"| node_harvest
node_harvest -.->|"builds brief"| node_brief
node_repo_facts -.->|"informs scoring"| node_scoring
node_discovery -.->|"records candidates"| node_candidate_store
node_scoring -.->|"ranks candidates"| node_proposal
node_proposal -.->|"reads candidates"| node_candidate_store
node_operator -->|"approves proposal"| node_human_gate
node_human_gate -->|"persists decision"| node_candidate_store
node_human_gate -->|"transitions state"| node_candidate_model
node_machine_gate -->|"rechecks candidates"| node_candidate_store
node_implement_stage -.->|"derives verification"| node_recipe
node_implement_stage -.->|"requests patch"| node_llm
node_implement_stage -.->|"runs verification"| node_sandbox
node_implement_stage -.->|"reproduces failure"| node_reproduction
node_implement_stage -.->|"submits change"| node_submission
node_submission -.->|"asserts identity"| node_identity
node_submission -->|"screens shipment"| node_guard
node_submission -.->|"drafts PR body"| node_llm
node_watch -.->|"syncs PR state"| node_candidate_store
node_operator -->|"manages replies"| node_replies
node_python_cli -.->|"runs submission"| node_python_submit
node_python_submit -->|"asserts identity"| node_python_identity
node_python_submit -->|"uses repository access"| node_python_repo
node_python_submit -->|"uses GitHub API"| node_python_ghapi
node_python_submit -->|"uses candidate model"| node_python_models
node_python_submit -->|"records audit"| node_python_audit

click node_pipeline_cli "https://github.com/vimalyad/oss-pipeline-stale/blob/main/cmd/pipeline/main.go"
click node_discovery "https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/discover/discover.go"
click node_harvest "https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/harvest/harvest.go"
click node_brief "https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/brief/brief.go"
click node_repo_facts "https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/repofacts/repofacts.go"
click node_candidate_model "https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/model/candidate.go"
click node_candidate_store "https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/store/store.go"
click node_scoring "https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/score/score.go"
click node_proposal "https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/propose/propose.go"
click node_human_gate "https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/gate/gate.go"
click node_machine_gate "https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/machine/machine.go"
click node_implement_stage "https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/implement/implement.go"
click node_recipe "https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/recipe/derive.go"
click node_sandbox "https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/sandbox/sandbox.go"
click node_reproduction "https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/repro/repro.go"
click node_llm "https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/llm/llm.go"
click node_identity "https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/identity/identity.go"
click node_submission "https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/submit/submit.go"
click node_guard "https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/guard/guard.go"
click node_watch "https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/watch/poll.go"
click node_replies "https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/replies/replies.go"
click node_python_cli "https://github.com/vimalyad/oss-pipeline-stale/blob/main/src/oss_pipeline/cli.py"
click node_python_models "https://github.com/vimalyad/oss-pipeline-stale/blob/main/src/oss_pipeline/models.py"
click node_python_submit "https://github.com/vimalyad/oss-pipeline-stale/blob/main/src/oss_pipeline/submit.py"
click node_python_identity "https://github.com/vimalyad/oss-pipeline-stale/blob/main/src/oss_pipeline/identity.py"
click node_python_repo "https://github.com/vimalyad/oss-pipeline-stale/blob/main/src/oss_pipeline/repo.py"
click node_python_ghapi "https://github.com/vimalyad/oss-pipeline-stale/blob/main/src/oss_pipeline/ghapi.py"
click node_python_audit "https://github.com/vimalyad/oss-pipeline-stale/blob/main/src/oss_pipeline/audit.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_pipeline_cli,node_discovery,node_harvest,node_brief,node_repo_facts toneBlue
class node_candidate_model,node_candidate_store,node_scoring,node_proposal,node_human_gate,node_machine_gate toneAmber
class node_implement_stage,node_recipe,node_sandbox,node_reproduction,node_llm toneMint
class node_identity,node_submission,node_guard,node_watch,node_replies toneRose
class node_python_cli,node_python_models,node_python_submit,node_python_identity,node_python_repo,node_python_ghapi,node_python_audit,node_operator toneIndigo
```

## Components

### Discovery and triage

- [Pipeline CLI](https://github.com/vimalyad/oss-pipeline-stale/blob/main/cmd/pipeline/main.go): `cmd/pipeline/main.go`
- [Issue discovery](https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/discover/discover.go): `internal/discover/discover.go`
- [Issue harvesting](https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/harvest/harvest.go): `internal/harvest/harvest.go`
- [Issue brief](https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/brief/brief.go): `internal/brief/brief.go`
- [Repository facts](https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/repofacts/repofacts.go): `internal/repofacts/repofacts.go`

### Candidate decisions

- [Candidate state](https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/model/candidate.go): `internal/model/candidate.go`
- [JSON candidate store](https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/store/store.go): `internal/store/store.go`
- [Candidate scoring](https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/score/score.go): `internal/score/score.go`
- [Proposal report](https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/propose/propose.go): `internal/propose/propose.go`
- [Human approval gate](https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/gate/gate.go): `internal/gate/gate.go`
- [Machine capability gate](https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/machine/machine.go): `internal/machine/machine.go`

### Implementation and verification

- [Implementation stage](https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/implement/implement.go): `internal/implement/implement.go`
- [Build recipe derivation](https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/recipe/derive.go): `internal/recipe/derive.go`
- [Isolated execution](https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/sandbox/sandbox.go): `internal/sandbox/sandbox.go`
- [Failure reproduction](https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/repro/repro.go): `internal/repro/repro.go`
- [Model CLI](https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/llm/llm.go): `internal/llm/llm.go`

### Safe publication

- [Git identity boundary](https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/identity/identity.go): `internal/identity/identity.go`
- [PR submission](https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/submit/submit.go): `internal/submit/submit.go`
- [Publication guards](https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/guard/guard.go): `internal/guard/guard.go`
- [CI and PR watch](https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/watch/poll.go): `internal/watch/poll.go`
- [Maintainer replies](https://github.com/vimalyad/oss-pipeline-stale/blob/main/internal/replies/replies.go): `internal/replies/replies.go`

### Python rollback

- [Python CLI](https://github.com/vimalyad/oss-pipeline-stale/blob/main/src/oss_pipeline/cli.py): `src/oss_pipeline/cli.py`
- [Python candidate models](https://github.com/vimalyad/oss-pipeline-stale/blob/main/src/oss_pipeline/models.py): `src/oss_pipeline/models.py`
- [Python PR submission](https://github.com/vimalyad/oss-pipeline-stale/blob/main/src/oss_pipeline/submit.py): `src/oss_pipeline/submit.py`
- [Python identity](https://github.com/vimalyad/oss-pipeline-stale/blob/main/src/oss_pipeline/identity.py): `src/oss_pipeline/identity.py`
- [Python repository access](https://github.com/vimalyad/oss-pipeline-stale/blob/main/src/oss_pipeline/repo.py): `src/oss_pipeline/repo.py`
- [Python GitHub API](https://github.com/vimalyad/oss-pipeline-stale/blob/main/src/oss_pipeline/ghapi.py): `src/oss_pipeline/ghapi.py`
- [Python audit](https://github.com/vimalyad/oss-pipeline-stale/blob/main/src/oss_pipeline/audit.py): `src/oss_pipeline/audit.py`

### Other components

- **Operator**

## Connections

- Operator → Pipeline CLI: runs stages (evidence: `README.md`)
- Pipeline CLI → Issue discovery: starts discovery (evidence: `README.md`)
- Pipeline CLI → Human approval gate: records decisions (evidence: `README.md`)
- Pipeline CLI → Implementation stage: starts implementation (evidence: `README.md`)
- Pipeline CLI → CI and PR watch: starts watch (evidence: `README.md`)
- Issue discovery → Issue harvesting: finds issue context
- Issue harvesting → Issue brief: builds brief (evidence: `README.md`)
- Repository facts → Candidate scoring: informs scoring (evidence: `internal/score/score.go`)
- Issue discovery → JSON candidate store: records candidates (evidence: `README.md`)
- Candidate scoring → Proposal report: ranks candidates (evidence: `README.md`)
- Proposal report → JSON candidate store: reads candidates (evidence: `README.md`)
- Operator → Human approval gate: approves proposal (evidence: `README.md`)
- Human approval gate → JSON candidate store: persists decision (evidence: `internal/gate/gate.go`)
- Human approval gate → Candidate state: transitions state (evidence: `internal/gate/gate.go`)
- Machine capability gate → JSON candidate store: rechecks candidates
- Implementation stage → Build recipe derivation: derives verification
- Implementation stage → Model CLI: requests patch (evidence: `internal/llm/llm.go`)
- Implementation stage → Isolated execution: runs verification (evidence: `internal/sandbox/sandbox.go`)
- Implementation stage → Failure reproduction: reproduces failure (evidence: `internal/repro/repro.go`)
- Implementation stage → PR submission: submits change (evidence: `README.md`)
- PR submission → Git identity boundary: asserts identity (evidence: `internal/submit/submit.go`)
- PR submission → Publication guards: screens shipment (evidence: `internal/submit/submit.go`)
- PR submission → Model CLI: drafts PR body (evidence: `internal/submit/submit.go`)
- CI and PR watch → JSON candidate store: syncs PR state (evidence: `README.md`)
- Operator → Maintainer replies: manages replies (evidence: `README.md`)
- Python CLI → Python PR submission: runs submission
- Python PR submission → Python identity: asserts identity (evidence: `src/oss_pipeline/submit.py`)
- Python PR submission → Python repository access: uses repository access (evidence: `src/oss_pipeline/submit.py`)
- Python PR submission → Python GitHub API: uses GitHub API (evidence: `src/oss_pipeline/submit.py`)
- Python PR submission → Python candidate models: uses candidate model (evidence: `src/oss_pipeline/submit.py`)
- Python PR submission → Python audit: records audit (evidence: `src/oss_pipeline/submit.py`)