# harshgounder/github-contribution-observatory architecture

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

- Interactive diagram: https://gitdiagram.com/harshgounder/github-contribution-observatory
- Repository: https://github.com/harshgounder/github-contribution-observatory

## Overview

This repository is a documentation-first design for a future GitHub contribution observatory, not a running crawler or contribution bot. The graph follows the README’s documented workflow and major capabilities; the listed specification files define planned components, and their implementation and exact runtime wiring remain unverified.

Main entry points: [`docs/security/SECURITY-MODEL.md`](https://github.com/harshgounder/github-contribution-observatory/blob/main/docs/security/SECURITY-MODEL.md) (Human action gate), [`docs/specs/CONTEXT-COMPILER-SPEC.md`](https://github.com/harshgounder/github-contribution-observatory/blob/main/docs/specs/CONTEXT-COMPILER-SPEC.md) (Context compiler), [`docs/specs/DATA-COMPILER-SPEC.md`](https://github.com/harshgounder/github-contribution-observatory/blob/main/docs/specs/DATA-COMPILER-SPEC.md) (Source registry), [`docs/specs/V2-SYSTEM-SPEC.md`](https://github.com/harshgounder/github-contribution-observatory/blob/main/docs/specs/V2-SYSTEM-SPEC.md) (Candidate universe)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_observation["Observation and evidence"]
  node_source_registry["Source registry"]
  node_candidate_universe["Candidate universe<br/>[V2-SYSTEM-SPEC.md]"]
  node_data_compiler["Versioned data compiler"]
  node_evidence_graph[("Evidence and provenance")]
end

subgraph group_reasoning["Context and decisions"]
  node_context_compiler["Context compiler"]
  node_memory[("Memory system<br/>[MEMORY-SPEC.md]")]
  node_experiment_policy["Experiment policy<br/>[V2-SYSTEM-SPEC.md]"]
end

subgraph group_work["Contribution and evaluation"]
  node_contribution_case["Isolated contribution case<br/>[V2-SYSTEM-SPEC.md]"]
  node_opencode["OpenCode patch builder<br/>[AGENT-MATRIX.md]"]
  node_tests_scans["Tests and scans"]
  node_fresh_evaluator["Fresh evaluator<br/>[EVALUATION-SPEC.md]"]
end

subgraph group_governance["Controls and outcomes"]
  node_action_gate["Human action gate<br/>[SECURITY-MODEL.md]"]
  node_capability_controls["Policy and capability controls<br/>[SECURITY-MODEL.md]"]
  node_github_action["Approved GitHub action<br/>[V2-SYSTEM-SPEC.md]"]
  node_outcome_dataset[("Contribution outcomes<br/>[EVALUATION-SPEC.md]")]
  node_research_release["Research release<br/>[V2-SYSTEM-SPEC.md]"]
end

node_public_sources(("Public GitHub sources"))
node_human(("Human reviewer"))
node_github(("GitHub"))

node_public_sources -->|"registers sources"| node_source_registry
node_source_registry -->|"defines coverage"| node_candidate_universe
node_candidate_universe -->|"selects records"| node_data_compiler
node_data_compiler -->|"compiles evidence"| node_evidence_graph
node_evidence_graph -->|"supplies evidence"| node_context_compiler
node_context_compiler -->|"informs experiments"| node_experiment_policy
node_memory -->|"supplies memory"| node_context_compiler
node_experiment_policy -->|"selects case"| node_contribution_case
node_contribution_case -->|"provides task"| node_opencode
node_opencode -->|"submits patch"| node_tests_scans
node_tests_scans -->|"supplies results"| node_fresh_evaluator
node_fresh_evaluator -->|"reports evaluation"| node_action_gate
node_human -->|"reviews"| node_action_gate
node_capability_controls -->|"constrains authority"| node_action_gate
node_action_gate -->|"approves action"| node_github_action
node_github_action -->|"performs action"| node_github
node_github -->|"contributes outcomes"| node_outcome_dataset
node_outcome_dataset -->|"informs next release"| node_research_release

click node_source_registry "https://github.com/harshgounder/github-contribution-observatory/blob/main/docs/specs/DATA-COMPILER-SPEC.md"
click node_candidate_universe "https://github.com/harshgounder/github-contribution-observatory/blob/main/docs/specs/V2-SYSTEM-SPEC.md"
click node_data_compiler "https://github.com/harshgounder/github-contribution-observatory/blob/main/docs/specs/DATA-COMPILER-SPEC.md"
click node_evidence_graph "https://github.com/harshgounder/github-contribution-observatory/blob/main/docs/specs/EVIDENCE-GRAPH-SPEC.md"
click node_context_compiler "https://github.com/harshgounder/github-contribution-observatory/blob/main/docs/specs/CONTEXT-COMPILER-SPEC.md"
click node_memory "https://github.com/harshgounder/github-contribution-observatory/blob/main/docs/specs/MEMORY-SPEC.md"
click node_experiment_policy "https://github.com/harshgounder/github-contribution-observatory/blob/main/docs/specs/V2-SYSTEM-SPEC.md"
click node_contribution_case "https://github.com/harshgounder/github-contribution-observatory/blob/main/docs/specs/V2-SYSTEM-SPEC.md"
click node_opencode "https://github.com/harshgounder/github-contribution-observatory/blob/main/docs/specs/AGENT-MATRIX.md"
click node_tests_scans "https://github.com/harshgounder/github-contribution-observatory/blob/main/docs/specs/ACCEPTANCE-TESTS.md"
click node_fresh_evaluator "https://github.com/harshgounder/github-contribution-observatory/blob/main/docs/evaluation/EVALUATION-SPEC.md"
click node_action_gate "https://github.com/harshgounder/github-contribution-observatory/blob/main/docs/security/SECURITY-MODEL.md"
click node_capability_controls "https://github.com/harshgounder/github-contribution-observatory/blob/main/docs/security/SECURITY-MODEL.md"
click node_github_action "https://github.com/harshgounder/github-contribution-observatory/blob/main/docs/specs/V2-SYSTEM-SPEC.md"
click node_outcome_dataset "https://github.com/harshgounder/github-contribution-observatory/blob/main/docs/evaluation/EVALUATION-SPEC.md"
click node_research_release "https://github.com/harshgounder/github-contribution-observatory/blob/main/docs/specs/V2-SYSTEM-SPEC.md"

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_source_registry,node_candidate_universe,node_data_compiler,node_evidence_graph,node_human toneBlue
class node_context_compiler,node_memory,node_experiment_policy toneAmber
class node_contribution_case,node_opencode,node_tests_scans,node_fresh_evaluator toneMint
class node_action_gate,node_capability_controls,node_github_action,node_outcome_dataset,node_research_release toneRose
class node_public_sources,node_github toneIndigo
```

## Components

### Observation and evidence

- [Source registry](https://github.com/harshgounder/github-contribution-observatory/blob/main/docs/specs/DATA-COMPILER-SPEC.md): `docs/specs/DATA-COMPILER-SPEC.md`
- [Candidate universe](https://github.com/harshgounder/github-contribution-observatory/blob/main/docs/specs/V2-SYSTEM-SPEC.md): `docs/specs/V2-SYSTEM-SPEC.md`
- [Versioned data compiler](https://github.com/harshgounder/github-contribution-observatory/blob/main/docs/specs/DATA-COMPILER-SPEC.md): `docs/specs/DATA-COMPILER-SPEC.md`
- [Evidence and provenance](https://github.com/harshgounder/github-contribution-observatory/blob/main/docs/specs/EVIDENCE-GRAPH-SPEC.md): `docs/specs/EVIDENCE-GRAPH-SPEC.md`

### Context and decisions

- [Context compiler](https://github.com/harshgounder/github-contribution-observatory/blob/main/docs/specs/CONTEXT-COMPILER-SPEC.md): `docs/specs/CONTEXT-COMPILER-SPEC.md`
- [Memory system](https://github.com/harshgounder/github-contribution-observatory/blob/main/docs/specs/MEMORY-SPEC.md): `docs/specs/MEMORY-SPEC.md`
- [Experiment policy](https://github.com/harshgounder/github-contribution-observatory/blob/main/docs/specs/V2-SYSTEM-SPEC.md): `docs/specs/V2-SYSTEM-SPEC.md`

### Contribution and evaluation

- [Isolated contribution case](https://github.com/harshgounder/github-contribution-observatory/blob/main/docs/specs/V2-SYSTEM-SPEC.md): `docs/specs/V2-SYSTEM-SPEC.md`
- [OpenCode patch builder](https://github.com/harshgounder/github-contribution-observatory/blob/main/docs/specs/AGENT-MATRIX.md): `docs/specs/AGENT-MATRIX.md`
- [Tests and scans](https://github.com/harshgounder/github-contribution-observatory/blob/main/docs/specs/ACCEPTANCE-TESTS.md): `docs/specs/ACCEPTANCE-TESTS.md`
- [Fresh evaluator](https://github.com/harshgounder/github-contribution-observatory/blob/main/docs/evaluation/EVALUATION-SPEC.md): `docs/evaluation/EVALUATION-SPEC.md`

### Controls and outcomes

- [Human action gate](https://github.com/harshgounder/github-contribution-observatory/blob/main/docs/security/SECURITY-MODEL.md): `docs/security/SECURITY-MODEL.md`
- [Policy and capability controls](https://github.com/harshgounder/github-contribution-observatory/blob/main/docs/security/SECURITY-MODEL.md): `docs/security/SECURITY-MODEL.md`
- [Approved GitHub action](https://github.com/harshgounder/github-contribution-observatory/blob/main/docs/specs/V2-SYSTEM-SPEC.md): `docs/specs/V2-SYSTEM-SPEC.md`
- [Contribution outcomes](https://github.com/harshgounder/github-contribution-observatory/blob/main/docs/evaluation/EVALUATION-SPEC.md): `docs/evaluation/EVALUATION-SPEC.md`
- [Research release](https://github.com/harshgounder/github-contribution-observatory/blob/main/docs/specs/V2-SYSTEM-SPEC.md): `docs/specs/V2-SYSTEM-SPEC.md`

### Other components

- **Public GitHub sources**
- **Human reviewer**
- **GitHub**

## Connections

- Public GitHub sources → Source registry: registers sources
- Source registry → Candidate universe: defines coverage
- Candidate universe → Versioned data compiler: selects records
- Versioned data compiler → Evidence and provenance: compiles evidence
- Evidence and provenance → Context compiler: supplies evidence
- Context compiler → Experiment policy: informs experiments
- Memory system → Context compiler: supplies memory
- Experiment policy → Isolated contribution case: selects case
- Isolated contribution case → OpenCode patch builder: provides task
- OpenCode patch builder → Tests and scans: submits patch
- Tests and scans → Fresh evaluator: supplies results
- Fresh evaluator → Human action gate: reports evaluation
- Human reviewer → Human action gate: reviews
- Policy and capability controls → Human action gate: constrains authority
- Human action gate → Approved GitHub action: approves action
- Approved GitHub action → GitHub: performs action
- GitHub → Contribution outcomes: contributes outcomes
- Contribution outcomes → Research release: informs next release