System Architecture

Architecture & Query Pipeline

Every natural language question in Orcha Agent OS passes through a multi-stage compilation, validation, and transpilation pipeline before reaching your physical database warehouse.

The 7-Stage Query Lifecycle

1

Intent Classification & Conversational Rewriting

lib/intent-classifier.ts & lib/query-rewriter.ts

Determines whether the user's input is a quantitative data question (Text-to-SQL), an exploratory schema question, or conversational chit-chat. For follow-up questions (e.g. 'What about in 2024?'), the query rewriter uses conversational history to produce a self-contained question.

2

Semantic Vector Memory Recall

convex/semanticMemory.ts

Performs vector similarity search against previously verified natural language questions and curated golden SQL pairs. If a close match is found, the verified SQL template is injected into the prompt context to guide the model.

3

Schema Column Pruner

lib/column-pruner.ts

For databases with hundreds of tables or thousands of columns, sending the entire schema would blow out LLM token limits and introduce noise. The column pruner selects only the relevant models, dimensions, and measures needed for the question.

4

LLM Semantic SQL Generation (MDL Layer)

lib/chat-agent.ts

The LLM generates SQL not against raw database table physical names, but against the clean Model Definition Language (MDL) manifest. It queries business terms like 'revenue', 'order_count', or 'margin' without worrying about low-level joins or formula expansions.

5

WASM Semantic Transpiler & Formula Inlining

orcha-rust-engine (Apache DataFusion WASM)

The compiled Rust WebAssembly engine takes the MDL-level SQL and transpiles it into standard ANSI SQL. It automatically resolves calculated virtual columns (inlining math formulas), strips unused views, and dynamically injects join paths via Graph BFS pathing.

6

Dry-Plan SQL Validator

lib/sql-validator.ts

Runs static schema checking and dry-run query planning rules against the generated SQL. It verifies that all referenced tables and columns actually exist and catches syntax errors before any physical database connection is touched.

7

OrchaFusion Native Dialect Database Execution

lib/db-executor.ts & lib/engine/orchafusion.ts

Translates the validated ANSI SQL into the target dialect (Postgres, MySQL, SQLite, MSSQL, Oracle) and executes it securely over an encrypted connection pool. Returns structured JSON records to the UI, MCP client, or API consumer.

Why an Embedded Rust WASM Engine?

Traditional text-to-SQL frameworks rely on the LLM to write exact raw SQL dialect syntax, inline complex algebraic formulas, and remember full join syntax. This frequently leads to syntax errors, incorrect grouping, or catastrophic cartesian product joins.

In Orcha Agent OS, the LLM generates simplified queries against high-level MDL models. The Rust WebAssembly binary (compiled from Apache DataFusion) takes this abstract syntax tree (AST), optimizes the plan in memory, and transpiles it into mathematically sound native SQL in under 5 milliseconds.

Zero Runtime Garbage CollectionDeterministic Join InjectionSub-5ms WASM Latency

Automatic BFS Join Pathing

When a user asks for metrics residing in different tables (e.g., Customers, Orders, and Payments), Orcha constructs an in-memory graph where tables are nodes and foreign-key / semantic relationships are edges.

// BFS Path Discovery Example:
From: Customers ──(cust_id)──► Orders ──(order_id)──► Order_Items ──(prod_id)──► Products
✔ Result: Automatically injects 3 INNER JOIN clauses without prompt engineering.