DataNexus Architecture: Four Layers and Two Flows

This post maps the path from a natural-language query to the final response, showing which components run and in what order. It is the starting point of the series; the rationale behind each component choice and the experiments along the way are covered in the posts that follow.

Why routing architecture instead of a single NL2SQL pipeline

When NL2SQL is first applied to a real enterprise environment, the same problem usually appears. DDL alone does not let the LLM infer what a table named T_CUST_MST actually means, or what calculation logic “net revenue” refers to in this organization. Benchmark scores keep climbing, yet reports from real enterprise deployments still show accuracy falling below 50%. The same category of errors does not disappear just by swapping datasets.

But a single SQL path creates a different problem. Questions about term definitions or answers buried in unstructured documents are blocked. So DataNexus separates the design into two axes: injecting ontology-based business context before the LLM sees the query, and routing each question type to the appropriate execution path.

The difference from a standard RAG setup is summarized below:

Full flow

flowchart TD
    Q["Natural language question"]
    Q --> CTX["Context assembly<br/>Glossary · DDL · HoT rules injected"]
    CTX --> R{"Router Agent<br/>term_type classification"}
    R -->|"metric"| N["NL2SQL Engine<br/>NL → SQL"]
    R -->|"concept · relation"| G["Graph DBA<br/>Cypher template + LLM Fallback"]
    R -->|"unstructured doc"| V["GraphRAG Engine<br/>Documents + Knowledge Graph"]
    R -.->|"external info (Phase 2+)"| W["Web Agent"]
    N --> SE["Schema Enforcer<br/>Schema validation · RLS enforcement"]
    G --> SE
    SE --> EXEC["DB execution"]
    V --> SUP
    W -.-> SUP
    EXEC --> SUP["Supervisor<br/>HoT priority conflict resolution"]
    SUP --> ANS["Result returned"]
    ANS -.feedback.-> FEED["NL2SQL self-learning loop"]

Four things differ from a naive architecture. The context assembly step before the router is made explicit. A Schema Enforcer sits between generation and execution. When results from multiple sources conflict, the Supervisor resolves them by Hierarchy of Truth (HoT) priority. The Web Agent is a Phase 2+ external information path, shown as dashed to mark it as future scope.

Components by layer

Knowledge Layer (defining what things mean)

Routing Layer (query classification and synchronization)

Execution Layer (answering)

Verification Layer (validation and conflict resolution)

Dashboard Promotion: from Pull to Push

Everything above covers handling a single natural language query. But if the same KPI question runs every week, asking it in Chat each time is wasteful. That is the motivation for the second flow.

flowchart LR
    CHAT["Chat exploration<br/>Pull"] -.same query 3+ times.-> DETECT["Repetition pattern detected"]
    DETECT --> PROMO["Dashboard Promotion<br/>SQL parameterization + JWT RLS token"]
    PROMO --> DASH["Scheduled KPI dashboard<br/>Push"]
    GLOSS["Glossary change"] -.Lineage Drift detected.-> DASH

Queries that recur frequently in the exploration phase are automatically promoted to static dashboards. The promoted SQL carries Lineage back to the Glossary, so when a term definition changes, the dashboard is marked STALE and enters the auto-resync queue. Definition changes propagate to operational reporting without requiring manual tracking.

Together with the NL2SQL accuracy improvements described above, this promotion path forms one of the two core axes of DataNexus.

Core design principles

Context follows a Static First, Dynamic Last structure. Ontology, DDL, and HoT rules are locked into a fixed prefix block in the system prompt. Only the user question is appended dynamically. Anthropic’s prefix caching raises the cache hit rate in this structure.

Pre-execution validation has lower operating cost than post-hoc correction. The Schema Enforcer intercepts SQL immediately after LLM generation. Blocking a bad query before execution is less costly than letting it run against the DB, return an empty result, and require a retry.

Conflicts are resolved by priority table, not by asking the LLM. The same metric “churn rate” showing up as 12% from Marketing and 8% from CRM is common. The formulas differ, and both can still be valid. Asking the model “which one is right?” every time produces inconsistent answers. HoT priority is defined upfront and applied consistently.

What the series covers

• Post 7 (Phase 1): Router branching criteria and Supervisor conflict resolution
• Post 8 (Phase 1): Reaching EX 80% on a 30-question retail sample through four PDCA cycles
• Post 9 (Phase 1): Hitting BIRD 56% and the nine experiments that got ruled out
• Post 10 (Phase 1): Spider 72%: the observation that dataset characteristics determine error type more than model choice does

Three areas are intentionally out of scope here. Data warehouse modeling is covered in the DW Modeling series. Search visibility optimization is handled in the GEO series. And the development agent (Claude Code-based) used to implement DataNexus operates on a different evaluation axis than the production runtime agent, so that topic gets its own post.