Binexia
Binexia

Core Concepts

Widget Framework

How dashboard widgets work — types, configuration, and the rendering pipeline.

Widgets are the building blocks of Binexia dashboards. Each widget is a JSON configuration object that describes what data to show and how to display it. Widget rendering is LLM-free for cached/template hits — only the admin's Raw Query widget triggers live LLM generation.

Widget Types

kpi_card

Single metric with optional comparison period.

{
  "widget_type": "kpi_card",
  "config": {
    "metric": "revenue",
    "period": "this_month",
    "comparison_period": "last_month",
    "icon": "pi pi-dollar",
    "color": "var(--p-green-500)"
  }
}

Displays: current value, change from comparison period (%, arrow), icon, color.

metric_chart

Time-series or categorical chart.

{
  "widget_type": "metric_chart",
  "config": {
    "metric": "total_bookings",
    "dimension": "booking_date",
    "chart_type": "line",
    "period": "last_30_days",
    "color": "var(--p-primary-color)",
    "show_trend": true
  }
}

Supports: line, bar, area chart types. Dimensions determine grouping (time for line, categorical for bar).

top_n_table

Ranked table of items by metric value.

{
  "widget_type": "top_n_table",
  "config": {
    "metric": "revenue",
    "dimension": "destination",
    "period": "this_month",
    "sort_by": "value",
    "sort_dir": "desc",
    "limit": 5,
    "show_rank": true,
    "show_percentage": true
  }
}

alert_feed

Scrollable list of recent agent alerts.

{
  "widget_type": "alert_feed",
  "config": {
    "max_items": 10,
    "severity_filter": ["warning", "critical"],
    "show_timestamp": true
  }
}

raw_query

Admin-only widget. Accepts a free-text natural language question and renders the result live via the LLM pipeline. This is the only widget type that triggers the full OrchestratorAgent → AnalyticsAgent flow.

Dashboard Layout

Dashboards use a grid layout stored as JSON:

{
  "layout": [
    { "i": "w1", "x": 0, "y": 0, "w": 6, "h": 4 },
    { "i": "w2", "x": 6, "y": 0, "w": 6, "h": 4 },
    { "i": "w3", "x": 0, "y": 4, "w": 8, "h": 6 }
  ]
}

12-column grid. Each widget has a position (x, y) and size (w, h).

Rendering Pipeline

Widget config JSON
  └─► Is it a cache/template hit?
        ├─ YES → Render directly from cached data (no LLM)
        └─ NO  → Is it a raw_query?
                    ├─ YES → OrchestratorAgent → AnalyticsAgent → SQL → chart
                    └─ NO  → Fetch metric data from semantic model → render

Metric Source of Truth

All widget metrics reference tenant_semantic.metrics by name. When you change a metric definition in the semantic model, affected widgets update on next render. The system flags dependent widgets for admin review when metrics change.

Admin Tools

  • Widget Builder — Create and configure widgets visually
  • Dashboard Builder — Arrange widgets on a grid, set role visibility
  • Dashboard defaults — Set one dashboard per role as the landing page