Skip to content

ARCHITECTURE-DIAGRAM.md

Latest commit

 

History

History
278 lines (220 loc) · 9.79 KB

ARCHITECTURE-DIAGRAM.md

File metadata and controls

278 lines (220 loc) · 9.79 KB

HCA Architecture Diagram

Holonic Compound Architecture (HCA) v0.1 - Proof of Concept

This diagram represents the complete HCA architecture as specified in SPEC.md.

System Overview

flowchart TB
  %% =========================
  %%  Holonic Compound Architecture (HCA)
  %%  Protocols: ACP (northbound), A2A (coordination), MCP (tools), OpenHands (runtime)
  %%  Key: Compound Loop + Knowledge Base for cross-task learning
  %% =========================

  %% ---- Client / Human surface (ACP Northbound Boundary) ----
  subgraph ClientSurface["External Clients (ACP Northbound Boundary)"]
    IDE["IDE / VS Code"]
    CLI["CLI Client"]
    WEBUI["Web UI"]
  end

  %% ---- Root Holon: Gateway + Mission Control ----
  subgraph RootHolon["Root Holon"]
    direction TB
    ACPGW["ACP Gateway<br/>(JSON-RPC: stdio/ws/http)<br/>• Task submission<br/>• Status streaming<br/>• Artifact retrieval"]
    ROOT["Root Agent<br/>• Mission control<br/>• Global policy enforcement<br/>• Conflict arbitration<br/>• Task decomposition"]
    KB["Knowledge Base<br/>• Patterns (what works)<br/>• Anti-patterns (what fails)<br/>• Lessons from COMPOUND phase<br/>• Cross-task learning"]

    ACPGW <--> ROOT
    ROOT <--> KB
  end

  IDE <-->|ACP| ACPGW
  CLI <-->|ACP| ACPGW
  WEBUI <-->|ACP| ACPGW

  %% ---- Domain Holons: Coordination Layer ----
  subgraph DomainHolons["Domain Holons (A2A Coordination Boundary)"]
    direction TB

    subgraph EngDomain["Engineering Domain"]
      CODEH["Engineering Lead<br/>• Decomposes dev tasks<br/>• Delegates to leaf agents<br/>• Aggregates artifacts"]
    end

    subgraph QADomain["QA Domain"]
      QAH["QA Lead<br/>• Coordinates reviews<br/>• Manages evaluators<br/>• Aggregates verdicts"]
    end

    subgraph DataDomain["Data/Research Domain"]
      DATAH["Research Lead<br/>• Coordinates research<br/>• Manages context gathering<br/>• Aggregates findings"]
    end
  end

  %% A2A delegation from Root (Authority flows DOWN)
  ROOT <-->|"A2A: hca/task/delegate<br/>Constraints: goals, budget, policies"| CODEH
  ROOT <-->|"A2A: hca/task/delegate<br/>Constraints: goals, budget, policies"| QAH
  ROOT <-->|"A2A: hca/task/delegate<br/>Constraints: goals, budget, policies"| DATAH

  %% ---- Leaf Agents (Executors) - Execute Compound Loop ----
  subgraph LeafAgents["Leaf Holons (Execute Compound Loop)"]
    direction TB

    subgraph CodeLeaves["Code Executors"]
      CODE1["Dev Agent<br/>PLAN→WORK→REVIEW→REVISE"]
      CODE2["Refactor Agent<br/>PLAN→WORK→REVIEW→REVISE"]
    end

    subgraph QALeaves["QA Executors"]
      QA1["Test Agent<br/>PLAN→WORK→REVIEW→REVISE"]
      QA2["Evaluator Agent<br/>(Separate reviewer)<br/>Produces Verdicts"]
    end

    subgraph DataLeaves["Research Executors"]
      DATA1["Research Agent<br/>PLAN→WORK→REVIEW→REVISE"]
    end
  end

  %% A2A within domains
  CODEH <-->|"A2A: delegate"| CODE1
  CODEH <-->|"A2A: delegate"| CODE2
  QAH <-->|"A2A: delegate"| QA1
  QAH <-->|"A2A: delegate"| QA2
  DATAH <-->|"A2A: delegate"| DATA1

  %% Cross-domain review (Producer ≠ Reviewer - SPEC requirement)
  CODE1 -.->|"A2A: hca/review/request<br/>(Producer → Evaluator)"| QA2
  QA2 -.->|"A2A: hca/review/verdict<br/>(pass/fail/partial + evidence)"| CODE1

  %% Results flow UP
  CODE1 -->|"A2A: hca/task/complete<br/>Artifacts + Status"| CODEH
  CODE2 -->|"A2A: hca/task/complete"| CODEH
  QA1 -->|"A2A: hca/task/complete<br/>Test reports"| QAH
  QA2 -->|"A2A: Verdicts"| QAH
  DATA1 -->|"A2A: hca/task/complete<br/>Research notes"| DATAH

  CODEH -->|"A2A: Aggregated artifacts"| ROOT
  QAH -->|"A2A: Aggregated verdicts"| ROOT
  DATAH -->|"A2A: Context/evidence"| ROOT

  %% Knowledge contribution (COMPOUND phase)
  CODE1 -.->|"hca/knowledge/contribute<br/>Lessons learned"| KB
  QA2 -.->|"hca/knowledge/contribute<br/>Review patterns"| KB

  %% Knowledge query (PLAN phase)
  KB -.->|"hca/knowledge/query<br/>Relevant lessons"| CODE1
  KB -.->|"hca/knowledge/query"| CODE2

  %% ---- Tool Plane (MCP Tool Boundary) ----
  subgraph ToolPlane["Tool Plane (MCP Tool Boundary)"]
    direction TB
    MCPHOST["MCP Client<br/>(embedded in Leaf Holons)"]

    subgraph MCPServers["MCP Tool Servers"]
      MCPFS["Filesystem/Git Server<br/>• File operations<br/>• Git commands"]
      MCPLSP["LSP Server<br/>• Code intelligence<br/>• Diagnostics"]
      MCPHTTP["HTTP/API Server<br/>• External APIs<br/>• Linear, GitHub, etc."]
      MCPVAULT["Secrets Server<br/>• Policy enforcement<br/>• Credential access"]
    end
  end

  %% Leaf agents use MCP for tool access
  CODE1 -->|"MCP: tools/call"| MCPHOST
  CODE2 -->|"MCP: tools/call"| MCPHOST
  QA1 -->|"MCP: tools/call"| MCPHOST
  DATA1 -->|"MCP: tools/call"| MCPHOST

  MCPHOST --> MCPFS
  MCPHOST --> MCPLSP
  MCPHOST --> MCPHTTP
  MCPHOST --> MCPVAULT

  %% ---- Runtime Substrate (OpenHands) ----
  subgraph Runtime["OpenHands Runtime (Execution Substrate)"]
    direction TB
    OHSVC["OpenHands Agent Server<br/>• Session lifecycle<br/>• Resource allocation<br/>• Artifact persistence"]

    subgraph SessionPool["Session Pool"]
      S1["Sandbox A<br/>Dev Agent session<br/>• Workspace<br/>• Logs<br/>• Artifacts"]
      S2["Sandbox B<br/>Test Agent session"]
      S3["Sandbox C<br/>Research session"]
    end

    ARTIFACTS["Artifact Store<br/>• Versioned outputs<br/>• Lineage tracking"]
  end

  %% Leaf agents run in sandboxed sessions
  CODE1 -->|"Runtime: create session"| OHSVC
  CODE2 -->|"Runtime: create session"| OHSVC
  QA1 -->|"Runtime: create session"| OHSVC
  DATA1 -->|"Runtime: create session"| OHSVC

  OHSVC --> S1
  OHSVC --> S2
  OHSVC --> S3
  OHSVC --> ARTIFACTS

  %% Tools execute within sandboxes
  S1 ---|"Workspace access"| MCPFS
  S1 ---|"Code intel"| MCPLSP
  S2 ---|"Test execution"| MCPFS
  S3 ---|"API access"| MCPHTTP

  %% Style definitions
  classDef rootStyle fill:#e1f5fe,stroke:#01579b,stroke-width:2px
  classDef domainStyle fill:#fff3e0,stroke:#e65100,stroke-width:2px
  classDef leafStyle fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
  classDef toolStyle fill:#fce4ec,stroke:#880e4f,stroke-width:2px
  classDef runtimeStyle fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
  classDef clientStyle fill:#eceff1,stroke:#37474f,stroke-width:2px

  class ROOT,ACPGW,KB rootStyle
  class CODEH,QAH,DATAH domainStyle
  class CODE1,CODE2,QA1,QA2,DATA1 leafStyle
  class MCPHOST,MCPFS,MCPLSP,MCPHTTP,MCPVAULT toolStyle
  class OHSVC,S1,S2,S3,ARTIFACTS runtimeStyle
  class IDE,CLI,WEBUI clientStyle
