# trustgraph-ai/trustgraph architecture

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

- Interactive diagram: https://gitdiagram.com/trustgraph-ai/trustgraph
- Repository: https://github.com/trustgraph-ai/trustgraph
- Video tour (about a minute): https://gitdiagram.com/trustgraph-ai/trustgraph/video

## Overview

1. **Repository shape**
   This is a Python monorepo split into a shared core library plus many service packages. The main runtime code lives under `trustgraph-flow`, while `trustgraph-base` provides reusable client, messaging, schema, and service primitives. Other top-level packages are narrow adapters or CLIs (`trustgraph-cli`, `trustgraph-mcp`, `trustgraph-ocr`, `trustgraph-unstructured`, `trustgraph-bedrock`, `trustgraph-vertexai`, `trustgraph-embeddings-hf`).

2. **Primary architectural boundary: gateway vs workers**
   The central runtime boundary is the **API gateway** in `trustgraph-flow/trustgraph/gateway`, which exposes HTTP/OpenAPI and websocket/streaming endpoints. The gateway does not do the heavy work itself; it dispatches requests into backend services through the messaging layer. This makes the system event-driven and lets the same operations be invoked via REST, websocket, or CLI clients.

3. **Control plane vs data plane**
   The repo models a clear control plane/data plane split:
   - **Control plane**: IAM, config, workspace/collection management, flow lifecycle, prompt management, tool registration, and bootstrap.
   - **Data plane**: ingestion, decoding, chunking, embeddings, extraction, storage, retrieval, RAG, and agent execution.
   The workspace → collection → flow hierarchy in the README is reflected across the codebase and is the main tenancy/isolation model.

4. **Messaging and service orchestration**
   `trustgraph-base/trustgraph/base/pubsub.py` plus backends for Kafka, Pulsar, and RabbitMQ define the messaging abstraction. The service packages in `trustgraph-flow` are arranged around request/response or producer/consumer patterns, with `processor_group`, `consumer`, `publisher`, and `subscriber` helpers. This is the main internal transport between gateway, long-running workers, and specialized services.

5. **Ingestion and knowledge pipeline**
   Document and structured-data intake flows start with decoding/parsing, then chunking, then optional extraction, then persistence. Key stages are:
   - decoding services for PDF/OCR/unstructured text
   - chunking services (`token`, `recursive`)
   - knowledge extraction services (`extract/kg/...`)
   - storage services for documents, rows, triples, and embeddings
   The pipeline is designed to turn raw content into queryable knowledge artifacts, not just text blobs.

6. **Knowledge representation layer**
   The repo distinguishes several knowledge forms:
   - **Triples / graph facts** for symbolic context
   - **Rows** for tabular/structured records
   - **Document embeddings** and **graph embeddings** for semantic retrieval
   - **Ontology-driven extraction** for schema-aware graph construction
   The `trustgraph-base/trustgraph/schema/knowledge` and `trustgraph-flow/trustgraph/extract/kg/ontology` directories show that ontology and provenance are first-class parts of the domain model.

7. **Storage backends**
   Storage is abstracted behind service-specific implementations:
   - **Cassandra** for core multi-model and tabular storage
   - **Qdrant / Milvus / Pinecone** for vector-backed embedding storage and retrieval
   - **Neo4j / Memgraph / FalkorDB / Cassandra** for triple/graph storage and queries
   - **Garage / S3-compatible object storage** for blobs and large artifacts
   - **FTS5** for keyword index support
   The architecture is backend-pluggable; query and storage services are organized by capability and by backend.

8. **Retrieval and RAG**
   Retrieval services are separated by modality:
   - `document_rag` for document-centric retrieval
   - `graph_rag` for graph-grounded retrieval with explainability
   - `nlp_query` and `structured_query` for natural-language-to-query workflows
   - `sparql_query`, `rows_query`, `triples_query`, and embedding query services for direct access paths
   The system emphasizes explainable retrieval, using graph traversal and provenance rather than only nearest-neighbor vector matches.

