GraphRAG Configuration Guide - Architectural Overview

GraphRAG UI:

A React application where end users authenticate via Keycloak, interact with a conversational interface, and consume Server-Sent Events (SSE) streams.

Direct API Integration:

External customer applications can bypass the UI entirely and interact directly with the Conversation service over REST and SSE endpoints.

Conversations Service

Functions as the primary API facade for the GraphRAG system. It manages conversation history, validates OAuth2/JWT tokens against Keycloak, streams SSE responses, triggers workflows via webhooks, and persists session data to an embedded DuckDB database. On initial deployment, it bootstraps the workflow instance by configuring the owner account and seeding initial credentials.

Components Service

A custom Graphwise micro-service extending native vector store capabilities. It executes k-NN (k-nearest neighbors) queries against the configured vector store and returns relevant document chunks to the orchestrator.

Orchestrator (GraphRAG Workflows)

Powered by an n8n instance that coordinates the four-stage execution pipeline. It acts as the runtime configuration hub processing execution parameters and storing definitions inside a dedicated PostgreSQL database.

GraphDB

Serves as the central knowledge graph store. GraphRAG connects to GraphDB via the Model Context Protocol (MCP), exposing tools like SPARQL execution, full-text search (FTS), ontology-schema lookups, and IRI discovery to the AI agent.

Graphwise Graph Modeling

Provides the taxonomy and concept models. It is utilized during the retrieval stage to extract and expand concepts from user queries, enriching the LLM prompt context with comprehensive SKOS attributes and custom schemas.

Vector Store

Houses document embeddings and metadata. Supported providers include GraphDB Elasticsearch/OpenSearch connectors, self-hosted clusters, AWS Managed OpenSearch, Pinecone, Qdrant, and Weaviate.

LLM Providers

Third-party APIs used across the entire pipeline for intent classification, guardrails, memory compression and final answer generation. The system implements a primary and fallback model pattern for high availability.