How VibeBI works.

1 · Overview

VibeBI is an on-premise enterprise analytics platform that turns a raw warehouse into a governed, self-service BI service. It is built on three product surfaces that share contracts but keep responsibilities separate:

• VibeBI Desktop — the power-user and administration surface: BI Agent (reports), DG Agent (data governance), Explorer, Store, certification and access screens.
• VibeBI Web — a lightweight, read-only consumer surface for discovering and opening governed report share links.
• VibeBI Server — the headless on-prem control plane: identity, access control, report store, scheduling, audit, warehouse broker, and LLM gateway.

VibeBI ships with its own embedded agent engine. The agent does most of the drafting; human stewards and IT custodians approve and execute through certification gates — they are never the bottleneck.

2 · Architecture

The platform separates the agent runtime (on the user's laptop) from the control plane (on-prem server). Warehouse and LLM credentials never reach end-user devices.

flowchart LR
  subgraph client["User laptop"]
    DT["VibeBI Desktop"]
    SC["Agent sidecar :4580
VibeBI agent engine"]
    DT --> SC
  end
  subgraph server["On-prem server :8080"]
    AUTH["Auth / SSO"]
    BRK["Warehouse broker
read-only SQL"]
    GW["LLM gateway"]
    STORE["Report store
Postgres + object store"]
    ACL["Access control"]
  end
  CH[("Warehouse (EDW)
bronze · silver · gold")]
  WEB["VibeBI Web viewer"]
  SC --> AUTH
  SC --> BRK
  SC --> GW
  BRK --> CH
  DT --> STORE
  WEB --> AUTH
  WEB --> STORE
  STORE --> ACL
            

3 · The Alchemist (medallion)

VibeBI's scope starts at bronze — post-ingestion. It promotes data through a governed medallion: bronze → silver → gold + semantics. The single hard rule: gold is never built directly from bronze; certified silver views must exist first.

flowchart LR
  B["Bronze
source-shaped landing
source__entity"] --> S["Silver
silver_<domain>
conformed views"]
  S --> G["Gold
gold_<domain>
facts & dims"]
  G --> SEM["Semantics
entities · grain · tags"]
  SEM --> CR["Create / Web
published gold only"]
            

Stage 1 (Bronze → Silver) covers profiling, data-quality analysis, conformation, and domain/classification proposals. Stage 2 (Silver → Gold) covers entity resolution, manifest and gold-view drafting, validation, and repair loops. Physical database names are deployment configuration, not hard-coded in binaries.

4 · Semantic layer

The semantic layer is what makes reports durable. Instead of binding dashboards to physical tables, VibeBI exposes entities, grains, mappings, certified metrics, and gold-model metadata through a single contract.

• Certified metrics — steward-approved measures with expression, grain, and gold binding. One definition, reused everywhere.
• Business glossary — Company / Team / Personal scoped terms with definitions and aliases, injected into agent sessions.
• Field tags — every exposed field carries ≥ 1 data domain and a classification level.

Because reports read the semantic layer, an upstream schema change is absorbed in the silver→gold mapping — downstream reports keep working without a rewrite.

# Agent discovery contract
GetSemantics      # entities, tables, grains, mappings, certified metrics
QueryVibeBIGold  # read-only SQL against published gold for real answers

5 · Gold BI learning (self-grow loop)

Gold is not a one-shot publish. VibeBI captures demand signals from every BI agent turn — user questions, sparse/null metrics from live probes, query errors, join gaps, and entities the assistant could not answer — and turns them into steward-reviewed improvements to business drivers, manifests, and joins.

flowchart LR
  BI["BI Agent turns
chat + gold/silver probes"] --> SIG["Learning signals
catalog backlog"]
  SIG --> PROC["Process backlog
drivers · joins · hints"]
  PROC --> STW["Steward review
Gold → BI Learning tab"]
  STW --> GOLD["Approve drivers
publish manifests · build gold"]
  GOLD --> SEM["Updated semantics
fewer gaps next turn"]
  SEM --> BI
            

Stewards stay in control. Proposals create bi_learning business drivers in proposed status until approved. Manifest rebuilds for sparse metrics return to draft until re-published. Stewards can process step-by-step or run a full pipeline (process → approve → publish → build gold) from the desktop.

The BI agent receives a compact learning gaps section on later turns (sparse measures, uncovered entities, pending drivers) so it answers honestly instead of re-probing known-null columns. The DG agent uses the same backlog when regenerating business drivers.

6 · Agent engine

VibeBI runs a purpose-built embedded agent runtime — not a general chatbot. Two agent roles drive the product:

7 · Governance model

Access control uses two orthogonal planes, defined by the client and enforced on every field, query, report, and share.

Plane A — Data Domains (business topic)

Business-owned topic areas (Revenue, Supply Chain, HR Compensation), with optional sub-domains. Each domain has an owner who approves access requests — the business accountable party, not the technical table builder.

Plane B — Sensitivity tiers

Roles (RACI)

• Data Domain owner — who may access a domain; approves access requests; co-signs sensitive publishes.
• Data steward — what data means: definitions, grain, metrics, manifest approval, DQ certification, and gold BI learning (process chat signals → approve drivers → publish gold).
• Data custodian (IT) — how pipelines run: DDL execution, performance, backups, break-glass.

8 · Derived report access

This is the core access rule, and it has no bypass:

Report-level grants (roles, share links) can only narrow access — never widen it beyond underlying data entitlements. A gold model built from multiple silver tables inherits the union of their domain tags, so the owners of all inherited domains become the approvers.

9 · Deployment

100% on-premise is our edge — VibeBI runs entirely inside your network, with warehouse credentials and model keys that never leave it. The pilot is a single-VM Docker Compose install; production hardens to an HA cluster without product redesign.

On-premise is the default, not the only option. The same architecture deploys to the cloud of your choice — public, private, hybrid, or multi-cloud — so you can place the control plane and warehouse wherever your data-residency and operations strategy requires.

The server is intentionally lean — a lightweight binary that runs comfortably on commodity hardware. All agentic compute — profiling, semantic extraction, model generation, report drafting — runs distributed on each user's desktop client, not on the server. The server handles only governance, brokering, and serving, so server-side resource requirements stay minimal even as your user base grows.

For data-sensitive clients, VibeBI supports a fully air-gapped deployment: 100% on-premise, zero internet dependency, running against an in-house LLM. No data, no queries, and no metadata ever leave your network. The entire system — server, desktop client, and LLM — operates as a sealed loop inside your perimeter.

• Create agents run on user laptops (~100 concurrent creators).
• Web viewer serves casual consumers on PC and mobile (~500 concurrent).
• Production ships compiled artifacts — no source in runtime images, no source maps in prod.
• Reports are stored as .report.ts + generated HTML, rendered through ACL-gated APIs.

10 · Security invariants

Five non-negotiables hold across every deployment:

1. Warehouse credentials never on client devices — all gold/semantics flow through the server broker.
2. LLM keys never on client devices — server gateway or short-lived minted tokens only.
3. Share links are capability URLs — opaque id + SSO/ACL + short-lived render token, not static HTML paths.
4. Report access is derived from data entitlements — no standalone report permission can bypass domain + classification grants.
5. Production deploys compiled artifacts — no src/ in runtime images.

11 · Technology stack