9. **Agent orchestration and tool use**
   `trustgraph-flow/trustgraph/agent` contains agent execution patterns: **ReAct**, **Plan**, **Supervisor**, and an orchestrator/aggregator/meta-router. There is also an MCP tool service, which implies external tool invocation through a standard protocol boundary. This subsystem consumes context from retrieval services and emits streaming reasoning/explainability events back through the gateway.

10. **Model/provider adapters**
   LLM and embedding execution are not hardwired to one provider. There are dedicated adapters for:
   - text completion: OpenAI, Azure OpenAI, Anthropic/Claude, Cohere, Mistral, Ollama, vLLM, TGI, LM Studio, Llamafile
   - embeddings: Hugging Face / fastembed / Ollama variants
   - OCR: Mistral OCR and related decoders
   These adapters sit behind common client/service abstractions in `trustgraph-base`, so the higher-level flows can switch providers without changing the orchestration layer.

11. **Public contracts and generated specs**
   `specs/api` and `specs/websocket` are the authoritative interface contracts. They define REST/OpenAPI shapes, websocket message envelopes, and request/response schemas for the major services. The repo also includes versioned docs, tech specs, and tests that appear to lock down behavior and serialization formats across these boundaries.

12. **CLI, bootstrap, and operations**
   `trustgraph-cli` provides operational entry points for provisioning IAM, creating workspaces/collections, loading knowledge, managing flows, invoking services, and inspecting state. `trustgraph-flow/bootstrap` contains startup initializers such as workspace setup and default flow startup. This indicates the system is designed to be deployed as a set of cooperating containers, with operational workflows driven from CLI and automation rather than a monolithic app.

13. **Observability, explainability, and audit**
   Explainability is not an add-on; it is wired into the architecture via provenance packages, audit publishing, metrics, and streaming explain-trace endpoints. The service and gateway layers include explicit support for audit events, metrics, and streaming response handling so that retrieval and agent decisions can be inspected after the fact.

14. **Testing and release posture**
   The repo has deep unit, contract, integration, and end-to-end style tests, plus manual test fixtures and API test cases. That suggests the architecture is contract-heavy: components are expected to communicate through stable schemas, and cross-backend compatibility is an explicit concern.

15. **How to draw the diagram**
   A good architecture diagram should show:
   - clients/CLI/UI entering through the gateway
   - gateway dispatching to pub/sub-backed service workers
   - ingestion/extraction pipeline feeding storage layers
   - retrieval services reading from graph/vector/tabular/object stores
   - agent orchestration calling retrieval and model adapters
   - IAM/config/workspace services spanning everything as shared control-plane services
   - explicit spec boundaries for REST and websocket contracts

