# heinsithukyaw/agent-harness architecture

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

- Interactive diagram: https://gitdiagram.com/heinsithukyaw/agent-harness
- Repository: https://github.com/heinsithukyaw/agent-harness
- Video tour (about a minute): https://gitdiagram.com/heinsithukyaw/agent-harness/video

## Overview

Agent-Harness is a GitHub-backed registry of agent-framework projects. Its main workflow discovers repositories, enriches their metadata, classifies them into layers, records changes, then generates browsable data and visualizations. Users browse the generated web interface or consume the JSON and Markdown corpus. The graph focuses on this product; the separate profile-cards utility is not part of the README-described registry. Collection and rendering excerpts are partial, so uncertain internal wiring is omitted.

Main entry points: [`agent-harness/collect.mjs`](https://github.com/heinsithukyaw/agent-harness/blob/main/agent-harness/collect.mjs) (Collector), [`agent-harness/render.mjs`](https://github.com/heinsithukyaw/agent-harness/blob/main/agent-harness/render.mjs) (Renderer), [`agent-harness/data/projects.json`](https://github.com/heinsithukyaw/agent-harness/blob/main/agent-harness/data/projects.json) (Project Corpus), [`agent-harness/history/projects`](https://github.com/heinsithukyaw/agent-harness/tree/main/agent-harness/history/projects) (Project History)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Collection and Classification"]
  node_collector["Collector<br/>[collect.mjs]"]
  node_source_config["Source Queries<br/>[sources.json]"]
  node_classifier["Layer Classifier<br/>[collect.mjs]"]
end

subgraph group_state["Registry State"]
  node_projects["Project Corpus<br/>[projects.json]"]
  node_project_history[("Project History")]
  node_run_history["Run Ledger<br/>[events.jsonl]"]
  node_traffic["Traffic Data<br/>[traffic.json]"]
end

subgraph group_publication["Generated Views"]
  node_renderer["Renderer<br/>[render.mjs]"]
  node_registry_site["Searchable Site"]
  node_project_cards["Project Cards"]
  node_json_api["JSON Corpus<br/>[projects.json]"]
  node_markdown_index["Layer Tables<br/>[index.md]"]
end

node_maintainer(("Maintainer"))
node_github["GitHub API"]
node_visitor(("Registry Visitor"))

node_maintainer -->|"initiates collection"| node_collector
node_collector -->|"reads queries"| node_source_config
node_collector -->|"searches and enriches"| node_github
node_collector -->|"classifies metadata"| node_classifier
node_collector -->|"updates corpus"| node_projects
node_collector -->|"appends observations"| node_project_history
node_collector -->|"records runs"| node_run_history
node_collector -.->|"updates traffic"| node_traffic
node_renderer -->|"reads corpus"| node_projects
node_renderer -->|"reads run history"| node_project_history
node_renderer -->|"reads ledger"| node_run_history
node_renderer -->|"reads traffic"| node_traffic
node_renderer -->|"generates site"| node_registry_site
node_renderer -->|"generates cards"| node_project_cards
node_renderer -->|"generates tables"| node_markdown_index
node_visitor -->|"searches and filters"| node_registry_site
node_visitor -->|"consumes corpus"| node_json_api
node_visitor -->|"browses tables"| node_markdown_index

click node_collector "https://github.com/heinsithukyaw/agent-harness/blob/main/agent-harness/collect.mjs"
click node_source_config "https://github.com/heinsithukyaw/agent-harness/blob/main/agent-harness/config/sources.json"
click node_classifier "https://github.com/heinsithukyaw/agent-harness/blob/main/agent-harness/collect.mjs"
click node_projects "https://github.com/heinsithukyaw/agent-harness/blob/main/agent-harness/data/projects.json"
click node_project_history "https://github.com/heinsithukyaw/agent-harness/tree/main/agent-harness/history/projects"
click node_run_history "https://github.com/heinsithukyaw/agent-harness/blob/main/agent-harness/history/events.jsonl"
click node_traffic "https://github.com/heinsithukyaw/agent-harness/blob/main/agent-harness/data/traffic.json"
click node_renderer "https://github.com/heinsithukyaw/agent-harness/blob/main/agent-harness/render.mjs"
click node_registry_site "https://github.com/heinsithukyaw/agent-harness/tree/main/agent-harness/site"
click node_project_cards "https://github.com/heinsithukyaw/agent-harness/tree/main/agent-harness/assets/cards"
click node_json_api "https://github.com/heinsithukyaw/agent-harness/blob/main/agent-harness/data/projects.json"
click node_markdown_index "https://github.com/heinsithukyaw/agent-harness/blob/main/agent-harness/data/index.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_collector,node_source_config,node_classifier toneBlue
class node_projects,node_project_history,node_run_history,node_traffic toneAmber
class node_renderer,node_registry_site,node_project_cards,node_json_api,node_markdown_index,node_github toneMint
class node_maintainer,node_visitor toneIndigo
```

## Components

### Collection and Classification

- [Collector](https://github.com/heinsithukyaw/agent-harness/blob/main/agent-harness/collect.mjs): `agent-harness/collect.mjs`
- [Source Queries](https://github.com/heinsithukyaw/agent-harness/blob/main/agent-harness/config/sources.json): `agent-harness/config/sources.json`
- [Layer Classifier](https://github.com/heinsithukyaw/agent-harness/blob/main/agent-harness/collect.mjs): `agent-harness/collect.mjs`

### Registry State

- [Project Corpus](https://github.com/heinsithukyaw/agent-harness/blob/main/agent-harness/data/projects.json): `agent-harness/data/projects.json`
- [Project History](https://github.com/heinsithukyaw/agent-harness/tree/main/agent-harness/history/projects): `agent-harness/history/projects`
- [Run Ledger](https://github.com/heinsithukyaw/agent-harness/blob/main/agent-harness/history/events.jsonl): `agent-harness/history/events.jsonl`
- [Traffic Data](https://github.com/heinsithukyaw/agent-harness/blob/main/agent-harness/data/traffic.json): `agent-harness/data/traffic.json`

### Generated Views

- [Renderer](https://github.com/heinsithukyaw/agent-harness/blob/main/agent-harness/render.mjs): `agent-harness/render.mjs`
- [Searchable Site](https://github.com/heinsithukyaw/agent-harness/tree/main/agent-harness/site): `agent-harness/site`
- [Project Cards](https://github.com/heinsithukyaw/agent-harness/tree/main/agent-harness/assets/cards): `agent-harness/assets/cards`
- [JSON Corpus](https://github.com/heinsithukyaw/agent-harness/blob/main/agent-harness/data/projects.json): `agent-harness/data/projects.json`
- [Layer Tables](https://github.com/heinsithukyaw/agent-harness/blob/main/agent-harness/data/index.md): `agent-harness/data/index.md`

### Other components

- **Maintainer**
- **GitHub API**
- **Registry Visitor**

## Connections

- Maintainer → Collector: initiates collection
- Collector → Source Queries: reads queries
- Collector → GitHub API: searches and enriches
- Collector → Layer Classifier: classifies metadata
- Collector → Project Corpus: updates corpus
- Collector → Project History: appends observations
- Collector → Run Ledger: records runs
- Collector → Traffic Data: updates traffic
- Renderer → Project Corpus: reads corpus
- Renderer → Project History: reads run history
- Renderer → Run Ledger: reads ledger
- Renderer → Traffic Data: reads traffic
- Renderer → Searchable Site: generates site
- Renderer → Project Cards: generates cards
- Renderer → Layer Tables: generates tables
- Registry Visitor → Searchable Site: searches and filters
- Registry Visitor → JSON Corpus: consumes corpus
- Registry Visitor → Layer Tables: browses tables