Concepts

Core Concepts

How VRYO models a canvas, widgets, and agent interactions — and why it's a fundamentally different approach to BI.

The AI-Native BI Model

Traditional BI tools (Tableau, Power BI, Excel) are configuration-driven: you manually select chart types, drag fields to shelves, and format each element. VRYO is conversation-driven: you describe what you need, and an AI agent builds the dashboard.

Configuration-driven (Tableau / Power BI)

User selects chart type from menu
User drags fields to shelves/axes
User formats colors, labels, legends
User arranges layout manually

Conversation-driven (VRYO)

User describes the insight they need
AI selects chart type based on data shape
AI configures axes, series, and formatting
AI arranges the layout for readability

The core data model — CanvasState, AgentPatch, and widget schemas — is designed to make this AI loop work reliably. Every widget property is Zod-validated, so the agent can't produce invalid output.

CanvasState

CanvasState is the single source of truth. It contains a revision counter and a flat map of widgets. Every time the user moves a widget or an agent patch is applied the revision increments.

interface CanvasState {
  revision: number;
  widgets: Record<string, Widget>;  // keyed by widget.id
}

Widget types

There are six widget types. Each is a discriminated union on type and validated by a Zod schema at runtime. The AI agent chooses the right type for each data scenario.

"chart"

13 chart types: bar, line, area, scatter, pie, donut, heatmap, waterfall, radar, treemap, funnel, combo, radialBar.

"table"

Virtual-scrolling table with sparklines, conditional formatting, sorting, and search.

"note"

Markdown-capable sticky note. Agent-authored commentary and insights.

"kpi"

Single-metric card with trend indicator, target progress, and sparkline.

"gauge"

Semicircular gauge with color zones and target marker. SLA & utilization.

"filter"

Interactive slicer: dropdown, checkbox, range, search. Cross-filters linked widgets.

AgentPatch

An AgentPatch is what the agent (or any external system) sends back to modify the canvas. It has an upsert list (add or update widgets) and a remove list (widget IDs to delete). The baseRevision is optimistic-concurrency metadata — if it doesn't match the current revision, the patch is still applied but flagged.

interface AgentPatch {
  agentId:      string;
  baseRevision: number;
  rationale?:   string;   // natural-language explanation
  upsert?:      WidgetInput[];
  remove?:      string[];  // widget IDs
}

tldraw shape bridge

Internally, VRYO registers custom tldraw shape utilities (vryo-chart, vryo-table, vryo-note, vryo-kpi, vryo-gauge, vryo-filter). VryoProvider bridges between tldraw's shape store and CanvasState in both directions:

CanvasState → tldraw: applyPatch() calls editor.createShapes() / editor.updateShapes().
tldraw → CanvasState: editor.store.listen() propagates resize/move back so getState() always reflects current layout.

Arrow data binding

Widget shapes have an optional dataBinding object that specifies an endpoint and params. The useArrowData hook fetches the Arrow IPC stream, deserializes it, and provides typed row data to the widget component.

// In your widget definition
const chartWidget = {
  id: "revenue-chart",
  type: "chart",
  dataBinding: {
    endpoint: "/api/vryo/data",
    params: { dataset: "sales" },
  },
};

// In a custom component
const { data, status } = useArrowData(widget.dataBinding);

Developer hooks

VRYO provides hooks for common patterns so you don't need to wire up boilerplate yourself.

useWidget(id)

Subscribe to a single widget — get its state, update it, or remove it.

useDataSource(config)

Fetch external data from REST/CSV URLs with auto-refresh and column inference.

useDashboardActions()

Add, remove, duplicate, clear, export, import — all dashboard ops.

useArrowData(binding)

Fetch and parse Apache Arrow IPC streams for high-performance data binding.

useWidgetSelection()

Track which widgets are selected on the canvas.

usePersistence(key)

Auto-save and restore canvas state to localStorage.

Templates & workspace

VRYO includes a Workspace for building dashboards without writing code. It uses the same components and APIs as the developer library — anything built in the workspace can be exported as React code.

Five pre-built templates (Sales, Marketing, Product, Finance, HR) demonstrate real-world dashboard patterns. Templates are just arrays of widget objects — you can create your own and distribute them as npm packages.