Main entry points: [`trustgraph-base/trustgraph/base/pubsub.py`](https://github.com/trustgraph-ai/trustgraph/blob/master/trustgraph-base/trustgraph/base/pubsub.py) (Pub/Sub), [`trustgraph-flow/trustgraph/gateway`](https://github.com/trustgraph-ai/trustgraph/tree/master/trustgraph-flow/trustgraph/gateway) (API gateway), [`trustgraph-flow/trustgraph/decoding`](https://github.com/trustgraph-ai/trustgraph/tree/master/trustgraph-flow/trustgraph/decoding) (Ingest), [`trustgraph-flow/trustgraph/storage`](https://github.com/trustgraph-ai/trustgraph/tree/master/trustgraph-flow/trustgraph/storage) (Storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo["Monorepo"]
end

subgraph group_interfaces["Contracts"]
  node_spec_api["REST spec<br/>openapi contracts<br/>[openapi.yaml]"]
  node_spec_ws["WS spec<br/>asyncapi contracts<br/>[asyncapi.yaml]"]
end

subgraph group_foundation["Base Library"]
  node_base_pubsub["Pub/Sub<br/>messaging abstraction<br/>[pubsub.py]"]
  node_base_schema["Schemas<br/>service/data schema"]
  node_base_clients["Clients<br/>gateway/client SDK"]
end

subgraph group_runtime["Flow Runtime"]
  node_gateway["API gateway<br/>http/ws dispatch"]
  node_iam["IAM<br/>auth/control service"]
  node_config["Config<br/>control service"]
  node_flow_mgmt["Flow mgmt<br/>lifecycle control"]
  node_librarian["Librarian<br/>blob/document service"]
  node_ingest["Ingest<br/>decode/chunk pipeline"]
  node_extract_kg["KG extract<br/>knowledge extraction"]
  node_embeddings["Embeddings<br/>vector pipeline"]
  node_storage["Storage<br/>persistence services"]
  node_query["Query<br/>retrieval services"]
  node_rag["RAG<br/>retrieval orchestration"]
  node_agent["Agent<br/>orchestration runtime"]
end

subgraph group_adapters["Adapters"]
  node_llm_models["LLM adapters<br/>text completion providers"]
  node_embed_adapters["Embed adapters<br/>embedding providers<br/>[hf.py]"]
  node_ocr_unstructured["Decode adapters<br/>ocr/unstructured adapters<br/>[pdf_decoder.py]"]
end

subgraph group_ops["Operations"]
  node_cli["CLI<br/>operations tooling"]
  node_bootstrap["Bootstrap<br/>startup init"]
end

node_spec_api -->|"HTTP contract"| node_gateway
node_spec_ws -->|"stream contract"| node_gateway
node_base_pubsub -->|"dispatch transport"| node_gateway
node_base_schema -->|"shared models"| node_gateway
node_base_schema -->|"identity models"| node_iam
node_base_schema -->|"flow models"| node_flow_mgmt
node_base_pubsub -->|"worker transport"| node_ingest
node_base_pubsub -->|"worker transport"| node_extract_kg
node_base_pubsub -->|"worker transport"| node_embeddings
node_base_pubsub -->|"worker transport"| node_storage
node_base_pubsub -->|"worker transport"| node_query
node_base_pubsub -->|"worker transport"| node_rag
node_base_pubsub -->|"worker transport"| node_agent
node_librarian -->|"documents in"| node_ingest
node_ingest -->|"content flow"| node_extract_kg
node_extract_kg -->|"knowledge out"| node_storage
node_embeddings -->|"vector out"| node_storage
node_storage -->|"read path"| node_query
node_query -->|"retrieval context"| node_rag
node_rag -->|"grounding"| node_agent
node_llm_models -->|"reasoning model"| node_agent
node_llm_models -->|"rerank/generate"| node_rag
node_embed_adapters -->|"embed provider"| node_embeddings
node_ocr_unstructured -->|"decode provider"| node_ingest
node_cli -->|"operates via API"| node_gateway
node_cli -->|"admin flow"| node_bootstrap
node_bootstrap -->|"provisions"| node_iam
node_bootstrap -->|"starts defaults"| node_flow_mgmt
node_base_clients -->|"sdk"| node_gateway

click node_spec_api "https://github.com/trustgraph-ai/trustgraph/blob/master/specs/api/openapi.yaml"
click node_spec_ws "https://github.com/trustgraph-ai/trustgraph/blob/master/specs/websocket/asyncapi.yaml"
click node_base_pubsub "https://github.com/trustgraph-ai/trustgraph/blob/master/trustgraph-base/trustgraph/base/pubsub.py"
click node_base_schema "https://github.com/trustgraph-ai/trustgraph/tree/master/trustgraph-base/trustgraph/schema"
click node_base_clients "https://github.com/trustgraph-ai/trustgraph/tree/master/trustgraph-base/trustgraph/clients"
click node_gateway "https://github.com/trustgraph-ai/trustgraph/tree/master/trustgraph-flow/trustgraph/gateway"
click node_iam "https://github.com/trustgraph-ai/trustgraph/tree/master/trustgraph-flow/trustgraph/iam"
click node_config "https://github.com/trustgraph-ai/trustgraph/tree/master/trustgraph-flow/trustgraph/config/service"
click node_flow_mgmt "https://github.com/trustgraph-ai/trustgraph/tree/master/trustgraph-flow/trustgraph/flow/service"
click node_librarian "https://github.com/trustgraph-ai/trustgraph/tree/master/trustgraph-flow/trustgraph/librarian"
click node_ingest "https://github.com/trustgraph-ai/trustgraph/tree/master/trustgraph-flow/trustgraph/decoding"
click node_extract_kg "https://github.com/trustgraph-ai/trustgraph/tree/master/trustgraph-flow/trustgraph/extract/kg"
click node_embeddings "https://github.com/trustgraph-ai/trustgraph/tree/master/trustgraph-flow/trustgraph/embeddings"
click node_storage "https://github.com/trustgraph-ai/trustgraph/tree/master/trustgraph-flow/trustgraph/storage"
click node_query "https://github.com/trustgraph-ai/trustgraph/tree/master/trustgraph-flow/trustgraph/query"
click node_rag "https://github.com/trustgraph-ai/trustgraph/tree/master/trustgraph-flow/trustgraph/retrieval"
click node_agent "https://github.com/trustgraph-ai/trustgraph/tree/master/trustgraph-flow/trustgraph/agent"
click node_llm_models "https://github.com/trustgraph-ai/trustgraph/tree/master/trustgraph-flow/trustgraph/model/text_completion"
click node_embed_adapters "https://github.com/trustgraph-ai/trustgraph/blob/master/trustgraph-embeddings-hf/trustgraph/embeddings/hf/hf.py"
click node_ocr_unstructured "https://github.com/trustgraph-ai/trustgraph/blob/master/trustgraph-ocr/trustgraph/decoding/ocr/pdf_decoder.py"
click node_cli "https://github.com/trustgraph-ai/trustgraph/tree/master/trustgraph-cli/trustgraph/cli"
click node_bootstrap "https://github.com/trustgraph-ai/trustgraph/tree/master/trustgraph-flow/trustgraph/bootstrap"

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_spec_api,node_spec_ws toneAmber
class node_base_pubsub,node_base_schema,node_base_clients toneMint
class node_gateway,node_iam,node_config,node_flow_mgmt,node_librarian,node_ingest,node_extract_kg,node_embeddings,node_storage,node_query,node_rag,node_agent toneRose
class node_llm_models,node_embed_adapters,node_ocr_unstructured toneIndigo
class node_cli,node_bootstrap toneTeal
```

## Components

### Contracts

Public API and websocket specifications.

- [REST spec](https://github.com/trustgraph-ai/trustgraph/blob/master/specs/api/openapi.yaml): openapi contracts · Authoritative HTTP/OpenAPI surface for service requests and responses. · `specs/api/openapi.yaml`
- [WS spec](https://github.com/trustgraph-ai/trustgraph/blob/master/specs/websocket/asyncapi.yaml): asyncapi contracts · Websocket request/response envelopes and streaming channel contracts. · `specs/websocket/asyncapi.yaml`

### Base Library

Shared clients, messaging, schema, and service primitives.

- [Pub/Sub](https://github.com/trustgraph-ai/trustgraph/blob/master/trustgraph-base/trustgraph/base/pubsub.py): messaging abstraction · Broker-agnostic producer/consumer layer with Kafka, Pulsar, and RabbitMQ backends. · `trustgraph-base/trustgraph/base/pubsub.py`
- [Schemas](https://github.com/trustgraph-ai/trustgraph/tree/master/trustgraph-base/trustgraph/schema): service/data schema · Shared request, response, service, and knowledge schemas used across packages. · `trustgraph-base/trustgraph/schema`
- [Clients](https://github.com/trustgraph-ai/trustgraph/tree/master/trustgraph-base/trustgraph/clients): gateway/client SDK · Reusable Python clients for gateway-facing service APIs. · `trustgraph-base/trustgraph/clients`

### Flow Runtime

Gateway, workers, pipelines, retrieval, and storage services.

- [API gateway](https://github.com/trustgraph-ai/trustgraph/tree/master/trustgraph-flow/trustgraph/gateway): http/ws dispatch · Public entrypoint that serves REST and websocket endpoints and routes work to workers. · `trustgraph-flow/trustgraph/gateway`
- [IAM](https://github.com/trustgraph-ai/trustgraph/tree/master/trustgraph-flow/trustgraph/iam): auth/control service · Authentication, authorization, and identity workspace bootstrap. · `trustgraph-flow/trustgraph/iam`
- [Config](https://github.com/trustgraph-ai/trustgraph/tree/master/trustgraph-flow/trustgraph/config/service): control service · System configuration management and runtime config delivery. · `trustgraph-flow/trustgraph/config/service`
- [Flow mgmt](https://github.com/trustgraph-ai/trustgraph/tree/master/trustgraph-flow/trustgraph/flow/service): lifecycle control · Flow class definitions, startup, and runtime lifecycle management. · `trustgraph-flow/trustgraph/flow/service`
- [Librarian](https://github.com/trustgraph-ai/trustgraph/tree/master/trustgraph-flow/trustgraph/librarian): blob/document service · Object storage and document lifecycle management for large artifacts. · `trustgraph-flow/trustgraph/librarian`
- [Ingest](https://github.com/trustgraph-ai/trustgraph/tree/master/trustgraph-flow/trustgraph/decoding): decode/chunk pipeline · Document and structured-data intake: decode, parse, and chunk content. · `trustgraph-flow/trustgraph/decoding`
- [KG extract](https://github.com/trustgraph-ai/trustgraph/tree/master/trustgraph-flow/trustgraph/extract/kg): knowledge extraction · Ontology-driven and heuristic extraction into triples, entities, and contexts. · `trustgraph-flow/trustgraph/extract/kg`
- [Embeddings](https://github.com/trustgraph-ai/trustgraph/tree/master/trustgraph-flow/trustgraph/embeddings): vector pipeline · Document, graph, and row embedding generation workers. · `trustgraph-flow/trustgraph/embeddings`
- [Storage](https://github.com/trustgraph-ai/trustgraph/tree/master/trustgraph-flow/trustgraph/storage): persistence services · Capability-specific writers for knowledge, rows, triples, embeddings, and keyword index. · `trustgraph-flow/trustgraph/storage`
- [Query](https://github.com/trustgraph-ai/trustgraph/tree/master/trustgraph-flow/trustgraph/query): retrieval services · Modality-specific query services for vectors, rows, triples, SPARQL, and structured NLP. · `trustgraph-flow/trustgraph/query`
- [RAG](https://github.com/trustgraph-ai/trustgraph/tree/master/trustgraph-flow/trustgraph/retrieval): retrieval orchestration · Document and graph grounded retrieval with explainability and reranking. · `trustgraph-flow/trustgraph/retrieval`
- [Agent](https://github.com/trustgraph-ai/trustgraph/tree/master/trustgraph-flow/trustgraph/agent): orchestration runtime · ReAct, plan, supervisor, and meta-router execution over retrieval and tools. · `trustgraph-flow/trustgraph/agent`

### Adapters

Standalone runtime packages for providers and external protocols.

- [LLM adapters](https://github.com/trustgraph-ai/trustgraph/tree/master/trustgraph-flow/trustgraph/model/text_completion): text completion providers · Provider-specific text completion runtimes behind a common service abstraction. · `trustgraph-flow/trustgraph/model/text_completion`
- [Embed adapters](https://github.com/trustgraph-ai/trustgraph/blob/master/trustgraph-embeddings-hf/trustgraph/embeddings/hf/hf.py): embedding providers · Standalone embedding provider packages such as Hugging Face. · `trustgraph-embeddings-hf/trustgraph/embeddings/hf/hf.py`
- [Decode adapters](https://github.com/trustgraph-ai/trustgraph/blob/master/trustgraph-ocr/trustgraph/decoding/ocr/pdf_decoder.py): ocr/unstructured adapters · Standalone OCR and universal decoding packages used by the ingest pipeline. · `trustgraph-ocr/trustgraph/decoding/ocr/pdf_decoder.py`

### Operations

CLI, bootstrap, and developer tooling.

- [CLI](https://github.com/trustgraph-ai/trustgraph/tree/master/trustgraph-cli/trustgraph/cli): operations tooling · Operational entrypoints for IAM, workspace, flows, ingestion, queries, and inspection. · `trustgraph-cli/trustgraph/cli`
- [Bootstrap](https://github.com/trustgraph-ai/trustgraph/tree/master/trustgraph-flow/trustgraph/bootstrap): startup init · Workspace initialization, default flow startup, and topology seeding. · `trustgraph-flow/trustgraph/bootstrap`

## Connections

- REST spec → API gateway: HTTP contract · REST shapes define the gateway's public request/response surface.
- WS spec → API gateway: stream contract · Websocket envelopes and streaming events define async gateway behavior.
- Pub/Sub → API gateway: dispatch transport · Gateway routes work to backend services through pub/sub messaging.
- Schemas → API gateway: shared models · Gateway and services share canonical schemas and service contracts.
- Schemas → IAM: identity models · IAM uses shared service schemas and records.
- Schemas → Flow mgmt: flow models · Flow lifecycle and blueprint definitions use shared schemas.
- Pub/Sub → Ingest: worker transport · Ingestion workers are orchestrated as pub/sub services.
- Pub/Sub → KG extract: worker transport · Extraction runs as backend services on the messaging layer.
- Pub/Sub → Embeddings: worker transport · Embedding generation is executed by backend workers.
- Pub/Sub → Storage: worker transport · Writers consume messages and persist artifacts.
- Pub/Sub → Query: worker transport · Query services are exposed as messaging-backed workers.
- Pub/Sub → RAG: worker transport · Retrieval services are invoked through the messaging layer.
- Pub/Sub → Agent: worker transport · Agent execution is coordinated through request/response messaging.
- Librarian → Ingest: documents in · Large artifacts are fetched from the librarian before decoding and chunking.
- Ingest → KG extract: content flow · Decoded text and structure feed knowledge extraction.
- KG extract → Storage: knowledge out · Triples, rows, and provenance are written to storage backends.
- Embeddings → Storage: vector out · Embedding workers persist vectors to vector stores or indexes.
- Storage → Query: read path · Query services read from the backend-specific storage layer.
- Query → RAG: retrieval context · RAG composes answers from query results across modalities.
- RAG → Agent: grounding · Agents consume retrieved context and explainable evidence.
- LLM adapters → Agent: reasoning model · Agent patterns call shared LLM completion providers.
- LLM adapters → RAG: rerank/generate · Retrieval pipelines use model-backed generation and ranking.
- Embed adapters → Embeddings: embed provider · Embedding workers delegate to provider adapters.
- Decode adapters → Ingest: decode provider · Ingestion uses OCR and universal decoding adapters.
- CLI → API gateway: operates via API · CLI commands target the same public gateway surface as other clients.
- CLI → Bootstrap: admin flow · CLI drives bootstrap and workspace initialization workflows.
- Bootstrap → IAM: provisions · Bootstrap initializes identities and workspaces.
- Bootstrap → Flow mgmt: starts defaults · Bootstrap can seed default flows and topology.
- Clients → API gateway: sdk · Reusable clients wrap gateway-facing APIs for callers.
