Engineering a Production-Grade GraphRAG Intelligence System
Ugo Chukwu
Verified
Query Chat — Engineering a Production-Grade GraphRAG Intelligence System
Role: Founding Lead Engineer
Company context: Peerless
Public reconstruction: Query Chat by Etherlabs
Core disciplines: GraphRAG, knowledge graphs, retrieval engineering, AI agents, multi-tenant SaaS, full-stack product engineering, evaluation, security, technical leadership
Preview description
I designed and built an evidence-grounded account-intelligence system combining exact analytics, hybrid retrieval, knowledge-graph traversal, tenant isolation, and bounded AI reasoning—then reconstructed its core architecture publicly with synthetic data and reproducible evaluations.
This case study describes work completed for Peerless and demonstrates it through a fresh Etherlabs implementation. The public repository contains synthetic organizations, synthetic account data, new code, and no proprietary Peerless source, prompts, credentials, or client identities.
Query Chat: evidence-grounded account intelligence built with GraphRAG.
The outcome
Query Chat turns a fragmented account into a cited decision.
Instead of asking an operator to move between performance tables, strategy documents, customer language, prior decisions, account configuration, and operational notes, the system plans the question, retrieves the right evidence, calculates exact metrics, traverses relevant relationships, measures coverage, and returns an answer that distinguishes what is stated from what is inferred.
The result is not a generic chatbot wrapped around a database. It is an account-intelligence system designed around five guarantees:
exact numbers remain deterministic;
every conclusion has inspectable evidence or an explicit caveat;
tenant and actor scope are enforced across the API and database;
managers and clients receive different safe response contracts; and
provider failure never turns trusted evidence into a blank screen.
The manager workspace combines a concise decision answer with evidence, coverage, retrieval progress, and safe follow-up actions.
The problem: account truth was distributed across incompatible systems
The hardest account questions rarely live in one table.
“Which winning ads should we scale, and why?” may require:
exact spend, purchases, CPA, ROAS, and seven-day movement;
approved positioning, hooks, offers, and creative strategy;
customer objections and language;
attribution settings and source freshness;
relationships between audience, belief, creative, and outcome;
prior decisions and their evidence; and
knowledge of what is missing or stale.
A conventional dashboard can show metrics but cannot connect them to strategy. A conventional RAG chatbot can retrieve text but may calculate numbers unreliably, miss cross-document relationships, agree with false premises, or conceal evidence gaps behind confident prose.
The engineering challenge was therefore larger than “add chat.” I needed to design a decision system that could reason across structured and unstructured evidence without weakening numerical accuracy, authorization, privacy, or operational safety.
My role and ownership
As Founding Lead Engineer at Peerless, my ownership covered:
defining the product and system architecture;
prioritizing the account-intelligence roadmap;
designing the GraphRAG ingestion, retrieval, graph, and evidence model;
building the backend orchestration and public interfaces;
designing exact analytics and typed tool contracts;
implementing tenant, actor, and audience boundaries;
building the React product experience and evidence workspace;
designing evaluation, negative-security, and regression coverage;
iterating against production constraints and performance bottlenecks;
putting the product into client-facing workflows; and
providing technical direction as the engineering team expanded.
I was the sole engineer through July 2026 and became technical lead after the team expanded. I describe this as architecture and delivery leadership—not as an inflated people-management claim.
System design: a bounded decision engine
The core runtime follows a deliberately bounded loop:
plan → parallel tools → coverage check → bounded repair → cited answer
A role-aware decision workspace calls a typed API and bounded agent over exact analytics, GraphRAG retrieval, and a tenant-scoped provenance layer.
1. Establish immutable scope
Every request begins with an authenticated actor context containing organization, user, and role. Tenant scope is derived from the verified session; it is never trusted from arbitrary request JSON.
This scope follows the request into retrieval, analytics, graph traversal, threads, runs, evidence, gaps, actions, and feedback.
2. Build a typed query plan
The planner identifies the domains required to answer the question and selects a bounded set of tools. Depending on intent, a plan can include:
account profile retrieval;
exact performance analytics;
context-document retrieval;
hybrid knowledge search;
one- or two-hop graph traversal;
customer-voice evidence; and
decision history.
The plan is inspectable and finite. The system does not allow an unconstrained agent to call arbitrary functions indefinitely.
3. Run independent tools concurrently
Profile, analytics, retrieval, and graph tools return typed results with provenance, latency, and evidence. Independent tools execute in parallel to reduce avoidable orchestration latency.
Concurrent typed tools reduce avoidable orchestration latency before coverage evaluation.
4. Measure evidence coverage
Before synthesis, the engine checks whether the requested domains are covered, partially covered, conflicting, stale, or absent.
Missing customer voice becomes a knowledge gap. Contradictory claims remain visible as a conflict. Weak coverage lowers confidence. A repair cycle is targeted and bounded; it does not silently widen tenant scope or invent evidence.
5. Compose and enforce the audience boundary
The model may explain the supplied facts, but it cannot create exact numbers, dates, quotations, identities, or sources. A deterministic composer remains available when a provider is missing, throttled, over budget, slow, or malformed.
Finally, the API transforms the result for the audience before serialization.
GraphRAG as the precision layer
GraphRAG is the central architectural element of the system.
Traditional RAG retrieves passages that look semantically similar to a question. That is useful for recall, but account intelligence often depends on relationships that are distributed across multiple sources:
a customer objection connects to a belief;
that belief connects to a message or creative angle;
the angle appears in an ad;
the ad produces a measurable outcome;
a prior decision records what changed and why.
A vector store can retrieve the individual passages. A graph makes the relationship path inspectable and reusable.
Hybrid retrieval supplies recall; evidence-linked graph traversal supplies inspectable relationship paths.
Ingestion and normalization
The ingestion system converts heterogeneous account sources into normalized documents and chunks. Each record carries organization scope, source type, provenance, freshness, and authority metadata.
Structured sources can produce deterministic graph projections. Unstructured sources use constrained extraction with bounded schemas and retain an explicit inferred status. Retrieved text is always treated as untrusted evidence—not as an instruction to the agent.
Hybrid retrieval
The retrieval path combines:
vector similarity for semantic recall;
PostgreSQL full-text search for exact terminology and phrases;
source authority;
freshness; and
strict organization and source filtering before ranking.
Filtering before ranking is important. A broad nearest-neighbor search followed by tenant filtering is both slower and less accurate because irrelevant candidates consume the ranking window.
Evidence-linked graph traversal
Entities use organization-scoped canonical identities. Relationships and claims point back to evidence documents. Traversal is bounded to one or two hops and applies tenant scope at the starting entity, every edge, and every target.
The graph does not give the system permission to invent. It provides a precision layer for relationships that already have evidence lineage.
Coverage-aware reasoning
Graph results are evaluated alongside raw passages and exact analytics. If the graph has no supported path, the engine says so. If multiple sources disagree, the conflict remains visible. If a requested domain is absent, the answer becomes a gap or refusal—not an attractive hallucination.
Why exact analytics are separated from AI reasoning
Spend, ROAS, CPA, purchases, rankings, and trends are computed by deterministic tools.
The reasoning layer receives those values as evidence and explains what they mean alongside approved strategy context. This makes every numeric claim testable and prevents the model from rediscovering or recalculating business metrics from prose.
This separation created a clean contract:
deterministic tools own facts and calculations;
retrieval owns evidence recall;
the graph owns supported relationships;
coverage logic owns uncertainty and gaps; and
the model owns concise explanation within those boundaries.
*The agent follows a finite plan, runs independent tools concurrently, measures coverage, repairs one targeted gap, and composes a cited answer.*
Multi-tenant and audience-safe by design
Query Chat serves audiences with different legitimate needs.
A manager may need:
retrieved evidence;
confidence and domain coverage;
tool and retrieval diagnostics;
degradation state;
knowledge gaps and repair controls; and
reviewable draft actions.
A client needs a concise, accurate answer without provider details, traces, internal remediation, sensitive evidence, or manager controls.
That difference is an API contract—not a CSS decision.
Sensitive manager fields are removed from the client contract before the response leaves the server.
Manager diagnostics and client-safe answers are separate response contracts enforced before serialization.
The broader security model includes:
signed, expiring sessions;
membership-derived tenant and role scope;
cross-scope identifiers returning
404 to avoid existence disclosure;RLS on exposed tenant tables;
backend-only detailed runs, graph state, gaps, and actions;
prompt-injection screening;
server-only provider credentials;
bounded provider timeouts and spending controls; and
explicit production secret validation.
Provider resilience is a product feature
The system can use server-side AI synthesis, but it does not depend on a provider to preserve exact evidence.
When the provider is unavailable, deterministic evidence mode still returns a useful answer. Managers can see that the system degraded; clients do not receive internal provider details.
This choice mattered operationally. A model outage should not erase trusted account metrics, source citations, or the ability to explain what evidence is present.
Insight-to-action stops at a safe boundary
The public product includes one suggested action: Draft scaling brief.
Accepting it creates a reviewable artifact with the supporting evidence and recommendation. It cannot connect to or mutate an advertising platform, and it always reports that no live change was made.
This demonstrates the full insight-to-action product loop without pretending that an autonomous mutation is safe by default.
Testing and evaluation
I designed the acceptance model around failure modes that matter in production—not only happy-path chat quality.
The public 30-question golden set covers:
exact metrics;
strategic inference;
false premises;
missing data;
conflicting evidence;
prompt injection;
tenant isolation;
audience boundaries;
follow-up context; and
action safety.
API and database tests cover session integrity, planning, retrieval, analytics, citations, durable threads, actor isolation, role escalation, feedback, repairs, fallback behavior, and draft-only actions.
During the public reconstruction’s acceptance pass, a test exposed manager diagnostics still reachable in client mode. I tightened the boundary so the evidence rail, provider labels, progress diagnostics, reasoning traces, gaps, and repair controls are not rendered or serialized for clients.
That is the value of evaluation as product engineering: it changes the system, not only the score.
Production results and engineering scale
The following figures are dated historical Peerless production or private-source evidence. They are not traffic or benchmarks generated by the public Etherlabs demo.
Dated Peerless production scale and retrieval improvements—not public-demo traffic.
July 10, 2026 Peerless production snapshot
87,147 current knowledge chunks
14,685 current documents
5,078 graph entities
30,604 relationships
3,716 claims
Embedding coverage improved from approximately 54% to 99.99%
General hybrid retrieval improved from approximately 30 seconds to 1.3 seconds
Graph traversal improved from approximately 450 seconds/failure to approximately 6 seconds
August 10, 2026 private-source snapshot
approximately 15,600 query-engine lines
176 directly related tests
eight dedicated migrations
These measurements show the depth of the system and the operational work required to make its knowledge reliably retrievable. Source size is engineering context—not a business-impact claim.
What the public reconstruction proves
I rebuilt the core system as Query Chat by Etherlabs so clients and employers could inspect the engineering without exposing Peerless intellectual property or client data.
The public version demonstrates:
a working React/Vite decision workspace;
a FastAPI/Pydantic orchestration boundary;
exact analytics plus hybrid retrieval and graph tools;
stated-versus-inferred evidence presentation;
manager/client response separation;
two synthetic organizations for tenant-boundary testing;
provider-backed synthesis with deterministic fallback;
reviewable gaps and draft-only actions;
generated OpenAPI contracts;
reproducible synthetic fixtures;
CI, dependency, and secret checks; and
hosted persistence and security smoke tests against personally owned infrastructure using disposable users and synthetic data.
The sanitized Etherlabs reconstruction makes the architecture, behavior, boundaries, and evaluation inspectable with synthetic data.
Northstar Athletics, Harbor Home, their ads, metrics, findings, and screenshots are explicitly synthetic.
The same evidence-grounded workflow adapted for a narrow viewport.
The most important system-design decisions
1. Build a decision surface, not a general chatbot
The product owns a bounded account-intelligence problem. That keeps tools, evidence, evaluation, and safety contracts concrete.
2. Keep exact computation outside the model
Deterministic tools make numeric claims reproducible and let the system refuse unsupported calculations.
3. Use GraphRAG for supported relationships
Hybrid retrieval provides recall. The evidence-linked graph provides inspectable paths across beliefs, messages, creatives, decisions, and outcomes.
4. Treat coverage as a first-class output
What the system does not know is part of the answer. Missing, stale, weak, or conflicting evidence must be visible.
5. Enforce privacy before serialization
Client safety cannot depend on hidden frontend components. The server response itself must be safe.
6. Make degraded mode useful
Provider resilience should preserve exact evidence and clearly report degradation to the right audience.
7. Stop automation at a review boundary
Drafting a supported action is valuable. Performing a live mutation requires a separate authorization, audit, and execution system.
What I learned
The biggest lesson is that trustworthy AI products are built from boundaries more than prompts.
The quality unit is not an impressive paragraph. It is a reproducible decision:
scoped to the right account;
calculated from exact data;
supported by inspectable evidence;
connected through defensible relationships;
honest about missing information;
appropriate for its audience;
resilient when providers fail; and
safe to review before action.
That is the standard I use when building AI systems for real operational decisions.
Explore the work
Live demo: https://query-chat-gamma.vercel.app
Public repository: https://github.com/Etherlabs-dev/query-chat
Company context: https://peerlesscmo.com
If you are building an AI product that needs to reason across fragmented business data without sacrificing accuracy, provenance, security, or operational control, this is the kind of system architecture and end-to-end delivery I bring to the work.
Like this project
Posted Aug 12, 2026
I built an evidence-grounded account-intelligence system with exact analytics, hybrid retrieval, knowledge graphs, tenant isolation, and bounded AI reasoning.