Loading

Compound Loop Detail

flowchart TB
  %% Inner Loop: Per-Task Iteration
  PLAN["1. PLAN<br/>Query Knowledge Base<br/>Create implementation plan<br/>Define acceptance criteria<br/>Allocate budget"]
  WORK["2. WORK<br/>Execute plan<br/>Invoke tools via MCP<br/>Run in sandbox<br/>Produce artifacts"]
  REVIEW["3. REVIEW<br/>Separate Evaluator Holon<br/>Check acceptance criteria<br/>Run tests/lints<br/>Produce Verdict"]
  DECISION{"4. VERDICT?"}
  REVISE["REVISE<br/>Analyze feedback<br/>Update plan"]
  ACCEPT["ACCEPT<br/>Artifacts finalized"]
  ESCALATE["ESCALATE<br/>Return to parent<br/>with evidence"]

  %% Inner Loop Flow
  PLAN --> WORK
  WORK --> REVIEW
  REVIEW --> DECISION
  DECISION -->|PASS| ACCEPT
  DECISION -->|"FAIL + retries remain"| REVISE
  DECISION -->|"FAIL + no retries"| ESCALATE
  REVISE --> PLAN

  %% Outer Loop: Learning Accumulation
  COMPOUND["5. COMPOUND<br/>Extract lessons<br/>Classify patterns/anti-patterns<br/>Update Knowledge Base"]
  KB["Knowledge Base<br/>Future PLAN phases query this<br/>Each task improves next task"]

  %% Outer Loop Flow
  ACCEPT --> COMPOUND
  ESCALATE -.-> COMPOUND
  COMPOUND --> KB
  KB -.->|"Informs future tasks"| PLAN

  %% Styling
  style PLAN fill:#bbdefb,stroke:#1565c0
  style WORK fill:#c8e6c9,stroke:#2e7d32
  style REVIEW fill:#ffecb3,stroke:#f57c00
  style DECISION fill:#fff9c4,stroke:#fbc02d
  style ACCEPT fill:#c8e6c9,stroke:#2e7d32
  style ESCALATE fill:#ffcdd2,stroke:#c62828
  style REVISE fill:#ffe0b2,stroke:#ef6c00
  style COMPOUND fill:#e1bee7,stroke:#7b1fa2
  style KB fill:#f3e5f5,stroke:#7b1fa2
