# canner/wrenai architecture

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

- Interactive diagram: https://gitdiagram.com/canner/wrenai
- Repository: https://github.com/canner/wrenai

## Overview

#### 1. Purpose and Delivery Surfaces
WrenAI is an open-source generative-BI context and execution stack: agents use governed semantic definitions to plan SQL, execute it against customer data platforms, recall business knowledge, and generate browser-side dashboards. The maintained product is a multi-language monorepo, not a monolithic web application.

Primary entry points:
- Python CLI/runtime: `core/wren/src/wren/cli.py`, `core/wren/src/wren/engine.py`
- Rust semantic planning engine: `core/wren-core/core/src/lib.rs`
- Python native bindings: `core/wren-core-py/src/lib.rs`
- Browser/WASM SDK: `core/wren-core-wasm/src/lib.rs`, `core/wren-core-wasm/sdk/src/index.ts`

#### 2. Semantic Contract: MDL
MDL is the system boundary between business context and physical data sources. It represents models, datasets, relationships, views, cubes, metrics, functions, dialect behavior, lineage, and type planning. A shared Rust base defines manifest types, building, validation/migration utilities, and Python-oriented manifest support; the JSON schema is distributed separately.

Key paths:
- `core/wren-core-base/src/mdl/manifest.rs`
- `core/wren-core-base/src/mdl/builder.rs`
- `core/wren-core/core/src/mdl/mod.rs`
- `core/wren-mdl/mdl.schema.json`

Project-local MDL, instructions, example queries, and knowledge files are intended to be versioned with a user’s project rather than stored in a hosted service.

#### 3. Governed SQL Planning Engine
`wren-core` is the Rust/DataFusion semantic engine. It transforms SQL expressed over MDL concepts into source-executable SQL: construct context and semantic objects, analyze logical plans, expand views and model relations, enforce scope/access-control stages where enabled, optimize type/timestamp behavior, then unparse into a target dialect.

Key paths:
- `core/wren-core/core/src/mdl/context.rs`
- `core/wren-core/core/src/logical_plan/analyze/plan.rs`
- `core/wren-core/core/src/logical_plan/analyze/expand_view.rs`
- `core/wren-core/core/src/logical_plan/optimize/mod.rs`
- `core/wren-core/core/src/logical_plan/unparser.rs`

This engine is a planning/rewrite layer; data execution remains behind connectors and target warehouses.

#### 4. Python Runtime, CLI, and Connectors
The `wrenai` Python package is the agent-facing operational layer. Its CLI commands manage projects/context, profile connections, query through the MDL engine, serve local capabilities, expose MCP, and package agent prompts/skills. `engine.py` bridges CLI workflows to planning and query execution; `context.py` manages project context.

Connectors share a base/factory boundary and implement backend-specific connection, SQL handling, limits, and metadata behavior for DataFusion/DuckDB and remote databases.

Key paths:
- `core/wren/src/wren/cli.py`
- `core/wren/src/wren/engine.py`
- `core/wren/src/wren/connector/base.py`
- `core/wren/src/wren/connector/factory.py`
- `core/wren/src/wren/mcp_server.py`

Material external systems include PostgreSQL, BigQuery, Snowflake, ClickHouse, Redshift, Databricks, Athena, Trino, Spark, MySQL, SQL Server, Oracle, DuckDB, and DataFusion.

#### 5. Context Retrieval and Agent Interfaces
The AI context layer combines structured MDL with markdown/business knowledge and reusable query examples. The memory subsystem indexes and retrieves this content using embeddings and a local LanceDB-backed index. Agent-facing access is available through MCP, CLI skill delivery, and framework SDKs; the agent owns orchestration and LLM selection.

Key paths:
- `core/wren/src/wren/memory/schema_indexer.py`
- `core/wren/src/wren/memory/store.py`
- `core/wren/src/wren/skills_delivery.py`
- `sdk/wren-langchain/src/wren_langchain/_toolkit.py`
- `sdk/wren-pydantic/src/wren_pydantic/_toolkit.py`

#### 6. Dashboard Build and Deployment Path
GenBI builds static/browser-side dashboard applications from project context and uses the WASM engine for in-browser query/planning capabilities. The Python GenBI subsystem composes app artifacts, validates them, and deploys to the user’s own Vercel or Cloudflare Pages account.

