# heinsithukyaw/git-agent architecture

> Architecture diagram of the GitHub repository heinsithukyaw/git-agent, 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/git-agent
- Repository: https://github.com/heinsithukyaw/git-agent
- Video tour (about a minute): https://gitdiagram.com/heinsithukyaw/git-agent/video

## Overview

Git Agent is a stateless, repository-backed dependency watcher. Its scheduled workflow reads the configured stack, gathers registry and advisory data, triages changes, optionally adds model narration, then gates and commits a digest and public projection. A separate issue-comment workflow handles conversational commands; a conditional heartbeat records fetch failures. The published site is rendered from committed public artifacts. The tree and excerpts support these main stages, but do not expose every script’s call graph, so uncertain internal wiring is omitted.

Main entry points: [`scripts/fetch-step.mjs`](https://github.com/heinsithukyaw/git-agent/blob/main/scripts/fetch-step.mjs) (Fetch step), [`scripts/commit-step.mjs`](https://github.com/heinsithukyaw/git-agent/blob/main/scripts/commit-step.mjs) (Commit step), [`lib/store.mjs`](https://github.com/heinsithukyaw/git-agent/blob/main/lib/store.mjs) (File store), [`scripts/route-step.mjs`](https://github.com/heinsithukyaw/git-agent/blob/main/scripts/route-step.mjs) (Command routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_scheduled["Scheduled digest"]
  node_fetch["Fetch step<br/>[fetch-step.mjs]"]
  node_sources["Dependency sources<br/>[sources.mjs]"]
  node_narrate["Narration step<br/>[narrate-step.mjs]"]
  node_llm["Model client<br/>[llm.mjs]"]
  node_commit["Commit step<br/>[commit-step.mjs]"]
  node_heartbeat["Heartbeat step<br/>[heartbeat-step.mjs]"]
end

subgraph group_conversation["Issue conversation"]
  node_route["Command routing<br/>[route-step.mjs]"]
  node_commands["Command rules<br/>[commands.mjs]"]
  node_reply["Reply step<br/>[reply-step.mjs]"]
end

subgraph group_policy["Triage and safety"]
  node_triage["Advisory triage<br/>[triage.mjs]"]
  node_gate["Containment gate<br/>[gate.mjs]"]
  node_public["Public projection<br/>[public-surface.mjs]"]
  node_publishable["Publication policy<br/>[publishable.mjs]"]
end

subgraph group_state["Repository and publication"]
  node_stack["Watch configuration<br/>[stack.json]"]
  node_render["Digest renderer<br/>[render.mjs]"]
  node_store["File store<br/>[store.mjs]"]
  node_history["Run history<br/>[runs.jsonl]"]
  node_site["Static site renderer<br/>[render-site.mjs]"]
  node_pages["Published Pages<br/>[index.html]"]
end

node_actions(("GitHub Actions"))
node_operator(("Repository operator"))
node_reader(("Site reader"))
node_github["GitHub API"]
node_registries["Package registries"]
node_osv["OSV advisories"]
node_model["Configured model endpoint"]

node_actions -->|"starts run"| node_fetch
node_fetch -->|"reads config"| node_stack
node_fetch -->|"gathers data"| node_sources
node_sources -->|"queries releases"| node_registries
node_sources -->|"queries advisories"| node_osv
node_fetch -->|"triages data"| node_triage
node_fetch -->|"passes artifact"| node_narrate
node_narrate -->|"requests prose"| node_llm
node_llm -.->|"sends request"| node_model
node_narrate -->|"checks narration"| node_gate
node_actions -->|"starts commit job"| node_commit
node_commit -->|"validates output"| node_gate
node_commit -->|"renders digest"| node_render
node_commit -->|"projects public data"| node_public
node_public -->|"applies policy"| node_publishable
node_commit -->|"writes artifacts"| node_store
node_store -->|"appends records"| node_history
node_actions -.->|"runs on failure"| node_heartbeat
node_heartbeat -->|"writes status"| node_store
node_operator -->|"configures watchlist"| node_stack
node_actions -->|"starts issue turn"| node_route
node_route -->|"checks command"| node_commands
node_route -->|"reads issue"| node_github
node_reply -->|"posts reply"| node_github
node_route -->|"records command"| node_store
node_actions -->|"dispatches reply"| node_reply
node_actions -->|"renders site"| node_site
node_site -->|"reads summary"| node_store
node_site -->|"writes site"| node_pages
node_reader -->|"views digest"| node_pages

click node_stack "https://github.com/heinsithukyaw/git-agent/blob/main/data/stack.json"
click node_fetch "https://github.com/heinsithukyaw/git-agent/blob/main/scripts/fetch-step.mjs"
click node_sources "https://github.com/heinsithukyaw/git-agent/blob/main/lib/sources.mjs"
click node_triage "https://github.com/heinsithukyaw/git-agent/blob/main/lib/triage.mjs"
click node_narrate "https://github.com/heinsithukyaw/git-agent/blob/main/scripts/narrate-step.mjs"
click node_llm "https://github.com/heinsithukyaw/git-agent/blob/main/lib/llm.mjs"
click node_gate "https://github.com/heinsithukyaw/git-agent/blob/main/lib/gate.mjs"
click node_commit "https://github.com/heinsithukyaw/git-agent/blob/main/scripts/commit-step.mjs"
click node_render "https://github.com/heinsithukyaw/git-agent/blob/main/lib/render.mjs"
click node_public "https://github.com/heinsithukyaw/git-agent/blob/main/lib/public-surface.mjs"
click node_publishable "https://github.com/heinsithukyaw/git-agent/blob/main/lib/publishable.mjs"
click node_store "https://github.com/heinsithukyaw/git-agent/blob/main/lib/store.mjs"
click node_history "https://github.com/heinsithukyaw/git-agent/blob/main/history/runs.jsonl"
click node_heartbeat "https://github.com/heinsithukyaw/git-agent/blob/main/scripts/heartbeat-step.mjs"
click node_route "https://github.com/heinsithukyaw/git-agent/blob/main/scripts/route-step.mjs"
click node_commands "https://github.com/heinsithukyaw/git-agent/blob/main/lib/commands.mjs"
click node_reply "https://github.com/heinsithukyaw/git-agent/blob/main/scripts/reply-step.mjs"
click node_site "https://github.com/heinsithukyaw/git-agent/blob/main/scripts/render-site.mjs"
click node_pages "https://github.com/heinsithukyaw/git-agent/blob/main/site/index.html"

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_fetch,node_sources,node_narrate,node_llm,node_commit,node_heartbeat toneBlue
class node_route,node_commands,node_reply toneAmber
class node_triage,node_gate,node_public,node_publishable,node_github toneMint
class node_stack,node_render,node_store,node_history,node_site,node_pages toneRose
class node_actions,node_operator,node_reader,node_registries,node_osv,node_model toneIndigo
```

## Components

### Scheduled digest

- [Fetch step](https://github.com/heinsithukyaw/git-agent/blob/main/scripts/fetch-step.mjs): `scripts/fetch-step.mjs`
- [Dependency sources](https://github.com/heinsithukyaw/git-agent/blob/main/lib/sources.mjs): `lib/sources.mjs`
- [Narration step](https://github.com/heinsithukyaw/git-agent/blob/main/scripts/narrate-step.mjs): `scripts/narrate-step.mjs`
- [Model client](https://github.com/heinsithukyaw/git-agent/blob/main/lib/llm.mjs): `lib/llm.mjs`
- [Commit step](https://github.com/heinsithukyaw/git-agent/blob/main/scripts/commit-step.mjs): `scripts/commit-step.mjs`
- [Heartbeat step](https://github.com/heinsithukyaw/git-agent/blob/main/scripts/heartbeat-step.mjs): `scripts/heartbeat-step.mjs`

### Issue conversation

- [Command routing](https://github.com/heinsithukyaw/git-agent/blob/main/scripts/route-step.mjs): `scripts/route-step.mjs`
- [Command rules](https://github.com/heinsithukyaw/git-agent/blob/main/lib/commands.mjs): `lib/commands.mjs`
- [Reply step](https://github.com/heinsithukyaw/git-agent/blob/main/scripts/reply-step.mjs): `scripts/reply-step.mjs`

### Triage and safety

- [Advisory triage](https://github.com/heinsithukyaw/git-agent/blob/main/lib/triage.mjs): `lib/triage.mjs`
- [Containment gate](https://github.com/heinsithukyaw/git-agent/blob/main/lib/gate.mjs): `lib/gate.mjs`
- [Public projection](https://github.com/heinsithukyaw/git-agent/blob/main/lib/public-surface.mjs): `lib/public-surface.mjs`
- [Publication policy](https://github.com/heinsithukyaw/git-agent/blob/main/lib/publishable.mjs): `lib/publishable.mjs`

### Repository and publication

- [Watch configuration](https://github.com/heinsithukyaw/git-agent/blob/main/data/stack.json): `data/stack.json`
- [Digest renderer](https://github.com/heinsithukyaw/git-agent/blob/main/lib/render.mjs): `lib/render.mjs`
- [File store](https://github.com/heinsithukyaw/git-agent/blob/main/lib/store.mjs): `lib/store.mjs`
- [Run history](https://github.com/heinsithukyaw/git-agent/blob/main/history/runs.jsonl): `history/runs.jsonl`
- [Static site renderer](https://github.com/heinsithukyaw/git-agent/blob/main/scripts/render-site.mjs): `scripts/render-site.mjs`
- [Published Pages](https://github.com/heinsithukyaw/git-agent/blob/main/site/index.html): `site/index.html`

### Other components

- **GitHub Actions**
- **Repository operator**
- **Site reader**
- **GitHub API**
- **Package registries**
- **OSV advisories**
- **Configured model endpoint**

## Connections

- GitHub Actions → Fetch step: starts run
- Fetch step → Watch configuration: reads config
- Fetch step → Dependency sources: gathers data
- Dependency sources → Package registries: queries releases
- Dependency sources → OSV advisories: queries advisories
- Fetch step → Advisory triage: triages data
- Fetch step → Narration step: passes artifact
- Narration step → Model client: requests prose
- Model client → Configured model endpoint: sends request
- Narration step → Containment gate: checks narration
- GitHub Actions → Commit step: starts commit job
- Commit step → Containment gate: validates output
- Commit step → Digest renderer: renders digest
- Commit step → Public projection: projects public data
- Public projection → Publication policy: applies policy
- Commit step → File store: writes artifacts
- File store → Run history: appends records
- GitHub Actions → Heartbeat step: runs on failure
- Heartbeat step → File store: writes status
- Repository operator → Watch configuration: configures watchlist
- GitHub Actions → Command routing: starts issue turn
- Command routing → Command rules: checks command
- Command routing → GitHub API: reads issue
- Reply step → GitHub API: posts reply
- Command routing → File store: records command
- GitHub Actions → Reply step: dispatches reply
- GitHub Actions → Static site renderer: renders site
- Static site renderer → File store: reads summary
- Static site renderer → Published Pages: writes site
- Site reader → Published Pages: views digest