# PowerBricks — Specifiche di Progetto & Architettura

*Visual Query Builder · 26/06/2026 · documento di progetto e build*

> **Collocazione:** modulo `app/modules/powerbricks/` dentro **MyICR Suite** — non progetto standalone.
> **Layer semantico:** condiviso con `datawarehouse/` (MyICR Suite) — PowerBricks lo usa come dipendenza, non lo ingloba.

---

## 1 · Sintesi del progetto

PowerBricks è un'applicazione desktop leggera pensata per consentire a utenti non tecnici (analisti, manager, colleghi di reparto) di interrogare autonomamente basi dati complesse senza conoscere la sintassi SQL. Il sistema si basa sul paradigma della programmazione visuale a blocchi (ispirato a Scratch/Blockly): traduce le composizioni geometriche degli utenti in query SQL standard ottimizzate ed eseguendole direttamente in locale.

Nella sua forma base l'applicazione è **read-only**: compone domande e restituisce dati, senza alcun effetto collaterale.

---

## 2 · Architettura tecnologica

Approccio ibrido Desktop/Web-View, tutto locale, per reattività sui dati, sicurezza e distribuzione semplice senza infrastrutture web. **Stesso stack di MediaTrack** — consolidato nel team.

| Componente | Tecnologia |
|---|---|
| **Frontend** | HTML/CSS/JS con la libreria open-source **Google Blockly**. Delega al motore Blockly gli incastri logici, i vincoli di forma e i colori dei mattoncini. |
| **Backend** | **Python + Flask** come API REST pura locale. Nessun rendering di pagine: riceve le strutture ad albero dei blocchi in JSON e si occupa di validazione, traduzione in SQL e interazione con i file di dati. |
| **Contenitore** | **PyQt6 + QtWebEngine**: incapsula il frontend in una finestra desktop nativa. Stesso pattern di MediaTrack in MyICR Suite — nessuna dipendenza aggiuntiva. |
| **Dati** | **DuckDB su file Parquet** (stesso substrato di MyICR Suite): interrogazioni dirette ad alte prestazioni, in locale. |

---

## 3 · Ambito dati — 4 domini logici (caso Mediaset)

La base dati aziendale è organizzata in 4 macro-domini, ciascuno rappresentato da mattoncini dedicati con colorazioni e vincoli specifici.

| Dominio | Contenuto informativo | Esempi campi / blocchi |
|---|---|---|
| **Anagrafica** | Metadati dei contenuti, informazioni strutturali di programmi, film e serie. Fuoco centrale delle relazioni. | Titolo, Regista, Anno, Genere, ID_Titolo, Codice_Opera |
| **Emesso** | Storico delle messe in onda, canali, palinsesti e dettagli temporali di trasmissione. | Data_Canale, Ora_Inizio, Canale, Durata, ID_Titolo |
| **Diritti** | Contratti, licenze di sfruttamento, scadenze e vincoli legali di trasmissione. *Semantica derivata: vedi §4.* | Codice_Contratto, Data_Inizio_Validità, Data_Scadenza, titolarità %, passaggi |
| **Box Office** | Dati economici, incassi cinematografici, performance commerciali e biglietteria delle opere. | Incasso_Totale, Presenze, Codice_Opera, Weekend_Apertura |

---

## 4 · Motore di traduzione — JOIN automatiche e logica di dominio

**Principio cardine:** l'utente finale non conosce LEFT JOIN né chiavi primarie/esterne. La complessità relazionale si risolve interamente sotto la scocca. Un **grafo delle relazioni** nel backend analizza i campi e i filtri richiesti dai blocchi e ricostruisce automaticamente i passaggi relazionali; per evitare la perdita di dati (es. un film presente in Anagrafica ma assente in Box Office) il traduttore usa sistematicamente **LEFT JOIN con perno su Anagrafica**, il dominio principale.

