Come VibeBI funziona.

1 · Panoramica

VibeBI è una piattaforma analytics enterprise on-premise che trasforma un warehouse raw in un servizio BI governato e self-service. È costruito su tre superfici di prodotto che condividono i contract ma tengono separate le responsabilità:

• VibeBI Desktop — la superficie per power user e amministrazione: BI Agent (report), DG Agent (data governance), Explorer, Store, schermate di certificazione e accesso.
• VibeBI Web — una superficie di consultazione leggera e in sola lettura per scoprire e aprire i link di condivisione dei report governati.
• VibeBI Server — il control plane on-prem headless: identity, controllo degli accessi, store dei report, scheduling, audit, warehouse broker e LLM gateway.

VibeBI viene consegnato con un proprio motore agent embedded. L'agent fa gran parte della stesura; gli steward umani e i custodian IT approvano ed eseguono attraverso i gate di certificazione — non sono mai il collo di bottiglia.

2 · Architettura

La piattaforma separa il runtime dell'agent (sul laptop dell'utente) dal control plane (server on-prem). Le credenziali di warehouse e LLM non raggiungono mai i dispositivi degli utenti finali.

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)

Ambito di VibeBI parte dal bronze — dopo l'ingestion. Promuove i dati attraverso un medallion governato: bronze → silver → gold + semantica. L'unica regola ferrea: il gold non viene mai costruito direttamente dal bronze; le view silver certificate devono esistere prima.

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"]
            

Lo Stage 1 (Bronze → Silver) copre profiling, analisi della qualità dei dati, conformation e proposte di domain/classificazione. Lo Stage 2 (Silver → Gold) copre risoluzione delle entità, stesura di manifest e view gold, validazione e loop di riparazione. I nomi fisici dei database sono configurazione di deployment, non hard-coded nei binari.

4 · Livello semantico

Il livello semantico è ciò che rende i report duraturi. Invece di legare le dashboard alle tabelle fisiche, VibeBI espone entità, grain, mapping, metriche certificate e metadati dei modelli gold attraverso un unico contratto.

• Metriche certificate — misure approvate dallo steward, con espressione, grain e binding gold. Una definizione, riutilizzata ovunque.
• Glossario di business — termini con ambito Azienda / Team / Personale, con definizioni e alias, iniettati nelle sessioni dell'agente.
• Tag di campo — ogni campo esposto reca ≥ 1 data domain e un livello di classificazione.

Poiché i report leggono il livello semantico, un cambio di schema a monte viene assorbito nel mapping silver→gold — i report a valle continuano a funzionare senza una riscrittura.

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

5 · Gold BI learning (ciclo di auto-crescita)

Il gold non è una pubblicazione una tantum. VibeBI cattura segnali di domanda da ogni turno del BI agent — domande degli utenti, metriche sparse/null dai probe live, errori di query, gap nei join ed entità a cui l'assistente non ha saputo rispondere — e li trasforma in miglioramenti revisionati dagli steward su business driver, manifest e join.

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
            

Gli steward restano al controllo. Le proposte creano bi_learning business driver in proposto stato finché non è approvato. Le ricostruzioni di manifest per metriche sparse tornano a bozza fino a nuova pubblicazione. Gli steward possono procedere passo dopo passo oppure lanciare una pipeline completa (elabora → approva → pubblica → costruisci gold) dal desktop.

Il BI agent riceve un compatto gap di apprendimento sezione nei turni successivi (misure sparse, entità non coperte, driver in sospeso) così risponde con onestà invece di riprovare colonne note come null. Il DG Agent usa lo stesso backlog quando rigenera i business driver.

6 · Motore agent

VibeBI esegue un runtime agent embedded progettato allo scopo — non una chatbot generica. Due ruoli agent guidano il prodotto:

7 · Modello di governance

Il controllo degli accessi usa due piani ortogonali, definite dal cliente e applicate su ogni campo, query, report e condivisione.

Piano A — Data Domain (tema di business)

Aree tematiche di proprietà del business (Revenue, Supply Chain, HR Compensation), con sotto-domain opzionali. Ogni domain ha un proprietario chi approva le richieste di accesso — la parte accountable di business, non chi costruisce la tabella tecnica.

Piano B — Livelli di sensitività

Ruoli (RACI)

• Owner del Data Domain — chi può accedere a un domain; approva le richieste di accesso; co-firma le pubblicazioni sensibili.
• Data steward — cosa significano i dati: definizioni, grain, metriche, approvazione dei manifest, certificazione DQ e gold BI learning (elabora i segnali della chat → approva i driver → pubblica gold).
• Data custodian (IT) — come girano le pipeline: esecuzione DDL, performance, backup, break-glass.

8 · Accesso derivato ai report

Questa è la regola di accesso centrale, e non ha bypass:

I grant a livello di report (ruoli, link di condivisione) possono solo restringere accesso — mai ampliarlo oltre gli entitlement sui dati sottostanti. Un modello gold costruito da più tabelle silver eredita il unione dei rispettivi tag di domain, così i owner di tutti i domain ereditati diventano gli approver.

9 · Deployment

Il 100% on-premise è il nostro vantaggio — VibeBI gira interamente all'interno della sua rete, con credenziali del warehouse e chiavi dei modelli che non la lasciano mai. Il pilot è un'installazione Docker Compose su una singola VM; in produzione si rafforza in un cluster HA senza riprogettare il prodotto.

On-premise è il default, non l'unica opzione. La stessa architettura si deploya sul cloud di sua scelta — pubblico, privato, ibrido o multi-cloud — così può collocare control plane e warehouse dove lo richiedono la data residency e la strategia operativa.

Il server è intenzionalmente snello — un binario leggero che gira comodamente su hardware commodity. Tutta la computazione agentica — profiling, estrazione semantica, generazione dei modelli, stesura dei report — viene eseguita distribuita sul client desktop di ciascun utente, non sul server. Il server gestisce solo governance, brokering ed erogazione, così i requisiti di risorse server restano minimi anche quando la base utenti cresce.

Per i clienti attenti ai dati, VibeBI supporta un deployment fully air-gapped: 100% on-premise, zero dipendenza da internet, in esecuzione su un LLM interno. Nessun dato, nessuna query e nessun metadato lasciano mai la sua rete. L'intero sistema — server, client desktop e LLM — opera come un circuito chiuso all'interno del perimetro.

• Gli agent di Create girano sui laptop degli utenti (~100 creator concorrenti).
• Il viewer web serve i consumatori casuali su PC e mobile (~500 concorrenti).
• La produzione spedisce artifact compilati — nessun sorgente nelle immagini di runtime, nessuna source map in produzione.
• I report sono memorizzati come .report.ts + HTML generato, reso tramite API protette da ACL.

10 · Invarianti di sicurezza

Cinque non negoziabili valgono in ogni deployment:

1. Le credenziali del warehouse mai sui dispositivi client — tutto il gold e la semantica passano dal broker del server.
2. Le chiavi LLM mai sui dispositivi client — solo gateway del server o token emessi a breve scadenza.
3. I link di condivisione sono URL di capability — id opaco + SSO/ACL + token di render a breve scadenza, non path HTML statici.
4. L'accesso ai report è derivato dagli entitlement sui dati — nessun permesso di report autonomo può aggirare i grant di domain + classificazione.
5. La produzione fa il deploy di artifact compilati — nessun src/ nelle immagini di runtime.

11 · Stack tecnologico