# tridz-dev/huf architecture

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

- Interactive diagram: https://gitdiagram.com/tridz-dev/huf
- Repository: https://github.com/tridz-dev/huf

## Overview

HUF is a self-hosted AI infrastructure platform with a web interface and a Frappe-based backend. A user configures an agent or workflow, then invokes it through chat or the public API; the runtime manages conversation state, calls an LLM provider, and can use tools or grounded knowledge. Separate capability areas cover visual flows, integrations and messaging, reusable apps, and governance. The graph combines documented product capabilities with source-index references and excerpts; links to unsampled subsystems are included only where the README documents the relationship.

Main entry points: [`huf/ai/agent_integration.py`](https://github.com/tridz-dev/huf/blob/develop/huf/ai/agent_integration.py) (Agent runtime), [`huf/api/v1/router.py`](https://github.com/tridz-dev/huf/blob/develop/huf/api/v1/router.py) (Public API router), [`huf/ai/tool_registry.py`](https://github.com/tridz-dev/huf/blob/develop/huf/ai/tool_registry.py) (Tool registry), [`huf/api/v1/context.py`](https://github.com/tridz-dev/huf/blob/develop/huf/api/v1/context.py) (Request context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User access"]
  node_web["HUF web app<br/>[App.tsx]"]
  node_api["Public API router<br/>[router.py]"]
  node_api_context["Request context<br/>[context.py]"]
end

subgraph group_runtime["Agent runtime"]
  node_agent_runtime["Agent runtime"]
  node_conversations[("Conversation state")]
  node_llm["LLM provider<br/>[litellm.py]"]
  node_context_segments["Context assembly"]
  node_cost["Cost analytics<br/>[cost_calculator.py]"]
  node_budget["Run budgets<br/>[run_budget.py]"]
end

subgraph group_workflow["Workflow automation"]
  node_flow["Visual flow engine<br/>[flow_engine.py]"]
  node_orchestrator["Agent orchestration<br/>[orchestrator.py]"]
end

subgraph group_capabilities["Tools and grounding"]
  node_tools["Tool registry<br/>[tool_registry.py]"]
  node_tool_registry["Built-in tools<br/>[_registry.py]"]
  node_mcp["MCP client<br/>[mcp_client.py]"]
  node_knowledge["Knowledge retrieval<br/>[retriever.py]"]
  node_ocr["Document extraction<br/>[ocr_engine.py]"]
  node_apps["Apps ecosystem<br/>[apps_loader.py]"]
  node_gateway["Messaging gateways"]
end

subgraph group_governance["Platform governance"]
  node_permissions[("Capability permissions<br/>[permissions.py]")]
  node_access["Agent access checks<br/>[agent_access.py]"]
  node_transactions["Transaction control<br/>[transaction.py]"]
end

node_user(("User"))

node_user -->|"uses"| node_web
node_user -->|"invokes"| node_api
node_api -->|"builds context"| node_api_context
node_api -->|"dispatches run"| node_agent_runtime
node_agent_runtime -->|"manages history"| node_conversations
node_agent_runtime -->|"requests completion"| node_llm
node_agent_runtime -->|"builds context"| node_context_segments
node_agent_runtime -->|"applies budgets"| node_budget
node_llm -->|"tracks cost"| node_cost
node_agent_runtime -->|"invokes tools"| node_tools
node_tools -->|"checks capabilities"| node_permissions
node_agent_runtime -->|"uses MCP"| node_mcp
node_agent_runtime -->|"grounds responses"| node_knowledge
node_agent_runtime -->|"extracts documents"| node_ocr
node_flow -->|"runs agent nodes"| node_agent_runtime
node_orchestrator -->|"coordinates agents"| node_agent_runtime
node_gateway -->|"starts agent runs"| node_agent_runtime
node_apps -->|"packages capabilities"| node_tools
node_api_context -->|"authorizes agent"| node_access
node_access -->|"checks roles"| node_permissions
node_agent_runtime -->|"commits background state"| node_transactions
node_user -->|"designs workflows"| node_flow
node_user -->|"reuses skills"| node_apps

click node_web "https://github.com/tridz-dev/huf/blob/develop/frontend/src/App.tsx"
click node_api "https://github.com/tridz-dev/huf/blob/develop/huf/api/v1/router.py"
click node_api_context "https://github.com/tridz-dev/huf/blob/develop/huf/api/v1/context.py"
click node_agent_runtime "https://github.com/tridz-dev/huf/blob/develop/huf/ai/agent_integration.py"
click node_conversations "https://github.com/tridz-dev/huf/blob/develop/huf/ai/conversation_manager.py"
click node_llm "https://github.com/tridz-dev/huf/blob/develop/huf/ai/providers/litellm.py"
click node_context_segments "https://github.com/tridz-dev/huf/blob/develop/huf/ai/context_segments.py"
click node_cost "https://github.com/tridz-dev/huf/blob/develop/huf/ai/cost_calculator.py"
click node_budget "https://github.com/tridz-dev/huf/blob/develop/huf/ai/run_budget.py"
click node_flow "https://github.com/tridz-dev/huf/blob/develop/huf/ai/flow_engine.py"
click node_orchestrator "https://github.com/tridz-dev/huf/blob/develop/huf/ai/orchestration/orchestrator.py"
click node_tools "https://github.com/tridz-dev/huf/blob/develop/huf/ai/tool_registry.py"
click node_tool_registry "https://github.com/tridz-dev/huf/blob/develop/huf/ai/tools/_registry.py"
click node_mcp "https://github.com/tridz-dev/huf/blob/develop/huf/ai/mcp_client.py"
click node_knowledge "https://github.com/tridz-dev/huf/blob/develop/huf/ai/knowledge/retriever.py"
click node_ocr "https://github.com/tridz-dev/huf/blob/develop/huf/ai/ocr_engine.py"
click node_apps "https://github.com/tridz-dev/huf/blob/develop/huf/ai/app_seeding/apps_loader.py"
click node_gateway "https://github.com/tridz-dev/huf/blob/develop/huf/ai/tools/telegram_webhook.py"
click node_permissions "https://github.com/tridz-dev/huf/blob/develop/huf/permissions.py"
click node_access "https://github.com/tridz-dev/huf/blob/develop/huf/ai/agent_access.py"
click node_transactions "https://github.com/tridz-dev/huf/blob/develop/huf/ai/transaction.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_web,node_api,node_api_context,node_user toneBlue
class node_agent_runtime,node_conversations,node_llm,node_context_segments,node_cost,node_budget toneAmber
class node_flow,node_orchestrator toneMint
class node_tools,node_tool_registry,node_mcp,node_knowledge,node_ocr,node_apps,node_gateway toneRose
class node_permissions,node_access,node_transactions toneIndigo
```

## Components

### User access

- [HUF web app](https://github.com/tridz-dev/huf/blob/develop/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Public API router](https://github.com/tridz-dev/huf/blob/develop/huf/api/v1/router.py): `huf/api/v1/router.py`
- [Request context](https://github.com/tridz-dev/huf/blob/develop/huf/api/v1/context.py): `huf/api/v1/context.py`

### Agent runtime

- [Agent runtime](https://github.com/tridz-dev/huf/blob/develop/huf/ai/agent_integration.py): `huf/ai/agent_integration.py`
- [Conversation state](https://github.com/tridz-dev/huf/blob/develop/huf/ai/conversation_manager.py): `huf/ai/conversation_manager.py`
- [LLM provider](https://github.com/tridz-dev/huf/blob/develop/huf/ai/providers/litellm.py): `huf/ai/providers/litellm.py`
- [Context assembly](https://github.com/tridz-dev/huf/blob/develop/huf/ai/context_segments.py): `huf/ai/context_segments.py`
- [Cost analytics](https://github.com/tridz-dev/huf/blob/develop/huf/ai/cost_calculator.py): `huf/ai/cost_calculator.py`
- [Run budgets](https://github.com/tridz-dev/huf/blob/develop/huf/ai/run_budget.py): `huf/ai/run_budget.py`

### Workflow automation

- [Visual flow engine](https://github.com/tridz-dev/huf/blob/develop/huf/ai/flow_engine.py): `huf/ai/flow_engine.py`
- [Agent orchestration](https://github.com/tridz-dev/huf/blob/develop/huf/ai/orchestration/orchestrator.py): `huf/ai/orchestration/orchestrator.py`

### Tools and grounding

- [Tool registry](https://github.com/tridz-dev/huf/blob/develop/huf/ai/tool_registry.py): `huf/ai/tool_registry.py`
- [Built-in tools](https://github.com/tridz-dev/huf/blob/develop/huf/ai/tools/_registry.py): `huf/ai/tools/_registry.py`
- [MCP client](https://github.com/tridz-dev/huf/blob/develop/huf/ai/mcp_client.py): `huf/ai/mcp_client.py`
- [Knowledge retrieval](https://github.com/tridz-dev/huf/blob/develop/huf/ai/knowledge/retriever.py): `huf/ai/knowledge/retriever.py`
- [Document extraction](https://github.com/tridz-dev/huf/blob/develop/huf/ai/ocr_engine.py): `huf/ai/ocr_engine.py`
- [Apps ecosystem](https://github.com/tridz-dev/huf/blob/develop/huf/ai/app_seeding/apps_loader.py): `huf/ai/app_seeding/apps_loader.py`
- [Messaging gateways](https://github.com/tridz-dev/huf/blob/develop/huf/ai/tools/telegram_webhook.py): `huf/ai/tools/telegram_webhook.py`

### Platform governance

- [Capability permissions](https://github.com/tridz-dev/huf/blob/develop/huf/permissions.py): `huf/permissions.py`
- [Agent access checks](https://github.com/tridz-dev/huf/blob/develop/huf/ai/agent_access.py): `huf/ai/agent_access.py`
- [Transaction control](https://github.com/tridz-dev/huf/blob/develop/huf/ai/transaction.py): `huf/ai/transaction.py`

### Other components

- **User**

## Connections

- User → HUF web app: uses (evidence: `README.md`)
- User → Public API router: invokes (evidence: `README.md`)
- Public API router → Request context: builds context (evidence: `huf/api/v1/router.py`)
- Public API router → Agent runtime: dispatches run
- Agent runtime → Conversation state: manages history (evidence: `huf/ai/agent_integration.py`)
- Agent runtime → LLM provider: requests completion (evidence: `huf/ai/agent_integration.py`)
- Agent runtime → Context assembly: builds context (evidence: `huf/ai/agent_integration.py`)
- Agent runtime → Run budgets: applies budgets (evidence: `huf/ai/agent_integration.py`)
- LLM provider → Cost analytics: tracks cost (evidence: `huf/ai/providers/litellm.py`)
- Agent runtime → Tool registry: invokes tools (evidence: `huf/ai/agent_integration.py`)
- Tool registry → Capability permissions: checks capabilities (evidence: `huf/ai/tool_registry.py`)
- Agent runtime → MCP client: uses MCP (evidence: `huf/ai/agent_integration.py`)
- Agent runtime → Knowledge retrieval: grounds responses (evidence: `README.md`)
- Agent runtime → Document extraction: extracts documents (evidence: `huf/ai/agent_integration.py`)
- Visual flow engine → Agent runtime: runs agent nodes (evidence: `huf/ai/flow_engine.py`)
- Agent orchestration → Agent runtime: coordinates agents (evidence: `README.md`)
- Messaging gateways → Agent runtime: starts agent runs (evidence: `huf/ai/tools/telegram_webhook.py`)
- Apps ecosystem → Tool registry: packages capabilities (evidence: `README.md`)
- Request context → Agent access checks: authorizes agent (evidence: `huf/api/v1/endpoints/responses_stream.py`)
- Agent access checks → Capability permissions: checks roles
- Agent runtime → Transaction control: commits background state (evidence: `huf/ai/agent_integration.py`)
- User → Visual flow engine: designs workflows (evidence: `README.md`)
- User → Apps ecosystem: reuses skills (evidence: `README.md`)