# idun-group/idun-agent-platform architecture

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

- Interactive diagram: https://gitdiagram.com/idun-group/idun-agent-platform
- Repository: https://github.com/idun-group/idun-agent-platform

## Overview

Idun Agent Platform packages LangGraph and Google ADK agents as a self-hosted FastAPI runtime with chat, administration, persistence, traces, and policy/tool-management capabilities. The main workflow is configuring an agent, assembling its runtime configuration from stored settings, serving chat or messaging requests through the engine, and exposing administration and trace inspection through the bundled UI. The graph preserves README-documented capabilities, but several links to unsampled subsystems are documented at product level rather than verified from their implementation.

Main entry points: [`libs/idun_agent_engine/src/idun_agent_engine/agent/base.py`](https://github.com/idun-group/idun-agent-platform/blob/main/libs/idun_agent_engine/src/idun_agent_engine/agent/base.py) (Engine SDK), [`libs/idun_agent_standalone/src/idun_agent_standalone/app.py`](https://github.com/idun-group/idun-agent-platform/blob/main/libs/idun_agent_standalone/src/idun_agent_standalone/app.py) (Standalone app), [`services/idun_agent_standalone_ui/app/admin/page.tsx`](https://github.com/idun-group/idun-agent-platform/blob/main/services/idun_agent_standalone_ui/app/admin/page.tsx) (Admin and traces UI), [`libs/idun_agent_standalone/src/idun_agent_standalone/services/engine_config.py`](https://github.com/idun-group/idun-agent-platform/blob/main/libs/idun_agent_standalone/src/idun_agent_standalone/services/engine_config.py) (Config assembler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_chat["Chat UI<br/>[page.tsx]"]
  node_adminui["Admin and traces UI<br/>[page.tsx]"]
end

subgraph group_runtime["Agent runtime"]
  node_app["Standalone app<br/>[app.py]"]
  node_engine["Engine SDK<br/>[base.py]"]
  node_langgraph["LangGraph adapter<br/>[langgraph.py]"]
  node_adk["ADK adapter<br/>[adk.py]"]
  node_messaging["Messaging integrations"]
end

subgraph group_management["Agent management"]
  node_api["Admin REST API"]
  node_assembler["Config assembler<br/>[engine_config.py]"]
  node_reload["Runtime reload<br/>[engine_reload.py]"]
  node_mcp["MCP tools<br/>[registry.py]"]
  node_guardrails["Guardrails"]
  node_prompts["Prompt management<br/>[registry.py]"]
end

subgraph group_data["State and traces"]
  node_observability["Observability providers"]
  node_store[("Standalone database<br/>[session.py]")]
  node_tracestore[("Trace storage<br/>[writer.py]")]
end

subgraph group_contracts["Configuration contracts"]
  node_schema["Engine configuration<br/>[engine.py]"]
end

node_users(("Chat users"))
node_admins(("Administrators"))

node_users -->|"use chat"| node_chat
node_admins -->|"manage runtime"| node_adminui
node_chat -->|"send requests"| node_engine
node_adminui -.->|"call API"| node_api
node_app -->|"mount runtime"| node_engine
node_app -->|"register routes"| node_api
node_app -->|"read configuration"| node_store
node_app -->|"assemble config"| node_assembler
node_assembler -->|"load settings"| node_store
node_assembler -->|"validate config"| node_schema
node_api -.->|"trigger reload"| node_reload
node_reload -->|"reconfigure agent"| node_engine
node_engine -->|"supports framework"| node_langgraph
node_engine -->|"supports framework"| node_adk
node_engine -->|"govern tools"| node_mcp
node_engine -->|"apply policies"| node_guardrails
node_engine -->|"use prompts"| node_prompts
node_engine -->|"emit traces"| node_observability
node_engine -->|"persist memory"| node_store
node_messaging -->|"invoke agent"| node_engine
node_observability -.->|"export trace data"| node_tracestore
node_adminui -->|"inspect traces"| node_tracestore

click node_chat "https://github.com/idun-group/idun-agent-platform/blob/main/services/idun_agent_standalone_ui/app/page.tsx"
click node_adminui "https://github.com/idun-group/idun-agent-platform/blob/main/services/idun_agent_standalone_ui/app/admin/page.tsx"
click node_api "https://github.com/idun-group/idun-agent-platform/tree/main/libs/idun_agent_standalone/src/idun_agent_standalone/api/v1/routers"
click node_app "https://github.com/idun-group/idun-agent-platform/blob/main/libs/idun_agent_standalone/src/idun_agent_standalone/app.py"
click node_assembler "https://github.com/idun-group/idun-agent-platform/blob/main/libs/idun_agent_standalone/src/idun_agent_standalone/services/engine_config.py"
click node_reload "https://github.com/idun-group/idun-agent-platform/blob/main/libs/idun_agent_standalone/src/idun_agent_standalone/services/engine_reload.py"
click node_engine "https://github.com/idun-group/idun-agent-platform/blob/main/libs/idun_agent_engine/src/idun_agent_engine/agent/base.py"
click node_langgraph "https://github.com/idun-group/idun-agent-platform/blob/main/libs/idun_agent_engine/src/idun_agent_engine/agent/langgraph/langgraph.py"
click node_adk "https://github.com/idun-group/idun-agent-platform/blob/main/libs/idun_agent_engine/src/idun_agent_engine/agent/adk/adk.py"
click node_messaging "https://github.com/idun-group/idun-agent-platform/tree/main/libs/idun_agent_engine/src/idun_agent_engine/integrations"
click node_mcp "https://github.com/idun-group/idun-agent-platform/blob/main/libs/idun_agent_engine/src/idun_agent_engine/mcp/registry.py"
click node_guardrails "https://github.com/idun-group/idun-agent-platform/tree/main/libs/idun_agent_engine/src/idun_agent_engine/guardrails"
click node_prompts "https://github.com/idun-group/idun-agent-platform/blob/main/libs/idun_agent_engine/src/idun_agent_engine/prompts/registry.py"
click node_observability "https://github.com/idun-group/idun-agent-platform/tree/main/libs/idun_agent_engine/src/idun_agent_engine/observability"
click node_store "https://github.com/idun-group/idun-agent-platform/blob/main/libs/idun_agent_standalone/src/idun_agent_standalone/infrastructure/db/session.py"
click node_tracestore "https://github.com/idun-group/idun-agent-platform/blob/main/libs/idun_agent_standalone/src/idun_agent_standalone/infrastructure/traces/writer.py"
click node_schema "https://github.com/idun-group/idun-agent-platform/blob/main/libs/idun_agent_schema/src/idun_agent_schema/engine/engine.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_chat,node_adminui,node_users toneBlue
class node_app,node_engine,node_langgraph,node_adk,node_messaging toneAmber
class node_api,node_assembler,node_reload,node_mcp,node_guardrails,node_prompts toneMint
class node_observability,node_store,node_tracestore toneRose
class node_schema,node_admins toneIndigo
```

## Components

### User experience

- [Chat UI](https://github.com/idun-group/idun-agent-platform/blob/main/services/idun_agent_standalone_ui/app/page.tsx): `services/idun_agent_standalone_ui/app/page.tsx`
- [Admin and traces UI](https://github.com/idun-group/idun-agent-platform/blob/main/services/idun_agent_standalone_ui/app/admin/page.tsx): `services/idun_agent_standalone_ui/app/admin/page.tsx`

### Agent runtime

- [Standalone app](https://github.com/idun-group/idun-agent-platform/blob/main/libs/idun_agent_standalone/src/idun_agent_standalone/app.py): `libs/idun_agent_standalone/src/idun_agent_standalone/app.py`
- [Engine SDK](https://github.com/idun-group/idun-agent-platform/blob/main/libs/idun_agent_engine/src/idun_agent_engine/agent/base.py): `libs/idun_agent_engine/src/idun_agent_engine/agent/base.py`
- [LangGraph adapter](https://github.com/idun-group/idun-agent-platform/blob/main/libs/idun_agent_engine/src/idun_agent_engine/agent/langgraph/langgraph.py): `libs/idun_agent_engine/src/idun_agent_engine/agent/langgraph/langgraph.py`
- [ADK adapter](https://github.com/idun-group/idun-agent-platform/blob/main/libs/idun_agent_engine/src/idun_agent_engine/agent/adk/adk.py): `libs/idun_agent_engine/src/idun_agent_engine/agent/adk/adk.py`
- [Messaging integrations](https://github.com/idun-group/idun-agent-platform/tree/main/libs/idun_agent_engine/src/idun_agent_engine/integrations): `libs/idun_agent_engine/src/idun_agent_engine/integrations`

### Agent management

- [Admin REST API](https://github.com/idun-group/idun-agent-platform/tree/main/libs/idun_agent_standalone/src/idun_agent_standalone/api/v1/routers): `libs/idun_agent_standalone/src/idun_agent_standalone/api/v1/routers`
- [Config assembler](https://github.com/idun-group/idun-agent-platform/blob/main/libs/idun_agent_standalone/src/idun_agent_standalone/services/engine_config.py): `libs/idun_agent_standalone/src/idun_agent_standalone/services/engine_config.py`
- [Runtime reload](https://github.com/idun-group/idun-agent-platform/blob/main/libs/idun_agent_standalone/src/idun_agent_standalone/services/engine_reload.py): `libs/idun_agent_standalone/src/idun_agent_standalone/services/engine_reload.py`
- [MCP tools](https://github.com/idun-group/idun-agent-platform/blob/main/libs/idun_agent_engine/src/idun_agent_engine/mcp/registry.py): `libs/idun_agent_engine/src/idun_agent_engine/mcp/registry.py`
- [Guardrails](https://github.com/idun-group/idun-agent-platform/tree/main/libs/idun_agent_engine/src/idun_agent_engine/guardrails): `libs/idun_agent_engine/src/idun_agent_engine/guardrails`
- [Prompt management](https://github.com/idun-group/idun-agent-platform/blob/main/libs/idun_agent_engine/src/idun_agent_engine/prompts/registry.py): `libs/idun_agent_engine/src/idun_agent_engine/prompts/registry.py`

### State and traces

- [Observability providers](https://github.com/idun-group/idun-agent-platform/tree/main/libs/idun_agent_engine/src/idun_agent_engine/observability): `libs/idun_agent_engine/src/idun_agent_engine/observability`
- [Standalone database](https://github.com/idun-group/idun-agent-platform/blob/main/libs/idun_agent_standalone/src/idun_agent_standalone/infrastructure/db/session.py): `libs/idun_agent_standalone/src/idun_agent_standalone/infrastructure/db/session.py`
- [Trace storage](https://github.com/idun-group/idun-agent-platform/blob/main/libs/idun_agent_standalone/src/idun_agent_standalone/infrastructure/traces/writer.py): `libs/idun_agent_standalone/src/idun_agent_standalone/infrastructure/traces/writer.py`

### Configuration contracts

- [Engine configuration](https://github.com/idun-group/idun-agent-platform/blob/main/libs/idun_agent_schema/src/idun_agent_schema/engine/engine.py): `libs/idun_agent_schema/src/idun_agent_schema/engine/engine.py`

### Other components

- **Chat users**
- **Administrators**

## Connections

- Chat users → Chat UI: use chat (evidence: `README.md`)
- Administrators → Admin and traces UI: manage runtime (evidence: `README.md`)
- Chat UI → Engine SDK: send requests (evidence: `README.md`)
- Admin and traces UI → Admin REST API: call API
- Standalone app → Engine SDK: mount runtime (evidence: `README.md`)
- Standalone app → Admin REST API: register routes (evidence: `libs/idun_agent_standalone/src/idun_agent_standalone/app.py`)
- Standalone app → Standalone database: read configuration (evidence: `libs/idun_agent_standalone/src/idun_agent_standalone/app.py`)
- Standalone app → Config assembler: assemble config (evidence: `libs/idun_agent_standalone/src/idun_agent_standalone/app.py`)
- Config assembler → Standalone database: load settings (evidence: `libs/idun_agent_standalone/src/idun_agent_standalone/services/engine_config.py`)
- Config assembler → Engine configuration: validate config (evidence: `libs/idun_agent_standalone/src/idun_agent_standalone/services/engine_config.py`)
- Admin REST API → Runtime reload: trigger reload
- Runtime reload → Engine SDK: reconfigure agent (evidence: `libs/idun_agent_standalone/src/idun_agent_standalone/services/engine_reload.py`)
- Engine SDK → LangGraph adapter: supports framework (evidence: `README.md`)
- Engine SDK → ADK adapter: supports framework (evidence: `README.md`)
- Engine SDK → MCP tools: govern tools (evidence: `README.md`)
- Engine SDK → Guardrails: apply policies (evidence: `README.md`)
- Engine SDK → Prompt management: use prompts (evidence: `README.md`)
- Engine SDK → Observability providers: emit traces (evidence: `README.md`)
- Engine SDK → Standalone database: persist memory (evidence: `README.md`)
- Messaging integrations → Engine SDK: invoke agent (evidence: `libs/idun_agent_engine/src/idun_agent_engine/integrations/google_chat/handler.py`)
- Observability providers → Trace storage: export trace data
- Admin and traces UI → Trace storage: inspect traces (evidence: `README.md`)
