# saatsky/hierarchy_pai architecture

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

- Interactive diagram: https://gitdiagram.com/saatsky/hierarchy_pai
- Repository: https://github.com/saatsky/hierarchy_pai

## Overview

Hierarchical Planner AI is a Phoenix LiveView application for turning a user goal into a reviewed, dependency-aware plan, executing steps in parallel with specialist agents, and synthesizing the results. The UI also supports saved/imported plans, skills, model and specialist overrides, recovery, and live progress. MCP provides both an inbound tool endpoint and optional outbound tools for step execution. The main workflow is documented in the README; sampled source confirms the web routing, MCP bridge, synchronous pipeline wrapper, and supervised in-memory stores. Unsampled internals are represented only where documented.

Main entry points: [`lib/hierarchy_pai_web/live/planner_live.ex`](https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai_web/live/planner_live.ex) (Planner UI), [`lib/hierarchy_pai/agents/executor.ex`](https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai/agents/executor.ex) (Step executor), [`lib/hierarchy_pai/orchestrator.ex`](https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai/orchestrator.ex) (Wave orchestrator), [`lib/hierarchy_pai_web/router.ex`](https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai_web/router.ex) (Web router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interaction"]
  node_live["Planner UI<br/>[planner_live.ex]"]
  node_router["Web router<br/>[router.ex]"]
  node_components["UI components<br/>[core_components.ex]"]
end

subgraph group_planning["Plan and execute"]
  node_planner["Planner agent<br/>[planner.ex]"]
  node_registry["Specialist registry<br/>[agent_registry.ex]"]
  node_orchestrator["Wave orchestrator<br/>[orchestrator.ex]"]
  node_executor["Step executor<br/>[executor.ex]"]
  node_aggregator["Result aggregator<br/>[aggregator.ex]"]
  node_taskrunner["Task runner<br/>[task_runner.ex]"]
  node_discovery["Task discovery<br/>[discovery.ex]"]
  node_domain["Domain handling<br/>[domain.ex]"]
end

subgraph group_state["Configuration and state"]
  node_llm["LLM provider<br/>[llm_provider.ex]"]
  node_providers[("Provider settings<br/>[provider_store.ex]")]
  node_plans[("Saved plans<br/>[plan_store.ex]")]
  node_runs[("Run state<br/>[run_store.ex]")]
  node_skills[("Skill packages<br/>[skill_store.ex]")]
end

subgraph group_mcp["MCP interfaces"]
  node_mcpservers[("MCP server registry")]
  node_mcpclient["MCP client<br/>[mcp_client.ex]"]
  node_pipeline["Synchronous pipeline<br/>[pipeline_runner.ex]"]
  node_mcprouter["MCP endpoint<br/>[mcp_router.ex]"]
end

node_user(("User"))
node_mcpconsumer(("MCP-compatible agent"))
node_llmservice{{"LLM services"}}

node_user -->|"submits goal"| node_live
node_router -->|"routes UI"| node_live
node_live -->|"requests plan"| node_planner
node_planner -->|"assigns specialists"| node_registry
node_live -->|"saves and loads"| node_plans
node_live -->|"assigns skills"| node_skills
node_live -->|"starts execution"| node_orchestrator
node_orchestrator -->|"dispatches steps"| node_executor
node_executor -->|"uses specialist"| node_registry
node_executor -->|"uses skill"| node_skills
node_executor -.->|"calls step tools"| node_mcpclient
node_executor -.->|"builds model"| node_llm
node_llm -->|"calls provider"| node_llmservice
node_orchestrator -->|"synthesizes outputs"| node_aggregator
node_aggregator -.->|"builds model"| node_llm
node_live -->|"configures providers"| node_providers
node_live -.->|"tracks progress"| node_runs
node_live -.->|"renders UI"| node_components
node_mcpconsumer -->|"calls MCP endpoint"| node_router
node_router -->|"forwards MCP"| node_mcprouter
node_mcprouter -.->|"dispatches tools"| node_pipeline
node_pipeline -->|"starts pipeline"| node_orchestrator
node_pipeline -->|"updates run"| node_runs
node_mcpclient -.->|"uses server config"| node_mcpservers
node_discovery -.->|"supports task flow"| node_taskrunner
node_domain -.->|"supports task flow"| node_taskrunner

click node_live "https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai_web/live/planner_live.ex"
click node_router "https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai_web/router.ex"
click node_components "https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai_web/components/core_components.ex"
click node_planner "https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai/agents/planner.ex"
click node_registry "https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai/agents/agent_registry.ex"
click node_orchestrator "https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai/orchestrator.ex"
click node_executor "https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai/agents/executor.ex"
click node_aggregator "https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai/agents/aggregator.ex"
click node_taskrunner "https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai/pipeline/task_runner.ex"
click node_discovery "https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai/pipeline/discovery.ex"
click node_domain "https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai/pipeline/domain.ex"
click node_llm "https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai/llm_provider.ex"
click node_providers "https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai/provider_store.ex"
click node_plans "https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai/plan_store.ex"
click node_runs "https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai/run_store.ex"
click node_skills "https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai/skill_store.ex"
click node_mcpservers "https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai/mcp_server_store.ex"
click node_mcpclient "https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai/mcp_client.ex"
click node_pipeline "https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai/pipeline/pipeline_runner.ex"
click node_mcprouter "https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai_web/plugs/mcp_router.ex"

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_live,node_router,node_components,node_user toneBlue
class node_planner,node_registry,node_orchestrator,node_executor,node_aggregator,node_taskrunner,node_discovery,node_domain toneAmber
class node_llm,node_providers,node_plans,node_runs,node_skills toneMint
class node_mcpservers,node_mcpclient,node_pipeline,node_mcprouter toneRose
class node_mcpconsumer,node_llmservice toneIndigo
```

## Components

### Web interaction

- [Planner UI](https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai_web/live/planner_live.ex): `lib/hierarchy_pai_web/live/planner_live.ex`
- [Web router](https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai_web/router.ex): `lib/hierarchy_pai_web/router.ex`
- [UI components](https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai_web/components/core_components.ex): `lib/hierarchy_pai_web/components/core_components.ex`

### Plan and execute

- [Planner agent](https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai/agents/planner.ex): `lib/hierarchy_pai/agents/planner.ex`
- [Specialist registry](https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai/agents/agent_registry.ex): `lib/hierarchy_pai/agents/agent_registry.ex`
- [Wave orchestrator](https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai/orchestrator.ex): `lib/hierarchy_pai/orchestrator.ex`
- [Step executor](https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai/agents/executor.ex): `lib/hierarchy_pai/agents/executor.ex`
- [Result aggregator](https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai/agents/aggregator.ex): `lib/hierarchy_pai/agents/aggregator.ex`
- [Task runner](https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai/pipeline/task_runner.ex): `lib/hierarchy_pai/pipeline/task_runner.ex`
- [Task discovery](https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai/pipeline/discovery.ex): `lib/hierarchy_pai/pipeline/discovery.ex`
- [Domain handling](https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai/pipeline/domain.ex): `lib/hierarchy_pai/pipeline/domain.ex`

### Configuration and state

- [LLM provider](https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai/llm_provider.ex): `lib/hierarchy_pai/llm_provider.ex`
- [Provider settings](https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai/provider_store.ex): `lib/hierarchy_pai/provider_store.ex`
- [Saved plans](https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai/plan_store.ex): `lib/hierarchy_pai/plan_store.ex`
- [Run state](https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai/run_store.ex): `lib/hierarchy_pai/run_store.ex`
- [Skill packages](https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai/skill_store.ex): `lib/hierarchy_pai/skill_store.ex`

### MCP interfaces

- [MCP server registry](https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai/mcp_server_store.ex): `lib/hierarchy_pai/mcp_server_store.ex`
- [MCP client](https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai/mcp_client.ex): `lib/hierarchy_pai/mcp_client.ex`
- [Synchronous pipeline](https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai/pipeline/pipeline_runner.ex): `lib/hierarchy_pai/pipeline/pipeline_runner.ex`
- [MCP endpoint](https://github.com/saatsky/hierarchy_pai/blob/main/lib/hierarchy_pai_web/plugs/mcp_router.ex): `lib/hierarchy_pai_web/plugs/mcp_router.ex`

### Other components

- **User**
- **MCP-compatible agent**
- **LLM services**

## Connections

- User → Planner UI: submits goal
- Web router → Planner UI: routes UI (evidence: `lib/hierarchy_pai_web/router.ex`)
- Planner UI → Planner agent: requests plan
- Planner agent → Specialist registry: assigns specialists
- Planner UI → Saved plans: saves and loads
- Planner UI → Skill packages: assigns skills
- Planner UI → Wave orchestrator: starts execution
- Wave orchestrator → Step executor: dispatches steps
- Step executor → Specialist registry: uses specialist
- Step executor → Skill packages: uses skill
- Step executor → MCP client: calls step tools
- Step executor → LLM provider: builds model (evidence: `lib/hierarchy_pai/llm_provider.ex`)
- LLM provider → LLM services: calls provider
- Wave orchestrator → Result aggregator: synthesizes outputs
- Result aggregator → LLM provider: builds model (evidence: `lib/hierarchy_pai/llm_provider.ex`)
- Planner UI → Provider settings: configures providers
- Planner UI → Run state: tracks progress
- Planner UI → UI components: renders UI
- MCP-compatible agent → Web router: calls MCP endpoint
- Web router → MCP endpoint: forwards MCP (evidence: `lib/hierarchy_pai_web/router.ex`)
- MCP endpoint → Synchronous pipeline: dispatches tools
- Synchronous pipeline → Wave orchestrator: starts pipeline (evidence: `lib/hierarchy_pai/pipeline/pipeline_runner.ex`)
- Synchronous pipeline → Run state: updates run (evidence: `lib/hierarchy_pai/pipeline/pipeline_runner.ex`)
- MCP client → MCP server registry: uses server config
- Task discovery → Task runner: supports task flow
- Domain handling → Task runner: supports task flow
