# bhangun/andalus-framework architecture

> Architecture diagram of the GitHub repository bhangun/andalus-framework, 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-framework
- Repository: https://github.com/bhangun/andalus-framework

## Overview

Andalus is a modular Java framework for building autonomous agents and workflows, intended as reusable contracts, adapters, and services beneath a separate runtime. A typical user request enters agent orchestration, invokes an agent and model or tools, and can be coordinated as a workflow; communication adapters support local and remote agents. Knowledge, security, governance, and observability are supporting capability branches. The README documents these capabilities, but sampled source does not establish most runtime wiring, so those connections are shown as unverified.

Main entry points: [`framework/andalus-agent/src/main/java/tech/kayys/andalus/agent/orchestration/AgentOrchestrator.java`](https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-agent/src/main/java/tech/kayys/andalus/agent/orchestration/AgentOrchestrator.java) (Agent Orchestrator), [`framework/andalus-communication-api/src/main/java/tech/kayys/andalus/communication/api/AgentCommunicator.java`](https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-communication-api/src/main/java/tech/kayys/andalus/communication/api/AgentCommunicator.java) (Communication API), [`framework/andalus-communication-core/src/main/java/tech/kayys/andalus/communication/core/task/TaskController.java`](https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-communication-core/src/main/java/tech/kayys/andalus/communication/core/task/TaskController.java) (Communication Core), [`framework/andalus-provider/src/main/java/tech/kayys/andalus/inference/InferenceService.java`](https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-provider/src/main/java/tech/kayys/andalus/inference/InferenceService.java) (Inference Routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent_execution["Agent Execution"]
  node_agent_api["Agent Contracts<br/>[Agent.java]"]
  node_orchestrator["Agent Orchestrator"]
  node_execution_engine["Execution Engine"]
  node_workflow_engine["Workflow Engine"]
  node_inference["Inference Routing"]
  node_provider["Model Providers<br/>[Provider.java]"]
end

subgraph group_communication["Communication"]
  node_communication_api["Communication API"]
  node_communication_core["Communication Core"]
  node_a2a["A2A Adapter"]
  node_anp_discovery["ANP Discovery"]
  node_network["Agent Network"]
end

subgraph group_tools_knowledge["Tools &amp; Knowledge"]
  node_tool_invocation["Tool Invocation"]
  node_plugin_manager["Plugin Lifecycle"]
  node_knowledge["Knowledge Services"]
  node_rag["RAG Pipeline<br/>[RagPipeline.java]"]
  node_memory["Memory Manager"]
  node_embedding["Embedding Service"]
end

subgraph group_security_governance["Security &amp; Governance"]
  node_security["Authorization"]
  node_tool_authorization["Tool Authorization"]
  node_guardrails["Guardrails"]
end

subgraph group_operations["Operations"]
  node_audit["Audit Services<br/>[AuditService.java]"]
  node_tracing["Tracing"]
end

node_user(("Agent User"))

node_user -.->|"submits request"| node_orchestrator
node_orchestrator -.->|"invokes agent"| node_agent_api
node_orchestrator -.->|"coordinates execution"| node_execution_engine
node_orchestrator -.->|"runs workflows"| node_workflow_engine
node_orchestrator -.->|"requests inference"| node_inference
node_inference -->|"routes completion"| node_provider
node_orchestrator -.->|"communicates agents"| node_communication_api
node_communication_core -.->|"implements contracts"| node_communication_api
node_communication_api -.->|"supports A2A"| node_a2a
node_communication_api -.->|"supports ANP"| node_anp_discovery
node_communication_core -.->|"routes network tasks"| node_network
node_orchestrator -.->|"uses tools"| node_tool_invocation
node_plugin_manager -.->|"extends tool systems"| node_tool_invocation
node_orchestrator -.->|"uses knowledge"| node_knowledge
node_orchestrator -.->|"retrieves context"| node_rag
node_orchestrator -.->|"uses memory"| node_memory
node_rag -.->|"embeds content"| node_embedding
node_orchestrator -.->|"checks authorization"| node_security
node_orchestrator -.->|"authorizes tools"| node_tool_authorization
node_orchestrator -.->|"applies safeguards"| node_guardrails
node_orchestrator -.->|"records activity"| node_audit
node_orchestrator -.->|"emits telemetry"| node_tracing

click node_agent_api "https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-agent/src/main/java/tech/kayys/andalus/agent/Agent.java"
click node_orchestrator "https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-agent/src/main/java/tech/kayys/andalus/agent/orchestration/AgentOrchestrator.java"
click node_execution_engine "https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-engine/src/main/java/tech/kayys/andalus/execution/ExecutionEngine.java"
click node_workflow_engine "https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-workflow/src/main/java/tech/kayys/andalus/workflow/WorkflowEngine.java"
click node_inference "https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-provider/src/main/java/tech/kayys/andalus/inference/InferenceService.java"
click node_provider "https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-provider/src/main/java/tech/kayys/andalus/provider/Provider.java"
click node_communication_api "https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-communication-api/src/main/java/tech/kayys/andalus/communication/api/AgentCommunicator.java"
click node_communication_core "https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-communication-core/src/main/java/tech/kayys/andalus/communication/core/task/TaskController.java"
click node_a2a "https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-a2a/src/main/java/tech/kayys/andalus/a2a/adapter/A2AAgentAdapter.java"
click node_anp_discovery "https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-anp/src/main/java/tech/kayys/andalus/anp/discovery/AnpAgentDiscovery.java"
click node_network "https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-agent-network-core/src/main/java/tech/kayys/andalus/network/core/DefaultAgentNetwork.java"
click node_tool_invocation "https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-tool/src/main/java/tech/kayys/andalus/tool/ToolInvocation.java"
click node_plugin_manager "https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-plugin/src/main/java/tech/kayys/andalus/plugin/DefaultPluginLifecycleManager.java"
click node_knowledge "https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-knowledge/src/main/java/tech/kayys/andalus/knowledge/graph/KnowledgeGraphProjectionService.java"
click node_rag "https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-rag/src/main/java/tech/kayys/andalus/rag/spi/RagPipeline.java"
click node_memory "https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-memory/src/main/java/tech/kayys/andalus/memory/manager/DefaultMemoryManager.java"
click node_embedding "https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-embedding/src/main/java/tech/kayys/andalus/embedding/EmbeddingService.java"
click node_security "https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-security-core/src/main/java/tech/kayys/andalus/security/policy/PolicyAuthorizationService.java"
click node_tool_authorization "https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-runtime-spi/src/main/java/tech/kayys/andalus/execution/governance/DefaultToolAuthorizationService.java"
click node_guardrails "https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-guardrails/src/main/java/tech/kayys/andalus/guardrails/GuardrailsService.java"
click node_audit "https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-audit/src/main/java/tech/kayys/andalus/audit/AuditService.java"
click node_tracing "https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-observability/src/main/java/tech/kayys/andalus/tracing/TracingService.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_agent_api,node_orchestrator,node_execution_engine,node_workflow_engine,node_inference,node_provider,node_user toneBlue
class node_communication_api,node_communication_core,node_a2a,node_anp_discovery,node_network toneAmber
class node_tool_invocation,node_plugin_manager,node_knowledge,node_rag,node_memory,node_embedding toneMint
class node_security,node_tool_authorization,node_guardrails toneRose
class node_audit,node_tracing toneIndigo
```

## Components

### Agent Execution

- [Agent Contracts](https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-agent/src/main/java/tech/kayys/andalus/agent/Agent.java): `framework/andalus-agent/src/main/java/tech/kayys/andalus/agent/Agent.java`
- [Agent Orchestrator](https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-agent/src/main/java/tech/kayys/andalus/agent/orchestration/AgentOrchestrator.java): `framework/andalus-agent/src/main/java/tech/kayys/andalus/agent/orchestration/AgentOrchestrator.java`
- [Execution Engine](https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-engine/src/main/java/tech/kayys/andalus/execution/ExecutionEngine.java): `framework/andalus-engine/src/main/java/tech/kayys/andalus/execution/ExecutionEngine.java`
- [Workflow Engine](https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-workflow/src/main/java/tech/kayys/andalus/workflow/WorkflowEngine.java): `framework/andalus-workflow/src/main/java/tech/kayys/andalus/workflow/WorkflowEngine.java`
- [Inference Routing](https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-provider/src/main/java/tech/kayys/andalus/inference/InferenceService.java): `framework/andalus-provider/src/main/java/tech/kayys/andalus/inference/InferenceService.java`
- [Model Providers](https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-provider/src/main/java/tech/kayys/andalus/provider/Provider.java): `framework/andalus-provider/src/main/java/tech/kayys/andalus/provider/Provider.java`

### Communication

- [Communication API](https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-communication-api/src/main/java/tech/kayys/andalus/communication/api/AgentCommunicator.java): `framework/andalus-communication-api/src/main/java/tech/kayys/andalus/communication/api/AgentCommunicator.java`
- [Communication Core](https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-communication-core/src/main/java/tech/kayys/andalus/communication/core/task/TaskController.java): `framework/andalus-communication-core/src/main/java/tech/kayys/andalus/communication/core/task/TaskController.java`
- [A2A Adapter](https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-a2a/src/main/java/tech/kayys/andalus/a2a/adapter/A2AAgentAdapter.java): `framework/andalus-a2a/src/main/java/tech/kayys/andalus/a2a/adapter/A2AAgentAdapter.java`
- [ANP Discovery](https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-anp/src/main/java/tech/kayys/andalus/anp/discovery/AnpAgentDiscovery.java): `framework/andalus-anp/src/main/java/tech/kayys/andalus/anp/discovery/AnpAgentDiscovery.java`
- [Agent Network](https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-agent-network-core/src/main/java/tech/kayys/andalus/network/core/DefaultAgentNetwork.java): `framework/andalus-agent-network-core/src/main/java/tech/kayys/andalus/network/core/DefaultAgentNetwork.java`

### Tools & Knowledge

- [Tool Invocation](https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-tool/src/main/java/tech/kayys/andalus/tool/ToolInvocation.java): `framework/andalus-tool/src/main/java/tech/kayys/andalus/tool/ToolInvocation.java`
- [Plugin Lifecycle](https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-plugin/src/main/java/tech/kayys/andalus/plugin/DefaultPluginLifecycleManager.java): `framework/andalus-plugin/src/main/java/tech/kayys/andalus/plugin/DefaultPluginLifecycleManager.java`
- [Knowledge Services](https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-knowledge/src/main/java/tech/kayys/andalus/knowledge/graph/KnowledgeGraphProjectionService.java): `framework/andalus-knowledge/src/main/java/tech/kayys/andalus/knowledge/graph/KnowledgeGraphProjectionService.java`
- [RAG Pipeline](https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-rag/src/main/java/tech/kayys/andalus/rag/spi/RagPipeline.java): `framework/andalus-rag/src/main/java/tech/kayys/andalus/rag/spi/RagPipeline.java`
- [Memory Manager](https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-memory/src/main/java/tech/kayys/andalus/memory/manager/DefaultMemoryManager.java): `framework/andalus-memory/src/main/java/tech/kayys/andalus/memory/manager/DefaultMemoryManager.java`
- [Embedding Service](https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-embedding/src/main/java/tech/kayys/andalus/embedding/EmbeddingService.java): `framework/andalus-embedding/src/main/java/tech/kayys/andalus/embedding/EmbeddingService.java`

### Security & Governance

- [Authorization](https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-security-core/src/main/java/tech/kayys/andalus/security/policy/PolicyAuthorizationService.java): `framework/andalus-security-core/src/main/java/tech/kayys/andalus/security/policy/PolicyAuthorizationService.java`
- [Tool Authorization](https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-runtime-spi/src/main/java/tech/kayys/andalus/execution/governance/DefaultToolAuthorizationService.java): `framework/andalus-runtime-spi/src/main/java/tech/kayys/andalus/execution/governance/DefaultToolAuthorizationService.java`
- [Guardrails](https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-guardrails/src/main/java/tech/kayys/andalus/guardrails/GuardrailsService.java): `framework/andalus-guardrails/src/main/java/tech/kayys/andalus/guardrails/GuardrailsService.java`

### Operations

- [Audit Services](https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-audit/src/main/java/tech/kayys/andalus/audit/AuditService.java): `framework/andalus-audit/src/main/java/tech/kayys/andalus/audit/AuditService.java`
- [Tracing](https://github.com/bhangun/andalus-framework/blob/main/framework/andalus-observability/src/main/java/tech/kayys/andalus/tracing/TracingService.java): `framework/andalus-observability/src/main/java/tech/kayys/andalus/tracing/TracingService.java`

### Other components

- **Agent User**

## Connections

- Agent User → Agent Orchestrator: submits request
- Agent Orchestrator → Agent Contracts: invokes agent
- Agent Orchestrator → Execution Engine: coordinates execution
- Agent Orchestrator → Workflow Engine: runs workflows
- Agent Orchestrator → Inference Routing: requests inference
- Inference Routing → Model Providers: routes completion (evidence: `framework/andalus-provider/src/main/java/tech/kayys/andalus/inference/InferenceService.java`)
- Agent Orchestrator → Communication API: communicates agents
- Communication Core → Communication API: implements contracts
- Communication API → A2A Adapter: supports A2A
- Communication API → ANP Discovery: supports ANP
- Communication Core → Agent Network: routes network tasks
- Agent Orchestrator → Tool Invocation: uses tools
- Plugin Lifecycle → Tool Invocation: extends tool systems
- Agent Orchestrator → Knowledge Services: uses knowledge
- Agent Orchestrator → RAG Pipeline: retrieves context
- Agent Orchestrator → Memory Manager: uses memory
- RAG Pipeline → Embedding Service: embeds content
- Agent Orchestrator → Authorization: checks authorization
- Agent Orchestrator → Tool Authorization: authorizes tools
- Agent Orchestrator → Guardrails: applies safeguards
- Agent Orchestrator → Audit Services: records activity
- Agent Orchestrator → Tracing: emits telemetry
