# javepreem/pi-worker-graph architecture

> Architecture diagram of the GitHub repository javepreem/pi-worker-graph, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/javepreem/pi-worker-graph
- Repository: https://github.com/javepreem/pi-worker-graph

## Overview

pi-worker-graph is a Pi coding-agent extension and DAG-first runtime for coordinating writable workers in a shared checkout. The parent activates the graph tool, scopes tasks, and receives results; the runtime validates dependencies, schedules eligible work, builds bounded prerequisite context, executes workers, and retains reports and run state. Optional capabilities include checks with review/repair, coordination events and inboxes, artifacts, and usage accounting. Edges reflect the README and shown imports or calls; several source excerpts are partial, so uncertain internal links are omitted.

Main entry points: [`src/orchestrator.ts`](https://github.com/javepreem/pi-worker-graph/blob/main/src/orchestrator.ts) (Orchestration), [`src/run.ts`](https://github.com/javepreem/pi-worker-graph/blob/main/src/run.ts) (Graph runner), [`src/store.ts`](https://github.com/javepreem/pi-worker-graph/blob/main/src/store.ts) (Run store), [`src/extension.ts`](https://github.com/javepreem/pi-worker-graph/blob/main/src/extension.ts) (Extension tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_activation["Pi integration"]
  node_extension["Extension tools<br/>[extension.ts]"]
  node_configuration["Configuration<br/>[config.ts]"]
end

subgraph group_execution["Graph execution"]
  node_orchestrator["Orchestration<br/>[orchestrator.ts]"]
  node_graph["DAG primitives<br/>[graph.ts]"]
  node_runner["Graph runner<br/>[run.ts]"]
  node_worker["Pi subprocess<br/>[pi-subprocess.ts]"]
  node_checks["Checks and review<br/>[check.ts]"]
end

subgraph group_contracts["Reports and context"]
  node_context["Prerequisite context<br/>[context.ts]"]
  node_reports["Worker reports<br/>[output.ts]"]
  node_failures["Execution failures"]
  node_usage["Usage accounting<br/>[usage.ts]"]
  node_json["JSON validation<br/>[json.ts]"]
end

subgraph group_persistence["Run state"]
  node_coordination["Coordination<br/>[coordination.ts]"]
  node_store[("Run store<br/>[store.ts]")]
end

node_parent(("Parent agent"))

node_parent -->|"invokes tools"| node_extension
node_extension -->|"loads settings"| node_configuration
node_extension -->|"registers tool"| node_orchestrator
node_extension -->|"imports"| node_coordination
node_orchestrator -->|"loads profiles"| node_configuration
node_orchestrator -->|"runs graph"| node_runner
node_orchestrator -->|"configures executor"| node_worker
node_orchestrator -->|"configures checks"| node_checks
node_orchestrator -->|"accesses run state"| node_store
node_runner -->|"schedules tasks"| node_graph
node_runner -->|"serializes prerequisites"| node_context
node_runner -->|"reads and publishes"| node_store
node_runner -->|"validates outputs"| node_reports
node_worker -->|"runs checks"| node_checks
node_worker -->|"parses tool result"| node_reports
node_context -->|"validates reports"| node_reports
node_failures -->|"validates usage"| node_usage
node_store -->|"parses artifacts"| node_reports
node_store -->|"parses accounting"| node_usage
node_coordination -->|"persists coordination"| node_store
node_configuration -->|"parses profiles"| node_worker

click node_extension "https://github.com/javepreem/pi-worker-graph/blob/main/src/extension.ts"
click node_configuration "https://github.com/javepreem/pi-worker-graph/blob/main/src/config.ts"
click node_orchestrator "https://github.com/javepreem/pi-worker-graph/blob/main/src/orchestrator.ts"
click node_graph "https://github.com/javepreem/pi-worker-graph/blob/main/src/graph.ts"
click node_runner "https://github.com/javepreem/pi-worker-graph/blob/main/src/run.ts"
click node_worker "https://github.com/javepreem/pi-worker-graph/blob/main/src/pi-subprocess.ts"
click node_checks "https://github.com/javepreem/pi-worker-graph/blob/main/src/check.ts"
click node_context "https://github.com/javepreem/pi-worker-graph/blob/main/src/context.ts"
click node_reports "https://github.com/javepreem/pi-worker-graph/blob/main/src/output.ts"
click node_failures "https://github.com/javepreem/pi-worker-graph/blob/main/src/execution-failure.ts"
click node_usage "https://github.com/javepreem/pi-worker-graph/blob/main/src/usage.ts"
click node_coordination "https://github.com/javepreem/pi-worker-graph/blob/main/src/coordination.ts"
click node_store "https://github.com/javepreem/pi-worker-graph/blob/main/src/store.ts"
click node_json "https://github.com/javepreem/pi-worker-graph/blob/main/src/json.ts"

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_extension,node_configuration toneBlue
class node_orchestrator,node_graph,node_runner,node_worker,node_checks toneAmber
class node_context,node_reports,node_failures,node_usage,node_json toneMint
class node_coordination,node_store toneRose
class node_parent toneIndigo
```

## Components

### Pi integration

- [Extension tools](https://github.com/javepreem/pi-worker-graph/blob/main/src/extension.ts): `src/extension.ts`
- [Configuration](https://github.com/javepreem/pi-worker-graph/blob/main/src/config.ts): `src/config.ts`

### Graph execution

- [Orchestration](https://github.com/javepreem/pi-worker-graph/blob/main/src/orchestrator.ts): `src/orchestrator.ts`
- [DAG primitives](https://github.com/javepreem/pi-worker-graph/blob/main/src/graph.ts): `src/graph.ts`
- [Graph runner](https://github.com/javepreem/pi-worker-graph/blob/main/src/run.ts): `src/run.ts`
- [Pi subprocess](https://github.com/javepreem/pi-worker-graph/blob/main/src/pi-subprocess.ts): `src/pi-subprocess.ts`
- [Checks and review](https://github.com/javepreem/pi-worker-graph/blob/main/src/check.ts): `src/check.ts`

### Reports and context

- [Prerequisite context](https://github.com/javepreem/pi-worker-graph/blob/main/src/context.ts): `src/context.ts`
- [Worker reports](https://github.com/javepreem/pi-worker-graph/blob/main/src/output.ts): `src/output.ts`
- [Execution failures](https://github.com/javepreem/pi-worker-graph/blob/main/src/execution-failure.ts): `src/execution-failure.ts`
- [Usage accounting](https://github.com/javepreem/pi-worker-graph/blob/main/src/usage.ts): `src/usage.ts`
- [JSON validation](https://github.com/javepreem/pi-worker-graph/blob/main/src/json.ts): `src/json.ts`

### Run state

- [Coordination](https://github.com/javepreem/pi-worker-graph/blob/main/src/coordination.ts): `src/coordination.ts`
- [Run store](https://github.com/javepreem/pi-worker-graph/blob/main/src/store.ts): `src/store.ts`

### Other components

- **Parent agent**

## Connections

- Parent agent → Extension tools: invokes tools (evidence: `README.md`)
- Extension tools → Configuration: loads settings (evidence: `src/extension.ts`)
- Extension tools → Orchestration: registers tool (evidence: `src/extension.ts`)
- Extension tools → Coordination: imports (evidence: `src/extension.ts`)
- Orchestration → Configuration: loads profiles (evidence: `src/orchestrator.ts`)
- Orchestration → Graph runner: runs graph (evidence: `src/orchestrator.ts`)
- Orchestration → Pi subprocess: configures executor (evidence: `src/orchestrator.ts`)
- Orchestration → Checks and review: configures checks (evidence: `src/orchestrator.ts`)
- Orchestration → Run store: accesses run state (evidence: `src/orchestrator.ts`)
- Graph runner → DAG primitives: schedules tasks (evidence: `src/run.ts`)
- Graph runner → Prerequisite context: serializes prerequisites (evidence: `src/run.ts`)
- Graph runner → Run store: reads and publishes (evidence: `src/run.ts`)
- Graph runner → Worker reports: validates outputs (evidence: `src/run.ts`)
- Pi subprocess → Checks and review: runs checks (evidence: `src/pi-subprocess.ts`)
- Pi subprocess → Worker reports: parses tool result (evidence: `src/pi-subprocess.ts`)
- Prerequisite context → Worker reports: validates reports (evidence: `src/context.ts`)
- Execution failures → Usage accounting: validates usage (evidence: `src/execution-failure.ts`)
- Run store → Worker reports: parses artifacts (evidence: `src/store.ts`)
- Run store → Usage accounting: parses accounting (evidence: `src/store.ts`)
- Coordination → Run store: persists coordination (evidence: `src/coordination.ts`)
- Configuration → Pi subprocess: parses profiles (evidence: `src/config.ts`)
