# shrec/aiworkhub architecture

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

- Interactive diagram: https://gitdiagram.com/shrec/aiworkhub
- Repository: https://github.com/shrec/aiworkhub

## Overview

AIWorkHub is a local-first control plane for multi-model coding agents, surfaced through VS Code and MCP. Its principal loop is to capture repository work, plan dependency-aware tasks, route and launch isolated workers, validate and review their changes, promote accepted work, and retain outcomes and project context for future decisions. The graph preserves documented intake, source intelligence, durable memory, review, and learning capabilities. Relationship evidence is limited to the README and SOURCE INDEX references; unsampled implementation wiring is not asserted.

Main entry points: [`src/aiworkhub/manager_loop.py`](https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/manager_loop.py) (Manager loop), [`src/aiworkhub/process_launcher.py`](https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/process_launcher.py) (Process launcher), [`src/aiworkhub/workforce_router.py`](https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/workforce_router.py) (Workforce routing), [`src/aiworkhub/task_store.py`](https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/task_store.py) (Task DAG)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_surfaces["User surfaces"]
  node_vscode["VS Code extension<br/>[extension.js]"]
  node_mcp["MCP interface<br/>[server.py]"]
end

subgraph group_planning["Planning and context"]
  node_manager["Manager loop<br/>[manager_loop.py]"]
  node_intake["NeedFix and roadmap<br/>[needfix_store.py]"]
  node_decomposition["Task decomposition"]
  node_taskqueue[("Task DAG<br/>[task_store.py]")]
  node_memorytools["Project context tools"]
  node_sourcegraph[("Source Graph<br/>[source_graph.py]")]
end

subgraph group_execution["Worker execution"]
  node_policy["Repository policy<br/>[repo_policy.py]"]
  node_catalog[("Workforce catalog")]
  node_router["Workforce routing"]
  node_launcher["Process launcher"]
  node_adapters["Runtime adapters"]
  node_workspace["Isolated worktrees"]
end

subgraph group_assurance["Verification and promotion"]
  node_validation["Validation runner"]
  node_review["Evidence-based review"]
  node_promotion["Manager promotion<br/>[task_engine.py]"]
end

subgraph group_memory["Durable authorities"]
  node_context[("Context graph<br/>[context_graph.py]")]
  node_learning["Learning commits<br/>[learning_commit.py]"]
  node_storage[("Storage registry")]
end

node_developer(("Developer"))
node_providers(("Coding model providers"))

node_developer -->|"uses"| node_vscode
node_developer -->|"uses"| node_mcp
node_vscode -.->|"manages work"| node_manager
node_mcp -.->|"exposes control"| node_manager
node_manager -->|"observes intake"| node_intake
node_manager -->|"plans tasks"| node_decomposition
node_manager -->|"coordinates DAG"| node_taskqueue
node_manager -->|"routes work"| node_router
node_manager -->|"uses context"| node_memorytools
node_memorytools -->|"queries memory"| node_context
node_manager -->|"uses intelligence"| node_sourcegraph
node_router -->|"ranks workers"| node_catalog
node_router -.->|"dispatches tasks"| node_launcher
node_launcher -->|"checks launch policy"| node_policy
node_launcher -->|"selects adapter"| node_adapters
node_adapters -->|"invokes models"| node_providers
node_launcher -->|"launches isolated"| node_workspace
node_manager -->|"verifies changes"| node_validation
node_manager -->|"requests review"| node_review
node_manager -->|"controls promotion"| node_promotion
node_promotion -->|"records decisions"| node_taskqueue
node_manager -->|"learns outcomes"| node_learning
node_context -->|"uses canonical storage"| node_storage
node_taskqueue -->|"registers authority"| node_storage