Loading

Protocol Boundary Summary

flowchart LR
  subgraph North["Northbound - ACP"]
    N1["Human/IDE to System<br/>Task submission<br/>Status streaming<br/>Artifact retrieval"]
  end

  subgraph Coord["Coordination - A2A"]
    C1["Holon to Holon<br/>hca/task/delegate<br/>hca/task/negotiate<br/>hca/review/request<br/>hca/knowledge/contribute"]
  end

  subgraph Tool["Tool - MCP"]
    T1["Holon to Tools<br/>tools/list<br/>tools/call<br/>Policy enforcement"]
  end

  subgraph Run["Runtime - OpenHands"]
    R1["Holon to Substrate<br/>Session management<br/>Sandboxed execution<br/>Artifact persistence"]
  end

  N1 --> C1 --> T1 --> R1
Loading

Data Flow Summary

Direction What Flows Protocol
DOWN (Authority) Goals, Constraints, Budgets, Policies A2A: hca/task/delegate
UP (Results) Artifacts, Verdicts, Status, Escalations A2A: hca/task/complete, hca/task/escalate
LATERAL (Review) Review requests, Verdicts A2A: hca/review/request, hca/review/verdict
LATERAL (Learning) Lessons to/from Knowledge Base A2A: hca/knowledge/contribute, hca/knowledge/query

Key HCA Invariants Shown

  1. Producer ≠ Reviewer: Code agents (CODE1) send review requests to separate Evaluator agents (QA2)
  2. Compound Loop Required: Every leaf holon executes PLAN→WORK→REVIEW→REVISE
  3. Knowledge Base: Central to cross-task learning, queried in PLAN, updated in COMPOUND
  4. Constraint-Based Authority: Root provides constraints, holons decide how to achieve goals
  5. Protocol Separation: Clear boundaries (ACP/A2A/MCP/Runtime)
  6. Sandboxed Execution: All work happens in OpenHands sessions

This diagram is part of the Holonic Compound Architecture (HCA) Specification v0.1