# victorzhong0110/gold-miner architecture

> Architecture diagram of the GitHub repository victorzhong0110/gold-miner, 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/victorzhong0110/gold-miner
- Repository: https://github.com/victorzhong0110/gold-miner

## Overview

Gold Miner is a product-validation project for cross-language GitHub discovery, not an installable extension: the README explicitly says no extension exists and no product-effect conclusions have been reached. Its principal implemented workflow is an E1 search experiment that takes query tasks and settings, runs budgeted GitHub searches, merges candidate repositories, and writes evaluation records. The roadmap also covers open-ended discovery, translation and reading, recommendations, and optional shared discovery. Those are documented plans or experiments, not verified product runtime. Source excerpts support the E1 and H0 components shown; unsampled subsystems are represented only at documented directory or plan paths.

Main entry points: [`docs/plan/v0.4.md`](https://github.com/victorzhong0110/gold-miner/blob/main/docs/plan/v0.4.md) (Product scope), [`experiments/E1-cross-language-search/scripts/e1_batch.py`](https://github.com/victorzhong0110/gold-miner/blob/main/experiments/E1-cross-language-search/scripts/e1_batch.py) (Batch orchestration), [`experiments/E1-cross-language-search/scripts/e1_minimal_runner.py`](https://github.com/victorzhong0110/gold-miner/blob/main/experiments/E1-cross-language-search/scripts/e1_minimal_runner.py) (Budgeted search), [`experiments/E1-cross-language-search/scripts/github_search.py`](https://github.com/victorzhong0110/gold-miner/blob/main/experiments/E1-cross-language-search/scripts/github_search.py) (GitHub search client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_validation["Search validation"]
  node_tasks["Search tasks<br/>[queries.yaml]"]
  node_settings["Run settings<br/>[run-settings.json]"]
  node_batch["Batch orchestration<br/>[e1_batch.py]"]
  node_runner["Budgeted search"]
  node_searchclient["GitHub search client<br/>[github_search.py]"]
  node_records["Candidate records"]
end

subgraph group_signals["Candidate signals"]
  node_seedparser["Seed source parser"]
  node_classifier["README classifier<br/>[readme_lang.py]"]
  node_h0["Metadata summary<br/>[h0_sample.py]"]
end

subgraph group_experience["Planned experience"]
  node_roadmap["Product scope<br/>[v0.4.md]"]
  node_extension["GitHub page experience<br/>[v0.4.md]"]
  node_translation["Translation support"]
  node_recommendation["Discovery assistance"]
  node_personal[("Local preferences<br/>[README.md]")]
  node_shared[("Opt-in shared entries<br/>[README.md]")]
end

subgraph group_evaluation["Research evaluation"]
  node_openended["Open-ended discovery<br/>[protocol.md]"]
  node_faithful["Faithful reading"]
  node_discoverability["Discoverability probes"]
  node_glossary["Glossary concepts"]
end

node_user(("Project explorer"))
node_github{{"GitHub Search API"}}
node_hellogithub{{"HelloGitHub issues"}}
node_metadata[("Repository metadata")]
node_model{{"User-provided model API"}}

node_user -->|"starts run"| node_batch
node_tasks -->|"supplies tasks"| node_batch
node_settings -->|"configures run"| node_batch
node_batch -->|"runs variants"| node_runner
node_runner -->|"requests search"| node_searchclient
node_searchclient -->|"queries repositories"| node_github
node_github -->|"returns results"| node_searchclient
node_runner -->|"emits candidates"| node_records
node_batch -->|"writes run outputs"| node_records
node_hellogithub -->|"provides Markdown"| node_seedparser
node_metadata -->|"provides repository data"| node_h0
node_h0 -->|"classifies README"| node_classifier
node_user -.->|"uses planned experience"| node_extension
node_roadmap -->|"specifies scope"| node_extension
node_roadmap -->|"plans capability"| node_translation
node_roadmap -->|"plans capability"| node_recommendation
node_user -.->|"reads with assistance"| node_translation
node_extension -.->|"stores locally"| node_personal
node_extension -.->|"contributes by choice"| node_shared
node_recommendation -.->|"may call"| node_model
node_roadmap -->|"defines experiment"| node_openended
node_roadmap -->|"defines experiment"| node_faithful
node_roadmap -->|"defines probes"| node_discoverability
node_roadmap -->|"tracks terminology"| node_glossary

click node_roadmap "https://github.com/victorzhong0110/gold-miner/blob/main/docs/plan/v0.4.md"
click node_tasks "https://github.com/victorzhong0110/gold-miner/blob/main/experiments/E1-cross-language-search/queries.yaml"
click node_settings "https://github.com/victorzhong0110/gold-miner/blob/main/experiments/E1-cross-language-search/run-settings.json"
click node_batch "https://github.com/victorzhong0110/gold-miner/blob/main/experiments/E1-cross-language-search/scripts/e1_batch.py"
click node_runner "https://github.com/victorzhong0110/gold-miner/blob/main/experiments/E1-cross-language-search/scripts/e1_minimal_runner.py"
click node_searchclient "https://github.com/victorzhong0110/gold-miner/blob/main/experiments/E1-cross-language-search/scripts/github_search.py"
click node_records "https://github.com/victorzhong0110/gold-miner/blob/main/experiments/E1-cross-language-search/schemas/candidates.schema.json"
click node_seedparser "https://github.com/victorzhong0110/gold-miner/blob/main/experiments/E1-cross-language-search/scripts/parse_hellogithub.py"
click node_classifier "https://github.com/victorzhong0110/gold-miner/blob/main/experiments/E1-cross-language-search/scripts/readme_lang.py"
click node_h0 "https://github.com/victorzhong0110/gold-miner/blob/main/experiments/E1-cross-language-search/scripts/h0_sample.py"
click node_extension "https://github.com/victorzhong0110/gold-miner/blob/main/docs/plan/v0.4.md"
click node_translation "https://github.com/victorzhong0110/gold-miner/blob/main/docs/research/2026-09-17-translation-and-discovery.md"
click node_recommendation "https://github.com/victorzhong0110/gold-miner/blob/main/docs/research/2026-09-17-translation-and-discovery.md"
click node_personal "https://github.com/victorzhong0110/gold-miner/blob/main/README.md"
click node_shared "https://github.com/victorzhong0110/gold-miner/blob/main/README.md"
click node_openended "https://github.com/victorzhong0110/gold-miner/blob/main/experiments/E2-open-ended-discovery/protocol.md"
click node_faithful "https://github.com/victorzhong0110/gold-miner/tree/main/experiments/E3-faithful-reading"
click node_discoverability "https://github.com/victorzhong0110/gold-miner/tree/main/experiments/E8-discoverability"
click node_glossary "https://github.com/victorzhong0110/gold-miner/tree/main/experiments/E9-glossary"

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_tasks,node_settings,node_batch,node_runner,node_searchclient,node_records,node_model toneBlue
class node_seedparser,node_classifier,node_h0,node_metadata toneAmber
class node_roadmap,node_extension,node_translation,node_recommendation,node_personal,node_shared,node_github toneMint
class node_openended,node_faithful,node_discoverability,node_glossary toneRose
class node_user,node_hellogithub toneIndigo
```

## Components

### Search validation

- [Search tasks](https://github.com/victorzhong0110/gold-miner/blob/main/experiments/E1-cross-language-search/queries.yaml): `experiments/E1-cross-language-search/queries.yaml`
- [Run settings](https://github.com/victorzhong0110/gold-miner/blob/main/experiments/E1-cross-language-search/run-settings.json): `experiments/E1-cross-language-search/run-settings.json`
- [Batch orchestration](https://github.com/victorzhong0110/gold-miner/blob/main/experiments/E1-cross-language-search/scripts/e1_batch.py): `experiments/E1-cross-language-search/scripts/e1_batch.py`
- [Budgeted search](https://github.com/victorzhong0110/gold-miner/blob/main/experiments/E1-cross-language-search/scripts/e1_minimal_runner.py): `experiments/E1-cross-language-search/scripts/e1_minimal_runner.py`
- [GitHub search client](https://github.com/victorzhong0110/gold-miner/blob/main/experiments/E1-cross-language-search/scripts/github_search.py): `experiments/E1-cross-language-search/scripts/github_search.py`
- [Candidate records](https://github.com/victorzhong0110/gold-miner/blob/main/experiments/E1-cross-language-search/schemas/candidates.schema.json): `experiments/E1-cross-language-search/schemas/candidates.schema.json`

### Candidate signals

- [Seed source parser](https://github.com/victorzhong0110/gold-miner/blob/main/experiments/E1-cross-language-search/scripts/parse_hellogithub.py): `experiments/E1-cross-language-search/scripts/parse_hellogithub.py`
- [README classifier](https://github.com/victorzhong0110/gold-miner/blob/main/experiments/E1-cross-language-search/scripts/readme_lang.py): `experiments/E1-cross-language-search/scripts/readme_lang.py`
- [Metadata summary](https://github.com/victorzhong0110/gold-miner/blob/main/experiments/E1-cross-language-search/scripts/h0_sample.py): `experiments/E1-cross-language-search/scripts/h0_sample.py`

### Planned experience

- [Product scope](https://github.com/victorzhong0110/gold-miner/blob/main/docs/plan/v0.4.md): `docs/plan/v0.4.md`
- [GitHub page experience](https://github.com/victorzhong0110/gold-miner/blob/main/docs/plan/v0.4.md): `docs/plan/v0.4.md`
- [Translation support](https://github.com/victorzhong0110/gold-miner/blob/main/docs/research/2026-09-17-translation-and-discovery.md): `docs/research/2026-09-17-translation-and-discovery.md`
- [Discovery assistance](https://github.com/victorzhong0110/gold-miner/blob/main/docs/research/2026-09-17-translation-and-discovery.md): `docs/research/2026-09-17-translation-and-discovery.md`
- [Local preferences](https://github.com/victorzhong0110/gold-miner/blob/main/README.md): `README.md`
- [Opt-in shared entries](https://github.com/victorzhong0110/gold-miner/blob/main/README.md): `README.md`

### Research evaluation

- [Open-ended discovery](https://github.com/victorzhong0110/gold-miner/blob/main/experiments/E2-open-ended-discovery/protocol.md): `experiments/E2-open-ended-discovery/protocol.md`
- [Faithful reading](https://github.com/victorzhong0110/gold-miner/tree/main/experiments/E3-faithful-reading): `experiments/E3-faithful-reading`
- [Discoverability probes](https://github.com/victorzhong0110/gold-miner/tree/main/experiments/E8-discoverability): `experiments/E8-discoverability`
- [Glossary concepts](https://github.com/victorzhong0110/gold-miner/tree/main/experiments/E9-glossary): `experiments/E9-glossary`

### Other components

- **Project explorer**
- **GitHub Search API**
- **HelloGitHub issues**
- **Repository metadata**
- **User-provided model API**

## Connections

- Project explorer → Batch orchestration: starts run
- Search tasks → Batch orchestration: supplies tasks
- Run settings → Batch orchestration: configures run
- Batch orchestration → Budgeted search: runs variants
- Budgeted search → GitHub search client: requests search
- GitHub search client → GitHub Search API: queries repositories
- GitHub Search API → GitHub search client: returns results
- Budgeted search → Candidate records: emits candidates
- Batch orchestration → Candidate records: writes run outputs
- HelloGitHub issues → Seed source parser: provides Markdown
- Repository metadata → Metadata summary: provides repository data
- Metadata summary → README classifier: classifies README
- Project explorer → GitHub page experience: uses planned experience
- Product scope → GitHub page experience: specifies scope
- Product scope → Translation support: plans capability
- Product scope → Discovery assistance: plans capability
- Project explorer → Translation support: reads with assistance
- GitHub page experience → Local preferences: stores locally
- GitHub page experience → Opt-in shared entries: contributes by choice
- Discovery assistance → User-provided model API: may call
- Product scope → Open-ended discovery: defines experiment
- Product scope → Faithful reading: defines experiment
- Product scope → Discoverability probes: defines probes
- Product scope → Glossary concepts: tracks terminology