click node_vscode "https://github.com/shrec/aiworkhub/blob/main/vscode-extension/extension.js"
click node_mcp "https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/server.py"
click node_manager "https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/manager_loop.py"
click node_intake "https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/needfix_store.py"
click node_decomposition "https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/task_decomposition.py"
click node_taskqueue "https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/task_store.py"
click node_memorytools "https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/manager_ai_tools.py"
click node_context "https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/context_graph.py"
click node_sourcegraph "https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/source_graph.py"
click node_policy "https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/repo_policy.py"
click node_catalog "https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/workforce_catalog.py"
click node_router "https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/workforce_router.py"
click node_launcher "https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/process_launcher.py"
click node_adapters "https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/runtime_adapters.py"
click node_workspace "https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/worker_workspace.py"
click node_validation "https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/validation_runner.py"
click node_review "https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/review_orchestrator.py"
click node_promotion "https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/task_engine.py"
click node_learning "https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/learning_commit.py"
click node_storage "https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/storage_registry.py"

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_vscode,node_mcp toneBlue
class node_manager,node_intake,node_decomposition,node_taskqueue,node_memorytools,node_sourcegraph toneAmber
class node_policy,node_catalog,node_router,node_launcher,node_adapters,node_workspace toneMint
class node_validation,node_review,node_promotion toneRose
class node_context,node_learning,node_storage,node_developer,node_providers toneIndigo
```

## Components

### User surfaces

- [VS Code extension](https://github.com/shrec/aiworkhub/blob/main/vscode-extension/extension.js): `vscode-extension/extension.js`
- [MCP interface](https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/server.py): `src/aiworkhub/server.py`

### Planning and context

- [Manager loop](https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/manager_loop.py): `src/aiworkhub/manager_loop.py`
- [NeedFix and roadmap](https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/needfix_store.py): `src/aiworkhub/needfix_store.py`
- [Task decomposition](https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/task_decomposition.py): `src/aiworkhub/task_decomposition.py`
- [Task DAG](https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/task_store.py): `src/aiworkhub/task_store.py`
- [Project context tools](https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/manager_ai_tools.py): `src/aiworkhub/manager_ai_tools.py`
- [Source Graph](https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/source_graph.py): `src/aiworkhub/source_graph.py`

### Worker execution

- [Repository policy](https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/repo_policy.py): `src/aiworkhub/repo_policy.py`
- [Workforce catalog](https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/workforce_catalog.py): `src/aiworkhub/workforce_catalog.py`
- [Workforce routing](https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/workforce_router.py): `src/aiworkhub/workforce_router.py`
- [Process launcher](https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/process_launcher.py): `src/aiworkhub/process_launcher.py`
- [Runtime adapters](https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/runtime_adapters.py): `src/aiworkhub/runtime_adapters.py`
- [Isolated worktrees](https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/worker_workspace.py): `src/aiworkhub/worker_workspace.py`

### Verification and promotion

- [Validation runner](https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/validation_runner.py): `src/aiworkhub/validation_runner.py`
- [Evidence-based review](https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/review_orchestrator.py): `src/aiworkhub/review_orchestrator.py`
- [Manager promotion](https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/task_engine.py): `src/aiworkhub/task_engine.py`

### Durable authorities

- [Context graph](https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/context_graph.py): `src/aiworkhub/context_graph.py`
- [Learning commits](https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/learning_commit.py): `src/aiworkhub/learning_commit.py`
- [Storage registry](https://github.com/shrec/aiworkhub/blob/main/src/aiworkhub/storage_registry.py): `src/aiworkhub/storage_registry.py`

### Other components

- **Developer**
- **Coding model providers**

## Connections

- Developer → VS Code extension: uses (evidence: `README.md`)
- Developer → MCP interface: uses (evidence: `README.md`)
- VS Code extension → Manager loop: manages work
- MCP interface → Manager loop: exposes control
- Manager loop → NeedFix and roadmap: observes intake (evidence: `README.md`)
- Manager loop → Task decomposition: plans tasks (evidence: `README.md`)
- Manager loop → Task DAG: coordinates DAG (evidence: `README.md`)
- Manager loop → Workforce routing: routes work (evidence: `README.md`)
- Manager loop → Project context tools: uses context (evidence: `src/aiworkhub/manager_loop.py`)
- Project context tools → Context graph: queries memory (evidence: `src/aiworkhub/manager_ai_tools.py`)
- Manager loop → Source Graph: uses intelligence (evidence: `README.md`)
- Workforce routing → Workforce catalog: ranks workers (evidence: `src/aiworkhub/workforce_catalog.py`)
- Workforce routing → Process launcher: dispatches tasks
- Process launcher → Repository policy: checks launch policy (evidence: `src/aiworkhub/repo_policy.py`)
- Process launcher → Runtime adapters: selects adapter
- Runtime adapters → Coding model providers: invokes models (evidence: `README.md`)
- Process launcher → Isolated worktrees: launches isolated (evidence: `README.md`)
- Manager loop → Validation runner: verifies changes (evidence: `README.md`)
- Manager loop → Evidence-based review: requests review (evidence: `README.md`)
- Manager loop → Manager promotion: controls promotion (evidence: `README.md`)
- Manager promotion → Task DAG: records decisions (evidence: `src/aiworkhub/task_engine.py`)
- Manager loop → Learning commits: learns outcomes (evidence: `README.md`)
- Context graph → Storage registry: uses canonical storage (evidence: `src/aiworkhub/context_graph.py`)
- Task DAG → Storage registry: registers authority (evidence: `src/aiworkhub/task_store.py`)
