# openbkn-ai/bkn-foundry architecture

> Architecture diagram of the GitHub repository openbkn-ai/bkn-foundry, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openbkn-ai/bkn-foundry
- Repository: https://github.com/openbkn-ai/bkn-foundry

## Overview

BKN Foundry is a backend platform for modeling and governing business knowledge networks, querying their ontology and underlying data, and supporting agent-facing model calls. The main query path accepts a client request, applies the relevant query logic, retrieves data through Vega, and returns results. The tree also identifies ontology management, metrics, authorization, proxy synchronization, and trace/evidence capabilities. Edges are limited to relationships visible in sampled source; several README-described capabilities have no corresponding implementation excerpts here.

Main entry points: [`adp/bkn/ontology-query/server/logics/metric/metric_query_service.go`](https://github.com/openbkn-ai/bkn-foundry/blob/main/adp/bkn/ontology-query/server/logics/metric/metric_query_service.go) (Metric query), [`infra/mf-model-api/app/controller/llm_controller.py`](https://github.com/openbkn-ai/bkn-foundry/blob/main/infra/mf-model-api/app/controller/llm_controller.py) (LLM API), [`adp/bkn/bkn-backend/server/logics/cypher/query_service.go`](https://github.com/openbkn-ai/bkn-foundry/blob/main/adp/bkn/bkn-backend/server/logics/cypher/query_service.go) (Cypher query), [`adp/bkn/bkn-backend/server/driveradapters/bkn_handler.go`](https://github.com/openbkn-ai/bkn-foundry/blob/main/adp/bkn/bkn-backend/server/driveradapters/bkn_handler.go) (BKN API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_model["Ontology management"]
  node_bkn_handler["BKN API<br/>[bkn_handler.go]"]
  node_bkn_service["BKN service<br/>[bkn_service.go]"]
  node_kn_service["Knowledge networks"]
  node_capability["Capability bindings"]
  node_ontology["Object and relation types"]
  node_permission["Permissions"]
end

subgraph group_query["Knowledge queries"]
  node_metric_api["Metric API<br/>[metric_handler.go]"]
  node_metric_service["Metric query"]
  node_authz["Query authorization"]
  node_cypher_service["Cypher query<br/>[query_service.go]"]
end

subgraph group_data["Data access"]
  node_vega_metric["Vega data access"]
  node_vega_api["Raw query API<br/>[query_handler.go]"]
  node_raw_query["Raw query service"]
  node_connectors["Data connectors"]
end

subgraph group_agent["Agent and trace"]
  node_model_api["LLM API<br/>[llm_controller.py]"]
  node_model_manager["Model management<br/>[llm_controller.py]"]
  node_model_provider["LLM provider"]
  node_cache[("Redis cache")]
  node_evidence["Evidence trace<br/>[evidence.go]"]
  node_trace_service["Interaction assembly<br/>[query_service.go]"]
end

node_client(("CLI or API client"))
node_query_client(("Query client"))
node_llm_client(("Agent or application"))

node_client -->|"sends requests"| node_bkn_handler
node_bkn_handler -->|"dispatches"| node_bkn_service
node_bkn_service -->|"manages networks"| node_kn_service
node_query_client -->|"sends metric query"| node_metric_api
node_metric_api -->|"dispatches"| node_metric_service
node_metric_service -->|"queries resource data"| node_vega_metric
node_metric_service -->|"checks access"| node_authz
node_metric_service -->|"loads object type"| node_ontology
node_cypher_service -->|"checks permissions"| node_permission
node_cypher_service -->|"resolves schema"| node_ontology
node_cypher_service -->|"runs data query"| node_vega_metric
node_query_client -->|"sends raw query"| node_vega_api
node_vega_api -->|"executes"| node_raw_query
node_raw_query -->|"queries data"| node_connectors
node_llm_client -->|"requests completion"| node_model_api
node_model_api -->|"calls model"| node_model_provider
node_model_api -->|"reads and writes"| node_cache
node_model_api -->|"emits trace evidence"| node_evidence
node_trace_service -->|"loads evidence"| node_evidence

click node_bkn_handler "https://github.com/openbkn-ai/bkn-foundry/blob/main/adp/bkn/bkn-backend/server/driveradapters/bkn_handler.go"
click node_bkn_service "https://github.com/openbkn-ai/bkn-foundry/blob/main/adp/bkn/bkn-backend/server/logics/bkn/bkn_service.go"
click node_kn_service "https://github.com/openbkn-ai/bkn-foundry/blob/main/adp/bkn/bkn-backend/server/logics/knowledge_network/knowledge_network_service.go"
click node_capability "https://github.com/openbkn-ai/bkn-foundry/blob/main/adp/bkn/bkn-backend/server/logics/capability_binding/capability_binding_service.go"
click node_ontology "https://github.com/openbkn-ai/bkn-foundry/blob/main/adp/bkn/bkn-backend/server/logics/object_type/object_type_service.go"
click node_permission "https://github.com/openbkn-ai/bkn-foundry/blob/main/adp/bkn/bkn-backend/server/logics/permission/permission_service.go"
click node_metric_api "https://github.com/openbkn-ai/bkn-foundry/blob/main/adp/bkn/ontology-query/server/driveradapters/metric_handler.go"
click node_metric_service "https://github.com/openbkn-ai/bkn-foundry/blob/main/adp/bkn/ontology-query/server/logics/metric/metric_query_service.go"
click node_authz "https://github.com/openbkn-ai/bkn-foundry/blob/main/adp/bkn/ontology-query/server/logics/query_authorization/query_authorization_service.go"
click node_cypher_service "https://github.com/openbkn-ai/bkn-foundry/blob/main/adp/bkn/bkn-backend/server/logics/cypher/query_service.go"
click node_vega_metric "https://github.com/openbkn-ai/bkn-foundry/blob/main/adp/bkn/ontology-query/server/drivenadapters/vega_backend/vega_backend_access.go"
click node_vega_api "https://github.com/openbkn-ai/bkn-foundry/blob/main/vega/vega-backend/server/driveradapters/query_handler.go"
click node_raw_query "https://github.com/openbkn-ai/bkn-foundry/blob/main/vega/vega-backend/server/logics/query/raw_query_service.go"
click node_model_api "https://github.com/openbkn-ai/bkn-foundry/blob/main/infra/mf-model-api/app/controller/llm_controller.py"
click node_model_manager "https://github.com/openbkn-ai/bkn-foundry/blob/main/infra/mf-model-manager/app/controller/llm_controller.py"
click node_evidence "https://github.com/openbkn-ai/bkn-foundry/blob/main/adp/bkn/ontology-query/server/common/bkntrace/evidence.go"
click node_trace_service "https://github.com/openbkn-ai/bkn-foundry/blob/main/bkn-trace/agent-observability/src/domain/service/assemblysvc/query_service.go"

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_bkn_handler,node_bkn_service,node_kn_service,node_capability,node_ontology,node_permission,node_client,node_query_client toneBlue
class node_metric_api,node_metric_service,node_authz,node_cypher_service toneAmber
class node_vega_metric,node_vega_api,node_raw_query,node_connectors toneMint
class node_model_api,node_model_manager,node_model_provider,node_cache,node_evidence,node_trace_service toneRose
class node_llm_client toneIndigo
```

## Components

### Ontology management

- [BKN API](https://github.com/openbkn-ai/bkn-foundry/blob/main/adp/bkn/bkn-backend/server/driveradapters/bkn_handler.go): `adp/bkn/bkn-backend/server/driveradapters/bkn_handler.go`
- [BKN service](https://github.com/openbkn-ai/bkn-foundry/blob/main/adp/bkn/bkn-backend/server/logics/bkn/bkn_service.go): `adp/bkn/bkn-backend/server/logics/bkn/bkn_service.go`
- [Knowledge networks](https://github.com/openbkn-ai/bkn-foundry/blob/main/adp/bkn/bkn-backend/server/logics/knowledge_network/knowledge_network_service.go): `adp/bkn/bkn-backend/server/logics/knowledge_network/knowledge_network_service.go`
- [Capability bindings](https://github.com/openbkn-ai/bkn-foundry/blob/main/adp/bkn/bkn-backend/server/logics/capability_binding/capability_binding_service.go): `adp/bkn/bkn-backend/server/logics/capability_binding/capability_binding_service.go`
- [Object and relation types](https://github.com/openbkn-ai/bkn-foundry/blob/main/adp/bkn/bkn-backend/server/logics/object_type/object_type_service.go): `adp/bkn/bkn-backend/server/logics/object_type/object_type_service.go`
- [Permissions](https://github.com/openbkn-ai/bkn-foundry/blob/main/adp/bkn/bkn-backend/server/logics/permission/permission_service.go): `adp/bkn/bkn-backend/server/logics/permission/permission_service.go`

### Knowledge queries

- [Metric API](https://github.com/openbkn-ai/bkn-foundry/blob/main/adp/bkn/ontology-query/server/driveradapters/metric_handler.go): `adp/bkn/ontology-query/server/driveradapters/metric_handler.go`
- [Metric query](https://github.com/openbkn-ai/bkn-foundry/blob/main/adp/bkn/ontology-query/server/logics/metric/metric_query_service.go): `adp/bkn/ontology-query/server/logics/metric/metric_query_service.go`
- [Query authorization](https://github.com/openbkn-ai/bkn-foundry/blob/main/adp/bkn/ontology-query/server/logics/query_authorization/query_authorization_service.go): `adp/bkn/ontology-query/server/logics/query_authorization/query_authorization_service.go`
- [Cypher query](https://github.com/openbkn-ai/bkn-foundry/blob/main/adp/bkn/bkn-backend/server/logics/cypher/query_service.go): `adp/bkn/bkn-backend/server/logics/cypher/query_service.go`

### Data access

- [Vega data access](https://github.com/openbkn-ai/bkn-foundry/blob/main/adp/bkn/ontology-query/server/drivenadapters/vega_backend/vega_backend_access.go): `adp/bkn/ontology-query/server/drivenadapters/vega_backend/vega_backend_access.go`
- [Raw query API](https://github.com/openbkn-ai/bkn-foundry/blob/main/vega/vega-backend/server/driveradapters/query_handler.go): `vega/vega-backend/server/driveradapters/query_handler.go`
- [Raw query service](https://github.com/openbkn-ai/bkn-foundry/blob/main/vega/vega-backend/server/logics/query/raw_query_service.go): `vega/vega-backend/server/logics/query/raw_query_service.go`
- **Data connectors**

### Agent and trace

- [LLM API](https://github.com/openbkn-ai/bkn-foundry/blob/main/infra/mf-model-api/app/controller/llm_controller.py): `infra/mf-model-api/app/controller/llm_controller.py`
- [Model management](https://github.com/openbkn-ai/bkn-foundry/blob/main/infra/mf-model-manager/app/controller/llm_controller.py): `infra/mf-model-manager/app/controller/llm_controller.py`
- **LLM provider**
- **Redis cache**
- [Evidence trace](https://github.com/openbkn-ai/bkn-foundry/blob/main/adp/bkn/ontology-query/server/common/bkntrace/evidence.go): `adp/bkn/ontology-query/server/common/bkntrace/evidence.go`
- [Interaction assembly](https://github.com/openbkn-ai/bkn-foundry/blob/main/bkn-trace/agent-observability/src/domain/service/assemblysvc/query_service.go): `bkn-trace/agent-observability/src/domain/service/assemblysvc/query_service.go`

### Other components

- **CLI or API client**
- **Query client**
- **Agent or application**

## Connections

- CLI or API client → BKN API: sends requests
- BKN API → BKN service: dispatches
- BKN service → Knowledge networks: manages networks
- Query client → Metric API: sends metric query
- Metric API → Metric query: dispatches
- Metric query → Vega data access: queries resource data
- Metric query → Query authorization: checks access
- Metric query → Object and relation types: loads object type
- Cypher query → Permissions: checks permissions
- Cypher query → Object and relation types: resolves schema
- Cypher query → Vega data access: runs data query
- Query client → Raw query API: sends raw query
- Raw query API → Raw query service: executes
- Raw query service → Data connectors: queries data
- Agent or application → LLM API: requests completion
- LLM API → LLM provider: calls model
- LLM API → Redis cache: reads and writes
- LLM API → Evidence trace: emits trace evidence
- Interaction assembly → Evidence trace: loads evidence