Key paths:
- `core/wren/src/wren/genbi/composer.py`
- `core/wren/src/wren/genbi/verify.py`
- `core/wren/src/wren/genbi/providers/vercel.py`
- `core/wren/src/wren/genbi/providers/cloudflare.py`
- `core/wren-core-wasm/sdk/src/index.ts`

#### 7. Runtime Boundaries and Packaging
Rust is the authoritative planner implementation, exposed to Python through `wren-core-py` and to browsers through `wren-core-wasm`. Python provides local CLI, connectors, project/context management, memory, and deployment orchestration. TypeScript is a thin WASM SDK surface. Releases publish independently versioned Rust crates, Python packages, WASM/npm artifacts, and agent SDKs.

Key paths:
- `core/wren-core/Cargo.toml`
- `core/wren-core-py/Cargo.toml`
- `core/wren-core-wasm/Cargo.toml`
- `core/wren/pyproject.toml`

Main entry points: [`core/wren-core/core/src/lib.rs`](https://github.com/canner/wrenai/blob/main/core/wren-core/core/src/lib.rs) (Wren Core), [`core/wren/src/wren/engine.py`](https://github.com/canner/wrenai/blob/main/core/wren/src/wren/engine.py) (Runtime engine), [`core/wren/src/wren/mcp_server.py`](https://github.com/canner/wrenai/blob/main/core/wren/src/wren/mcp_server.py) (MCP server), [`core/wren-core-base/src/mdl/manifest.rs`](https://github.com/canner/wrenai/blob/main/core/wren-core-base/src/mdl/manifest.rs) (MDL manifest builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_semantic["Semantic Planning"]
  node_mdl_schema["MDL schema<br/>JSON schema<br/>[mdl.schema.json]"]
  node_mdl_base["MDL manifest builder<br/>Rust semantic base<br/>[manifest.rs]"]
  node_planner_api{{"Wren Core<br/>Rust planning engine<br/>[lib.rs]"}}
  node_semantic_context["Semantic context<br/>planner context<br/>[context.rs]"]
  node_plan_analysis["Logical-plan analysis<br/>planner stage<br/>[plan.rs]"]
  node_plan_optimization["Plan optimization<br/>planner stage<br/>[mod.rs]"]
  node_dialect_sql["Source SQL output<br/>dialect unparser<br/>[unparser.rs]"]
end

subgraph group_python["Python Runtime"]
  node_python_bindings["Python native bindings<br/>PyO3 binding<br/>[lib.rs]"]
  node_cli["wrenai CLI<br/>Python CLI<br/>[cli.py]"]
  node_runtime_engine["Runtime engine<br/>Python orchestration<br/>[engine.py]"]
  node_connector_factory["Connector factory<br/>connector boundary<br/>[factory.py]"]
  node_memory_indexer["Context indexer<br/>embedding indexer<br/>[schema_indexer.py]"]
  node_memory_store[("Local memory store<br/>LanceDB index<br/>[store.py]")]
end

subgraph group_agent["Agent &amp; Dashboard Surfaces"]
  node_mcp_server["MCP server<br/>agent interface<br/>[mcp_server.py]"]
  node_agent_sdks["Framework SDKs<br/>agent toolkits<br/>[_toolkit.py]"]
  node_genbi_composer["GenBI composer<br/>dashboard builder<br/>[composer.py]"]
  node_wasm_sdk["Browser WASM SDK<br/>TypeScript SDK<br/>[index.ts]"]
end

node_project_context["Versioned project context<br/>project assets"]
node_data_platforms[("Customer data platforms<br/>external warehouses")]
node_hosting["User-owned hosting<br/>deployment targets"]

node_project_context -.->|"conforms to"| node_mdl_schema
node_project_context -->|"loads MDL"| node_mdl_base
node_mdl_schema -.->|"distributes contract"| node_mdl_base
node_mdl_base -->|"builds"| node_semantic_context
node_semantic_context -->|"supplies semantic objects"| node_plan_analysis
node_plan_analysis -->|"rewrites plan"| node_plan_optimization
node_plan_optimization -->|"optimized plan"| node_dialect_sql
node_planner_api -->|"contains"| node_semantic_context
node_planner_api -->|"runs"| node_plan_analysis
node_planner_api -->|"produces"| node_dialect_sql
node_python_bindings -->|"native access"| node_planner_api
node_cli -->|"invokes"| node_runtime_engine
node_runtime_engine -->|"plans through"| node_python_bindings
node_runtime_engine -->|"executes through"| node_connector_factory
node_connector_factory -->|"queries"| node_data_platforms
node_project_context -->|"indexes context"| node_memory_indexer
node_memory_indexer -->|"stores embeddings"| node_memory_store
node_mcp_server -->|"agent query access"| node_runtime_engine
node_mcp_server -->|"retrieves context"| node_memory_store
node_agent_sdks -.->|"agent tools"| node_mcp_server
node_genbi_composer -->|"builds browser app with"| node_wasm_sdk
node_genbi_composer -->|"deploys to"| node_hosting
node_wasm_sdk -.->|"WASM planner build"| node_planner_api

click node_mdl_schema "https://github.com/canner/wrenai/blob/main/core/wren-mdl/mdl.schema.json"
click node_mdl_base "https://github.com/canner/wrenai/blob/main/core/wren-core-base/src/mdl/manifest.rs"
click node_planner_api "https://github.com/canner/wrenai/blob/main/core/wren-core/core/src/lib.rs"
click node_semantic_context "https://github.com/canner/wrenai/blob/main/core/wren-core/core/src/mdl/context.rs"
click node_plan_analysis "https://github.com/canner/wrenai/blob/main/core/wren-core/core/src/logical_plan/analyze/plan.rs"
click node_plan_optimization "https://github.com/canner/wrenai/blob/main/core/wren-core/core/src/logical_plan/optimize/mod.rs"
click node_dialect_sql "https://github.com/canner/wrenai/blob/main/core/wren-core/core/src/logical_plan/unparser.rs"
click node_python_bindings "https://github.com/canner/wrenai/blob/main/core/wren-core-py/src/lib.rs"
click node_cli "https://github.com/canner/wrenai/blob/main/core/wren/src/wren/cli.py"
click node_runtime_engine "https://github.com/canner/wrenai/blob/main/core/wren/src/wren/engine.py"
click node_connector_factory "https://github.com/canner/wrenai/blob/main/core/wren/src/wren/connector/factory.py"
click node_memory_indexer "https://github.com/canner/wrenai/blob/main/core/wren/src/wren/memory/schema_indexer.py"
click node_memory_store "https://github.com/canner/wrenai/blob/main/core/wren/src/wren/memory/store.py"
click node_mcp_server "https://github.com/canner/wrenai/blob/main/core/wren/src/wren/mcp_server.py"
click node_agent_sdks "https://github.com/canner/wrenai/blob/main/sdk/wren-langchain/src/wren_langchain/_toolkit.py"
click node_genbi_composer "https://github.com/canner/wrenai/blob/main/core/wren/src/wren/genbi/composer.py"
click node_wasm_sdk "https://github.com/canner/wrenai/blob/main/core/wren-core-wasm/sdk/src/index.ts"

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_mdl_schema,node_mdl_base,node_planner_api,node_semantic_context,node_plan_analysis,node_plan_optimization,node_dialect_sql toneBlue
class node_python_bindings,node_cli,node_runtime_engine,node_connector_factory,node_memory_indexer,node_memory_store toneAmber
class node_mcp_server,node_agent_sdks,node_genbi_composer,node_wasm_sdk toneMint
class node_project_context,node_data_platforms,node_hosting toneNeutral
```

## Components

### Semantic Planning

- [MDL schema](https://github.com/canner/wrenai/blob/main/core/wren-mdl/mdl.schema.json): JSON schema · `core/wren-mdl/mdl.schema.json`
- [MDL manifest builder](https://github.com/canner/wrenai/blob/main/core/wren-core-base/src/mdl/manifest.rs): Rust semantic base · Defines manifest types, construction, validation, and migration. · `core/wren-core-base/src/mdl/manifest.rs`
- [Wren Core](https://github.com/canner/wrenai/blob/main/core/wren-core/core/src/lib.rs): Rust planning engine · Governed SQL rewrite layer built on DataFusion. · `core/wren-core/core/src/lib.rs`
- [Semantic context](https://github.com/canner/wrenai/blob/main/core/wren-core/core/src/mdl/context.rs): planner context · `core/wren-core/core/src/mdl/context.rs`
- [Logical-plan analysis](https://github.com/canner/wrenai/blob/main/core/wren-core/core/src/logical_plan/analyze/plan.rs): planner stage · Analyzes plans and expands semantic views and relations. · `core/wren-core/core/src/logical_plan/analyze/plan.rs`
- [Plan optimization](https://github.com/canner/wrenai/blob/main/core/wren-core/core/src/logical_plan/optimize/mod.rs): planner stage · Applies type and timestamp behavior. · `core/wren-core/core/src/logical_plan/optimize/mod.rs`
- [Source SQL output](https://github.com/canner/wrenai/blob/main/core/wren-core/core/src/logical_plan/unparser.rs): dialect unparser · Emits executable SQL for the target dialect. · `core/wren-core/core/src/logical_plan/unparser.rs`

### Python Runtime

- [Python native bindings](https://github.com/canner/wrenai/blob/main/core/wren-core-py/src/lib.rs): PyO3 binding · `core/wren-core-py/src/lib.rs`
- [wrenai CLI](https://github.com/canner/wrenai/blob/main/core/wren/src/wren/cli.py): Python CLI · Manages projects, profiles, queries, local serving, and agent capabilities. · `core/wren/src/wren/cli.py`
- [Runtime engine](https://github.com/canner/wrenai/blob/main/core/wren/src/wren/engine.py): Python orchestration · Bridges CLI workflows, planning, and query execution. · `core/wren/src/wren/engine.py`
- [Connector factory](https://github.com/canner/wrenai/blob/main/core/wren/src/wren/connector/factory.py): connector boundary · Selects backend-specific connection and SQL behavior. · `core/wren/src/wren/connector/factory.py`
- [Context indexer](https://github.com/canner/wrenai/blob/main/core/wren/src/wren/memory/schema_indexer.py): embedding indexer · Indexes MDL, knowledge, and example queries. · `core/wren/src/wren/memory/schema_indexer.py`
- [Local memory store](https://github.com/canner/wrenai/blob/main/core/wren/src/wren/memory/store.py): LanceDB index · `core/wren/src/wren/memory/store.py`

### Agent & Dashboard Surfaces

- [MCP server](https://github.com/canner/wrenai/blob/main/core/wren/src/wren/mcp_server.py): agent interface · `core/wren/src/wren/mcp_server.py`
- [Framework SDKs](https://github.com/canner/wrenai/blob/main/sdk/wren-langchain/src/wren_langchain/_toolkit.py): agent toolkits · LangChain and Pydantic agent integrations. · `sdk/wren-langchain/src/wren_langchain/_toolkit.py`
- [GenBI composer](https://github.com/canner/wrenai/blob/main/core/wren/src/wren/genbi/composer.py): dashboard builder · Composes static dashboard application artifacts. · `core/wren/src/wren/genbi/composer.py`
- [Browser WASM SDK](https://github.com/canner/wrenai/blob/main/core/wren-core-wasm/sdk/src/index.ts): TypeScript SDK · Exposes in-browser planning and query capabilities. · `core/wren-core-wasm/sdk/src/index.ts`

### Other components

- **Versioned project context**: project assets · Project-local MDL, instructions, knowledge, and examples.
- **Customer data platforms**: external warehouses · Remote databases plus local DuckDB and DataFusion execution.
- **User-owned hosting**: deployment targets · Vercel or Cloudflare Pages accounts.

## Connections

- Versioned project context → MDL schema: conforms to
- Versioned project context → MDL manifest builder: loads MDL
- MDL schema → MDL manifest builder: distributes contract
- MDL manifest builder → Semantic context: builds
- Semantic context → Logical-plan analysis: supplies semantic objects
- Logical-plan analysis → Plan optimization: rewrites plan
- Plan optimization → Source SQL output: optimized plan
- Wren Core → Semantic context: contains
- Wren Core → Logical-plan analysis: runs
- Wren Core → Source SQL output: produces
- Python native bindings → Wren Core: native access
- wrenai CLI → Runtime engine: invokes
- Runtime engine → Python native bindings: plans through
- Runtime engine → Connector factory: executes through
- Connector factory → Customer data platforms: queries
- Versioned project context → Context indexer: indexes context
- Context indexer → Local memory store: stores embeddings
- MCP server → Runtime engine: agent query access
- MCP server → Local memory store: retrieves context
- Framework SDKs → MCP server: agent tools
- GenBI composer → Browser WASM SDK: builds browser app with
- GenBI composer → User-owned hosting: deploys to
- Browser WASM SDK → Wren Core: WASM planner build