**Distinzione essenziale per l'implementazione.** Il grafo a LEFT JOIN **collega i domini** (Anagrafica ↔ Emesso ↔ Box Office) e per questi è sufficiente. Il dominio **Diritti**, invece, **non è esprimibile come semplice JOIN**: concetti come **titolarità %**, **passaggi consumati vs residui**, **first run vs re-run** e **inibizioni** sono misure derivate e logica condizionale, non chiavi relazionali. Richiedono un **layer di logica di business** (viste, colonne derivate, misure calcolate) interposto tra i contratti grezzi e i blocchi che l'utente compone.

È il cuore del valore — un tool generico non sa cosa sia un passaggio residuo — ed è dove si concentra la maggior parte dello sforzo di sviluppo.

### Esempio di flusso (JSON → SQL) per le JOIN inter-dominio

Input dal frontend:

```json
{
  "campi_richiesti": ["Anagrafica.Titolo", "BoxOffice.Incasso_Totale"],
  "filtri": [{"campo": "Anagrafica.Genere", "operatore": "=", "valore": "Cinema"}]
}
```

SQL compilato dal backend:

```sql
SELECT
    Anagrafica.Titolo,
    BoxOffice.Incasso_Totale
FROM Anagrafica
LEFT JOIN BoxOffice ON Anagrafica.Codice_Opera = BoxOffice.Codice_Opera
WHERE Anagrafica.Genere = 'Cinema';
```

> Una query sui diritti (es. «titoli con passaggi first-run residui nel 2027») **non** è generabile da questo solo schema relazionale: passa per il layer di business sopra descritto.

---

## 5 · Doppio input sullo stesso layer (mouse / linguaggio)

Una sola piattaforma, due modi di comporre i blocchi:

- **Mouse** (utenti non tecnici): trascinamento dei mattoncini. È l'input primario.
- **Linguaggio naturale** (evoluzione successiva): un generatore produce l'albero di blocchi a partire dal testo. L'NL **non scavalca** PowerBricks — genera l'albero, che resta **ispezionabile e correggibile** dall'utente, poi lo stesso traduttore validato lo compila. Nessuna query che sbaglia in silenzio: l'albero è il prodotto.

> Implicazione di build: layer semantico, blocchi e traduttore sono il cuore riutilizzabile; l'NL è solo un generatore testo→albero montato sopra. Costruire bene il traduttore blocchi→SQL serve entrambi gli input.

---

## 6 · Proprietà e vincoli

- **Read-only:** l'app interroga e basta — nessuna scrittura, nessun effetto collaterale.
- **Zero errori di sintassi:** l'interfaccia a blocchi impedisce fisicamente il collegamento di tipi incompatibili (es. testo dentro un filtro di data).
- **Prestazioni locali elevate:** Parquet + DuckDB processano milioni di righe in frazioni di secondo sul PC dell'utente, senza sovraccaricare i server centrali.
- **Flessibilità multidominio:** domande complesse trasversali ai 4 domini muovendo semplicemente il mouse.

---

## 7 · Sequenza di sviluppo & evoluzione

Un asse unico, senza lavoro in parallelo ad altri fronti:

1. **Layer semantico (4 aree)** — mappa campi + grafo relazioni + **logica di business dei diritti**. Il pezzo costoso e fondante.
2. **PowerBricks read-only** sopra il layer — blocchi → JSON → SQL → risultati.
3. **Generatore linguaggio naturale → blocchi** sullo stesso layer.
4. **Evoluzione (fase due)** — query → schedulazione → recapito via email (il report che arriva da solo). Read-only → read-and-deliver: l'azione è ristretta al solo recapito di un risultato, non automazione arbitraria.

> **Nodo architetturale della fase due:** lo scheduling sposta l'esecuzione fuori dal PC (serve un processo sempre attivo) → scelta **locale vs servizio**. È la prima decisione da affrontare quando si arriva alla fase due, non l'ultima.