# bhangun/andalus architecture

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

- Interactive diagram: https://gitdiagram.com/bhangun/andalus
- Repository: https://github.com/bhangun/andalus

## Overview

Andalus Runtime executes autonomous agents and workflows. The principal workflow begins with a CLI or REST invocation, passes into agent execution and orchestration, and produces an execution result; the README also documents programmatic execution and standalone runners. Runtime capabilities include memory/context, guardrails, human approval, knowledge and graph operations, sandboxing, and operational visibility. The source excerpts confirm selected execution, memory retrieval, HITL query/notification, and operator-service behavior. Several branches are documented but their wiring was not sampled, so those links are documented at the README level rather than inferred from module names.

Main entry points: [`runtime/andalus-runtime-core/src/main/java/tech/kayys/andalus/execution/AgentExecutionService.java`](https://github.com/bhangun/andalus/blob/main/runtime/andalus-runtime-core/src/main/java/tech/kayys/andalus/execution/AgentExecutionService.java) (Agent execution), [`runtime/andalus-runtime-core/src/main/java/tech/kayys/andalus/execution/DefaultExecutionEngine.java`](https://github.com/bhangun/andalus/blob/main/runtime/andalus-runtime-core/src/main/java/tech/kayys/andalus/execution/DefaultExecutionEngine.java) (Execution engine), [`runtime/andalus-hitl-runtime/src/main/java/tech/kayys/andalus/hitl/service/HumanTaskService.java`](https://github.com/bhangun/andalus/blob/main/runtime/andalus-hitl-runtime/src/main/java/tech/kayys/andalus/hitl/service/HumanTaskService.java) (Human tasks), [`cli/andalus-cli/src/main/java/tech/kayys/andalus/cli/AndalusGollekCli.java`](https://github.com/bhangun/andalus/blob/main/cli/andalus-cli/src/main/java/tech/kayys/andalus/cli/AndalusGollekCli.java) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Application interfaces"]
  node_cli["CLI"]
  node_rest["REST API<br/>[AgentResource.java]"]
  node_grpc["gRPC API"]
end

subgraph group_execution["Execution and orchestration"]
  node_agentexec["Agent execution"]
  node_execengine["Execution engine"]
  node_coordination["Coordination engine"]
  node_workflow["Workflow backend"]
end

subgraph group_governance["Governance and operations"]
  node_guardrails["Guardrails"]
  node_hitl["Human tasks"]
  node_taskquery["Task queries"]
  node_notifications["Task notifications"]
  node_sandbox["Sandbox runtime"]
  node_hermes["Operations and diagnostics"]
end

subgraph group_context["Memory and knowledge"]
  node_memory["Memory service"]
  node_context["Context engineering"]
  node_embedding["Embedding provider"]
  node_knowledge["Knowledge runtime"]
  node_graph["Graph runtime"]
  node_rag["RAG pipeline"]
end

subgraph group_integration["Backends and tools"]
  node_gamelan["Gamelan adapter"]
  node_mcp["MCP tool integration"]
end

node_user(("Agent user"))
node_llm{{"Inference provider"}}
node_result["Execution result"]

node_user -->|"invokes"| node_cli
node_user -->|"invokes"| node_rest
node_cli -.->|"starts execution"| node_agentexec
node_rest -.->|"starts execution"| node_agentexec
node_agentexec -->|"runs pipeline"| node_execengine
node_execengine -->|"returns result"| node_result
node_execengine -->|"executes workflow"| node_workflow
node_execengine -.->|"dispatches tools"| node_mcp
node_coordination -->|"uses backend"| node_gamelan
node_agentexec -->|"uses memory"| node_memory
node_context -->|"requests vectors"| node_embedding
node_agentexec -->|"applies policies"| node_guardrails
node_agentexec -->|"requests approval"| node_hitl
node_hitl -.->|"queries tasks"| node_taskquery
node_hitl -->|"sends notices"| node_notifications
node_user -.->|"invokes"| node_grpc
node_knowledge -->|"uses graph store"| node_graph
node_agentexec -.->|"uses retrieval"| node_rag
node_user -.->|"operates runtime"| node_sandbox
node_user -.->|"checks operations"| node_hermes
node_agentexec -->|"requests inference"| node_llm
node_agentexec -->|"coordinates agents"| node_coordination

click node_cli "https://github.com/bhangun/andalus/blob/main/cli/andalus-cli/src/main/java/tech/kayys/andalus/cli/AndalusGollekCli.java"
click node_rest "https://github.com/bhangun/andalus/blob/main/api/andalus-api-rest/src/main/java/tech/kayys/andalus/api/rest/AgentResource.java"
click node_grpc "https://github.com/bhangun/andalus/blob/main/api/andalus-api-grpc/src/main/java/tech/kayys/andalus/api/grpc/AndalusGrpcService.java"
click node_agentexec "https://github.com/bhangun/andalus/blob/main/runtime/andalus-runtime-core/src/main/java/tech/kayys/andalus/execution/AgentExecutionService.java"
click node_execengine "https://github.com/bhangun/andalus/blob/main/runtime/andalus-runtime-core/src/main/java/tech/kayys/andalus/execution/DefaultExecutionEngine.java"
click node_coordination "https://github.com/bhangun/andalus/blob/main/runtime/andalus-runtime-core/src/main/java/tech/kayys/andalus/coordination/CoordinationExecutionEngine.java"
click node_workflow "https://github.com/bhangun/andalus/blob/main/runtime/andalus-workflow-runtime/src/main/java/tech/kayys/andalus/agent/integration/gamelan/AgentGamelanService.java"
click node_gamelan "https://github.com/bhangun/andalus/blob/main/runtime/andalus-backend-gamelan/src/main/java/tech/kayys/andalus/agent/backend/gamelan/GamelanCoordinationExecutionEngine.java"
click node_memory "https://github.com/bhangun/andalus/blob/main/runtime/andalus-agent-runtime/src/main/java/tech/kayys/andalus/agent/core/memory/AgentMemoryService.java"
click node_context "https://github.com/bhangun/andalus/blob/main/runtime/andalus-memory-runtime/src/main/java/tech/kayys/andalus/memory/service/ContextEngineeringService.java"
click node_embedding "https://github.com/bhangun/andalus/blob/main/runtime/andalus-memory-runtime/src/main/java/tech/kayys/andalus/memory/spi/EmbeddingService.java"
click node_knowledge "https://github.com/bhangun/andalus/blob/main/runtime/andalus-knowledge-runtime/src/main/java/tech/kayys/andalus/knowledge/DefaultKnowledgeMutationService.java"
click node_graph "https://github.com/bhangun/andalus/blob/main/runtime/andalus-graph-runtime/src/main/java/tech/kayys/andalus/graph/runtime/GraphQueryExecutor.java"
click node_rag "https://github.com/bhangun/andalus/blob/main/runtime/andalus-rag-runtime/src/main/java/tech/kayys/andalus/rag/runtime/pipeline/DefaultRagPipeline.java"
click node_guardrails "https://github.com/bhangun/andalus/blob/main/runtime/andalus-guardrails-runtime/src/main/java/tech/kayys/andalus/guardrails/policy/PolicyBasedGuardrailsEngine.java"
click node_hitl "https://github.com/bhangun/andalus/blob/main/runtime/andalus-hitl-runtime/src/main/java/tech/kayys/andalus/hitl/service/HumanTaskService.java"
click node_taskquery "https://github.com/bhangun/andalus/blob/main/runtime/andalus-hitl-runtime/src/main/java/tech/kayys/andalus/hitl/repository/HumanTaskQueryService.java"
click node_notifications "https://github.com/bhangun/andalus/blob/main/runtime/andalus-hitl-runtime/src/main/java/tech/kayys/andalus/hitl/service/NotificationService.java"
click node_sandbox "https://github.com/bhangun/andalus/blob/main/runtime/andalus-sandbox/src/main/java/tech/kayys/andalus/operator/runtime/sandbox/DefaultSandboxOperatorService.java"
click node_hermes "https://github.com/bhangun/andalus/blob/main/modules/andalus-hermes/src/main/java/tech/kayys/andalus/hermes/HermesOperationalService.java"
click node_mcp "https://github.com/bhangun/andalus/blob/main/modules/tool/andalus-tool-mcp/src/main/java/tech/kayys/andalus/tool/mcp/McpServerActionPreviewService.java"

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_cli,node_rest,node_grpc,node_user toneBlue
class node_agentexec,node_execengine,node_coordination,node_workflow toneAmber
class node_guardrails,node_hitl,node_taskquery,node_notifications,node_sandbox,node_hermes toneMint
class node_memory,node_context,node_embedding,node_knowledge,node_graph,node_rag toneRose
class node_gamelan,node_mcp,node_llm,node_result toneIndigo
```

## Components

### Application interfaces

- [CLI](https://github.com/bhangun/andalus/blob/main/cli/andalus-cli/src/main/java/tech/kayys/andalus/cli/AndalusGollekCli.java): `cli/andalus-cli/src/main/java/tech/kayys/andalus/cli/AndalusGollekCli.java`
- [REST API](https://github.com/bhangun/andalus/blob/main/api/andalus-api-rest/src/main/java/tech/kayys/andalus/api/rest/AgentResource.java): `api/andalus-api-rest/src/main/java/tech/kayys/andalus/api/rest/AgentResource.java`
- [gRPC API](https://github.com/bhangun/andalus/blob/main/api/andalus-api-grpc/src/main/java/tech/kayys/andalus/api/grpc/AndalusGrpcService.java): `api/andalus-api-grpc/src/main/java/tech/kayys/andalus/api/grpc/AndalusGrpcService.java`

### Execution and orchestration

- [Agent execution](https://github.com/bhangun/andalus/blob/main/runtime/andalus-runtime-core/src/main/java/tech/kayys/andalus/execution/AgentExecutionService.java): `runtime/andalus-runtime-core/src/main/java/tech/kayys/andalus/execution/AgentExecutionService.java`
- [Execution engine](https://github.com/bhangun/andalus/blob/main/runtime/andalus-runtime-core/src/main/java/tech/kayys/andalus/execution/DefaultExecutionEngine.java): `runtime/andalus-runtime-core/src/main/java/tech/kayys/andalus/execution/DefaultExecutionEngine.java`
- [Coordination engine](https://github.com/bhangun/andalus/blob/main/runtime/andalus-runtime-core/src/main/java/tech/kayys/andalus/coordination/CoordinationExecutionEngine.java): `runtime/andalus-runtime-core/src/main/java/tech/kayys/andalus/coordination/CoordinationExecutionEngine.java`
- [Workflow backend](https://github.com/bhangun/andalus/blob/main/runtime/andalus-workflow-runtime/src/main/java/tech/kayys/andalus/agent/integration/gamelan/AgentGamelanService.java): `runtime/andalus-workflow-runtime/src/main/java/tech/kayys/andalus/agent/integration/gamelan/AgentGamelanService.java`

### Governance and operations

- [Guardrails](https://github.com/bhangun/andalus/blob/main/runtime/andalus-guardrails-runtime/src/main/java/tech/kayys/andalus/guardrails/policy/PolicyBasedGuardrailsEngine.java): `runtime/andalus-guardrails-runtime/src/main/java/tech/kayys/andalus/guardrails/policy/PolicyBasedGuardrailsEngine.java`
- [Human tasks](https://github.com/bhangun/andalus/blob/main/runtime/andalus-hitl-runtime/src/main/java/tech/kayys/andalus/hitl/service/HumanTaskService.java): `runtime/andalus-hitl-runtime/src/main/java/tech/kayys/andalus/hitl/service/HumanTaskService.java`
- [Task queries](https://github.com/bhangun/andalus/blob/main/runtime/andalus-hitl-runtime/src/main/java/tech/kayys/andalus/hitl/repository/HumanTaskQueryService.java): `runtime/andalus-hitl-runtime/src/main/java/tech/kayys/andalus/hitl/repository/HumanTaskQueryService.java`
- [Task notifications](https://github.com/bhangun/andalus/blob/main/runtime/andalus-hitl-runtime/src/main/java/tech/kayys/andalus/hitl/service/NotificationService.java): `runtime/andalus-hitl-runtime/src/main/java/tech/kayys/andalus/hitl/service/NotificationService.java`
- [Sandbox runtime](https://github.com/bhangun/andalus/blob/main/runtime/andalus-sandbox/src/main/java/tech/kayys/andalus/operator/runtime/sandbox/DefaultSandboxOperatorService.java): `runtime/andalus-sandbox/src/main/java/tech/kayys/andalus/operator/runtime/sandbox/DefaultSandboxOperatorService.java`
- [Operations and diagnostics](https://github.com/bhangun/andalus/blob/main/modules/andalus-hermes/src/main/java/tech/kayys/andalus/hermes/HermesOperationalService.java): `modules/andalus-hermes/src/main/java/tech/kayys/andalus/hermes/HermesOperationalService.java`

### Memory and knowledge

- [Memory service](https://github.com/bhangun/andalus/blob/main/runtime/andalus-agent-runtime/src/main/java/tech/kayys/andalus/agent/core/memory/AgentMemoryService.java): `runtime/andalus-agent-runtime/src/main/java/tech/kayys/andalus/agent/core/memory/AgentMemoryService.java`
- [Context engineering](https://github.com/bhangun/andalus/blob/main/runtime/andalus-memory-runtime/src/main/java/tech/kayys/andalus/memory/service/ContextEngineeringService.java): `runtime/andalus-memory-runtime/src/main/java/tech/kayys/andalus/memory/service/ContextEngineeringService.java`
- [Embedding provider](https://github.com/bhangun/andalus/blob/main/runtime/andalus-memory-runtime/src/main/java/tech/kayys/andalus/memory/spi/EmbeddingService.java): `runtime/andalus-memory-runtime/src/main/java/tech/kayys/andalus/memory/spi/EmbeddingService.java`
- [Knowledge runtime](https://github.com/bhangun/andalus/blob/main/runtime/andalus-knowledge-runtime/src/main/java/tech/kayys/andalus/knowledge/DefaultKnowledgeMutationService.java): `runtime/andalus-knowledge-runtime/src/main/java/tech/kayys/andalus/knowledge/DefaultKnowledgeMutationService.java`
- [Graph runtime](https://github.com/bhangun/andalus/blob/main/runtime/andalus-graph-runtime/src/main/java/tech/kayys/andalus/graph/runtime/GraphQueryExecutor.java): `runtime/andalus-graph-runtime/src/main/java/tech/kayys/andalus/graph/runtime/GraphQueryExecutor.java`
- [RAG pipeline](https://github.com/bhangun/andalus/blob/main/runtime/andalus-rag-runtime/src/main/java/tech/kayys/andalus/rag/runtime/pipeline/DefaultRagPipeline.java): `runtime/andalus-rag-runtime/src/main/java/tech/kayys/andalus/rag/runtime/pipeline/DefaultRagPipeline.java`

### Backends and tools

- [Gamelan adapter](https://github.com/bhangun/andalus/blob/main/runtime/andalus-backend-gamelan/src/main/java/tech/kayys/andalus/agent/backend/gamelan/GamelanCoordinationExecutionEngine.java): `runtime/andalus-backend-gamelan/src/main/java/tech/kayys/andalus/agent/backend/gamelan/GamelanCoordinationExecutionEngine.java`
- [MCP tool integration](https://github.com/bhangun/andalus/blob/main/modules/tool/andalus-tool-mcp/src/main/java/tech/kayys/andalus/tool/mcp/McpServerActionPreviewService.java): `modules/tool/andalus-tool-mcp/src/main/java/tech/kayys/andalus/tool/mcp/McpServerActionPreviewService.java`

### Other components

- **Agent user**
- **Inference provider**
- **Execution result**

## Connections

- Agent user → CLI: invokes (evidence: `README.md`)
- Agent user → REST API: invokes (evidence: `README.md`)
- CLI → Agent execution: starts execution
- REST API → Agent execution: starts execution
- Agent execution → Execution engine: runs pipeline (evidence: `README.md`)
- Execution engine → Execution result: returns result (evidence: `README.md`)
- Execution engine → Workflow backend: executes workflow (evidence: `runtime/andalus-runtime-core/src/main/java/tech/kayys/andalus/execution/DefaultExecutionEngine.java`)
- Execution engine → MCP tool integration: dispatches tools
- Coordination engine → Gamelan adapter: uses backend (evidence: `README.md`)
- Agent execution → Memory service: uses memory (evidence: `README.md`)
- Context engineering → Embedding provider: requests vectors (evidence: `runtime/andalus-memory-runtime/src/main/java/tech/kayys/andalus/memory/service/ContextEngineeringService.java`)
- Agent execution → Guardrails: applies policies (evidence: `README.md`)
- Agent execution → Human tasks: requests approval (evidence: `README.md`)
- Human tasks → Task queries: queries tasks
- Human tasks → Task notifications: sends notices (evidence: `README.md`)
- Agent user → gRPC API: invokes
- Knowledge runtime → Graph runtime: uses graph store (evidence: `README.md`)
- Agent execution → RAG pipeline: uses retrieval
- Agent user → Sandbox runtime: operates runtime
- Agent user → Operations and diagnostics: checks operations
- Agent execution → Inference provider: requests inference (evidence: `README.md`)
- Agent execution → Coordination engine: coordinates agents (evidence: `README.md`)
