Mappa del prodotto: l'enciclopedia completa di Multiverbe

Questa è la mappa completa di Multiverbe: come è fatta l'app, come funziona ogni schermata davanti (interfaccia) e dietro (server e database), cosa fa ciascun pianeta, come ragiona il cervello AI, come funzionano i settori e i prompt, dove il sistema impara, come sono organizzati i dati, e — sempre — il perché di ogni scelta.

È scritta perché la capisca chiunque del team, anche un cofondatore senza esperienza tecnica. Ogni sigla è spiegata alla prima occorrenza. I diagrammi sono blocchi di testo mermaid che la schermata /mappa della dashboard disegna in forma visiva.

Rapporto con le altre mappe. Questa è la mappa del funzionamento (cosa c'è e come opera). Lo stato di costruzione di ogni pezzo (vivo, in sviluppo, da migliorare, da cablare, deprecato) vive nella pagina /cantiere (source/_meta/cantiere.json), che non si ripete qui. Le decisioni hanno la loro fonte di verità nei file canon/ citati. Quando cambia il prodotto, si aggiorna prima la fonte, poi questa mappa, poi il Cantiere.

Fonte dei fatti tecnici: ricognizione reale del codice (D:\Desktop\Multiverbe\frontend\multiverbe-app) del 2026-06-04, con i percorsi dei file citati come prova.

L'architettura in un colpo d'occhio

Al centro c'è l'intelligenza artificiale (verso il cliente si chiama semplicemente "Multiverbe"; internamente "il Sole"). Attorno orbitano i pianeti operativi, ciascuno con i suoi satelliti (le sotto-funzioni).

mindmap
  root((Multiverbe AI<br/>il cervello che coordina))
    Web 🌐
      Generatore di sito
      SEO e trovabilità
      Recensioni e presenza locale
      Analytics
    Booking 📅
      Calendario e slot
      Promemoria smart AI
      Pagamenti e caparra
      Widget pubblico
    Content 🎬
      Testi e foto AI sovrana EU
      Calendario editoriale
      Pubblicazione social
    CRM 🎯
      Anagrafica clienti
      Valore cliente e churn
      Hub messaggi multicanale
      Fedelta
    Sales 💼
      Pipeline per settore
      Account venditori
      Contatto a freddo AI
      Chiamate e script
    Marketing 📣
      Campagne e distribuzione
      Pubblicita Google e Meta
      Ritorno della spesa
    Finanza 💰
      Ricavi e costi
      Fatturazione
      Previsioni AI

Il valore non sta nei singoli pianeti, ma nel fatto che il cervello legge i dati di tutti insieme e propone (o esegue) azioni che nessuno strumento isolato vedrebbe. Esempio concreto del ragionamento incrociato:

flowchart LR
  B["Booking:<br/>5 slot vuoti giovedi"] --> AI(("Multiverbe<br/>AI"))
  C["CRM:<br/>50 clienti che non tornano"] --> AI
  AI --> CO["Content:<br/>prepara una promo"]
  CO --> CH["Canale migliore<br/>(es. email):<br/>invia la promo"]
  CH --> R["Risultato:<br/>slot riempiti"]

La metafora, per Loris. L'app non è un menu di pagine. È un sistema solare in 3D: al centro il Sole (l'AI), attorno i pianeti. Si clicca un pianeta e si apre un "pannello di vetro" con dentro le funzioni vere. Alcune funzioni sono finite e collegate al database; altre sono ancora "scatole vuote" segnate come Roadmap (lo stato preciso è nel Cantiere).

Come ci si muove nell'app (il sistema solare)

L'app non usa indirizzi web diversi per ogni pagina (niente "react-router"). La navigazione è manuale, su due livelli, decisa nel codice (src/App.tsx, src/components/layout/PlanetScene.tsx, src/store/index.ts).

Livello 1 — quale superficie mostrare (App.tsx guarda l'indirizzo del browser). In ordine di precedenza: pagine di sviluppo (anteprima 3D, kitchen-sink dei componenti), pagine pubbliche senza login (il widget di prenotazione /widget/booking/:slug, il report condiviso /share/:hash, la pagina "il tuo sito è pronto" /site-builder/reveal), la Home demo /home, e infine l'esperienza principale / (il sistema solare). Qualsiasi altro indirizzo mostra il 404.

I tre cancelli prima di entrare:

Reimposta password se si arriva da un link di recupero (ha la priorità).
Login/registrazione se l'utente non è verificato.
Cancello fondatore (founder-gate): in questa fase l'app è chiusa al pubblico. Solo le email nella lista bianca (tabella founder_emails) entrano; gli altri vedono "Stiamo costruendo" e vengono disconnessi dopo pochi secondi. La difesa è a tre strati: registrazione disabilitata su Supabase, utenti non in lista bannati, e il controllo riga-per-riga del database (RLS).
Cancello onboarding: se il workspace non ha completato la configurazione iniziale, parte la procedura guidata a tutto schermo.

Livello 2 — dentro l'app (PlanetScene): la scena 3D (NucleoSphere) a tutto schermo, con sopra la navigazione di vetro. Clic su un pianeta → la camera vola verso il pianeta e si apre la sua card riassuntiva; clic sulla card → si apre il pannello pieno (PlanetPanel) con i satelliti; clic sul Sole centrale → si apre l'hub AI (chat, memoria, strategia, obiettivi; quinta funzione agenda decisa il 2026-07-03, in costruzione). I pianeti bloccati dal piano (tier) appaiono con un lucchetto e portano alla finestra di upgrade.

flowchart TD
    Start([Login OK + fondatore + onboarding fatto]) --> Scene[PlanetScene: sfera AI 3D + pianeti]
    Scene -->|clic su un pianeta| Cam[La camera vola verso il pianeta]
    Cam --> Dash[Card di vetro del pianeta]
    Scene -->|clic sul Sole centrale| AIHub[Hub AI: Chat / Memoria / Strategia / Obiettivi]
    Dash -->|clic sulla card| Panel[Pannello pieno del pianeta]
    Panel --> Tabs{Satellite scelto}
    Tabs -->|pronto| Real[Sotto-pagina con dati reali dal database]
    Tabs -->|in costruzione| Stub[Scatola 'Roadmap']
    Scene -->|pianeta bloccato dal piano| Upg[Finestra di upgrade]
    Panel -->|ESC / X| Scene

Il cervello — Multiverbe AI ("il Sole")

Questo è il cuore differenziante del prodotto, ed è reale: gira ogni giorno in produzione. Il Sole non è una chat attaccata a una dashboard. È la coscienza digitale dell'azienda del cliente: ogni giorno legge i dati dell'azienda attraverso i pianeti, li confronta con il suo settore, decide cosa conviene fare, e o lo propone o lo fa — poi ricorda tutto e ne parla quando gli si chiede.

Tre vincoli non negoziabili guidano tutta l'architettura:

(a) Nessun dato personale esce mai dall'Europa/Svizzera. Verso l'AI vanno solo numeri aggregati e alias, mai nomi o email.
(b) Deve funzionare anche se ogni modello AI è irraggiungibile. Ogni percorso AI ha un'alternativa deterministica (regole fisse) che produce comunque un risultato utile.
(c) Deve essere verificabile. Ogni esecuzione, decisione e azione è registrata.

Il codice vive in api/_inngest/ (i lavori pianificati), api/_lib/ (i motori riusabili), api/_lib/agent-actions/ (il catalogo di azioni) e api/ai/ (le risposte interattive).

3.1 L'analisi quotidiana incrociata ("i pianeti che lavorano per te")

È il rituale di punta. Founder, 2026-05-20 (citato nel codice): "i pianeti devono lavorare al posto dell'utente; l'utente apre il telefono e vede un sistema che ha lavorato durante la notte per far crescere l'azienda."

Il flusso esatto:

Sveglia (cron) alle 06:00 ora svizzera (analyze-planet-data.ts). Un orologio automatico parte una volta al giorno.
Un lavoro per ogni azienda (fan-out). Elenca i workspace attivi (con onboarding completato) ed emette un evento per ciascuno. Perché: isolamento. Se i dati di un'azienda sono guasti e il suo lavoro fallisce, tutte le altre vengono analizzate lo stesso. Inngest (il motore di flussi che ha sostituito i vecchi n8n + Python) parallelizza con un tetto di 5 lavori in contemporanea.
Per ogni azienda, in passi salvati uno per uno (così sopravvivono a un riavvio): calcola le metriche dei pianeti → carica i benchmark di settore → carica l'identità del Sole → ragiona e salva.

Da dove vengono i numeri (planet-metrics.ts): un file volutamente deterministico e senza dati personali. Calcola solo numeri aggregati, mai nomi.

Pianeta	Tabelle lette	Metriche chiave
Booking	`bookings`	prenotazioni 30 giorni, cancellazioni, tasso di cancellazione, in arrivo 7 giorni
CRM	`crm_contacts`	contatti totali, rischio abbandono (avevano speso, fermi da oltre 60 giorni), nuovi lead 7 giorni, clienti che tornano
Sales	`deals`	trattative aperte, valore aperto (CHF), trattative ferme (>14 giorni senza attività), tasso di chiusura
Web	`form_submissions`, `reach_audits`	contatti dal sito 7/30 giorni, punteggio di trovabilità

Perché solo numeri aggregati. Regola 4 del codice: i dati personali non devono mai raggiungere un modello fuori dall'Europa. Facendo in modo che lo strato delle metriche produca solo numeri, l'architettura garantisce per costruzione che il cervello veda tutto ciò che gli serve senza mai toccare un nome o un'email.

I benchmark di settore (sector-benchmark.ts): carica dalla tabella knowledge_packs i parametri di riferimento del settore (es. il tasso di no-show tipico: ristorante 8%, hotel 15%, bar 10%). Se mancano, il cervello produce comunque le sue osservazioni, solo senza il confronto.

Il ragionamento (agente Claude con strumenti). Il sistema costruisce un "agent loop": al modello (Claude Sonnet 4.6) si danno strumenti per leggere le metriche e i benchmark e uno per registrare un'osservazione. Gli si chiede di registrare 3-6 osservazioni, saltando i pianeti senza dati. Importante: gli strumenti sono di sola lettura su numeri già anonimi — nessuno strumento di scrittura qui, quindi il modello non può "agire" durante l'analisi.

I colli di bottiglia che rileva (i modi ricorrenti in cui una PMI perde soldi in silenzio):

Cancellazioni/no-show sopra la media di settore.
Clienti che non tornano (rischio abbandono, fermi da oltre 60 giorni).
Nuovi contatti non convertiti (arrivati da pochi giorni, ancora senza acquisto).
Trattative ferme da oltre due settimane.
Contatti dal sito da richiamare in fretta.

La gravità è a quattro livelli: info (fatto neutro), opportunita (soldi sul tavolo), allarme (perdita in corso da fermare), critico (il più grave). Serve a ordinare la Home (le poche cose che contano oggi) e diventa il "peso di importanza" quando l'osservazione entra nella memoria viva.

L'alternativa deterministica. Se manca la chiave del modello o il fornitore è giù, una versione a regole fisse produce le stesse cinque osservazioni dai numeri, tradotta in 4 lingue (it/de/fr/en). Perché: l'azienda apre comunque il telefono e trova un riassunto utile, corretto e nella sua lingua. L'AI è un miglioramento, non una dipendenza.

Il salvataggio è idempotente: rigenera le osservazioni fresche del giorno senza cancellare quelle che l'utente ha già visto, scartato o su cui ha già agito.

3.2 Le azioni autonome ("il Sole che agisce")

Rilevare i problemi è metà del prodotto. L'altra metà (sole-actions.ts): il Sole non solo propone, fa. Gira sullo stesso evento giornaliero dell'analisi, ma con un prompt separato.

Il catalogo di azioni (agent-actions/registry.ts): ogni azione ha una parte che decide il bersaglio (lato server, i dati personali restano qui) e una che esegue davvero. La stessa definizione è usata sia dal lavoro automatico sia dal bottone "Approva" — così non c'è divergenza tra "cosa farebbe il Sole" e "cosa succede se clicchi approva".

Azione	Pianeta	Cosa fa	Protezioni
Recupero cliente (win-back)	CRM	Email a un cliente di valore fermo da >60 giorni	valore >0, consenso, tetto invii, niente doppioni per 30 giorni
Richiesta recensione	CRM	Chiede una recensione a chi è stato servito da poco	servito ≤14 giorni, consenso, niente doppioni per 60 giorni
Follow-up lead	CRM	Ricontatta un contatto recente senza acquisto	arrivato ≤7 giorni, consenso, niente doppioni per 14 giorni
Bozza contenuto	Content	Prepara una bozza social stagionale (non pubblica nulla)	una ogni 7 giorni
Promemoria prenotazione	Booking	(già live e in automatico) ricorda al cliente l'appuntamento	strategia per settore, niente doppio invio

Il testo delle email è per settore e per lingua: il sistema mappa il settore a una "famiglia" (ospitalità, bellezza, fitness, salute, immobiliare, professionale, generico) che sceglie il tono — informale ("tu") per ospitalità/bellezza/fitness, formale ("lei") per salute/professionale/immobiliare.

La macchina dell'autonomia (spento / proponi / auto) è il cuore della fiducia. Due strati:

Per pianeta: off = interruttore di sicurezza (lo strumento non viene nemmeno dato al modello); propose = predefinito (l'azione diventa una scheda "da fare", mai eseguita); auto = eseguita e registrata.
Per tipo di azione (la fiducia si guadagna per compito, non per pianeta): dopo 3 approvazioni dello stesso tipo di azione, quel tipo viene "promosso ad auto" e il Sole inizia a farlo da solo. Un rifiuto non revoca una promozione già ottenuta. L'interruttore off del pianeta domina sempre su tutto.

Perché una scala a 3 approvazioni e mai "auto" implicito. Costruisce la fiducia in modo graduale e mirato. Un ristoratore può fidarsi di "manda la richiesta di recensione" da sola dopo tre buone prove, e voler comunque controllare ogni recupero cliente. Se la lettura del database fallisce, il sistema degrada a propose, mai ad auto: è un fail-safe (lo stato sicuro è "chiedi all'umano").

stateDiagram-v2
    [*] --> Propose: predefinito per ogni pianeta (MAI 'auto' implicito)
    Propose: PROPOSE - propongo, non eseguo
    Auto: AUTO - eseguo da solo
    Off: OFF - interruttore di sicurezza
    Propose --> Propose: 1a e 2a approvazione (contano verso la promozione)
    Propose --> Auto: 3a approvazione dello stesso tipo (soglia = 3)
    Propose --> Propose: rifiuto 'Non ora' (registra, non promuove)
    Auto --> Auto: rifiuto occasionale (la promozione gia ottenuta resta)
    Propose --> Off: il titolare spegne il pianeta
    Auto --> Off: il titolare spegne il pianeta
    Off --> Propose: il titolare riaccende
    Off --> Auto: il titolare imposta direttamente auto

A prova di doppione (difesa in profondità). Tre strati indipendenti evitano di assillare il cliente o di mandare due volte la stessa email: un controllo "ho già deciso qualcosa di simile per questo contatto di recente?", un controllo "esiste già questa scheda oggi?", e una scrittura in due fasi (prima si "prenota" la decisione, poi si manda l'email, poi si conferma) — così un riavvio non rimanda mai due volte.

Sicurezza dati. Il modello non vede mai un destinatario: il nome e l'email reali restano lato server; al modello va un alias (es. "M. <c_ab12cd34>").

3.3 Dove impara e la memoria viva

(Trattata in dettaglio nella sezione Dove impara Multiverbe.) In breve: il Sole ricorda fatti ed episodi di ogni azienda in una "memoria viva" e li ritrova per significato; rafforza gli schemi che si ripetono; e distilla dai contenuti che il titolare approva la voce del marchio. Non c'è "addestramento" del modello: si chiama RAG (recupero di informazioni dalla memoria) più rinforzo degli schemi.

3.4 L'identità (una voce, quattro lingue) e la chat

Tutta la personalità del Sole vive in un solo posto (sole-identity.ts): ogni prompt parte da lì e aggiunge solo il proprio compito. È consapevole del ruolo (parla diversamente al titolare e a un collaboratore, e con un collaboratore non espone dati sensibili di proprietà o finanziari), consapevole della lingua (quattro pacchetti completi it/de/fr/en, con fallback "mondo-ready" per altre lingue), e parla in prima persona plurale ("noi"), sempre dalla parte dell'azienda e fondato solo sui dati reali (non inventa numeri), in stile anti-slop (niente finto entusiasmo, niente emoji, niente trattini lunghi).

La chat (sole-ask.ts) è una risposta "fondata": quando gli si fa una domanda, il Sole recupera i ricordi rilevanti + i numeri vivi dei pianeti + le osservazioni di oggi, risponde con Sonnet 4.6, e salva lo scambio in memoria (così impara dall'uso).

3.5 Il motore agentico, lo smistamento dei modelli e il gateway sovrano europeo

Motore riusabile (agent-core.ts): un unico "ciclo a strumenti" controllato (con tetto di passi e di token, conteggio dei costi, cattura leggibile degli errori del fornitore) su cui poggiano tutti gli usi del cervello. La logica di sicurezza (autonomia, dati personali, scelta del bersaglio) sta fuori dal modello, nel codice deterministico: il modello sceglie solo tra candidati già risolti, già protetti e già anonimi.
Smistamento modelli: l'aspirazione è Sonnet ~60% (verso l'utente), Haiku ~30% (interni), Opus ~10% (strategici), più Mistral per le email (EU), Kimi per il generatore di siti, Gemini per il multimodale. Vietati DeepSeek e OpenRouter. Oggi, nella realtà del codice, quasi tutto gira su Sonnet 4.6; lo smistamento 60/30/10 è ancora da realizzare (è un'ottimizzazione di costo da fare quando i volumi lo giustificano).
Gateway sovrano europeo (_lib/sovereign/): ogni chiamata ai modelli per i contenuti passa da un'unica "porta" che garantisce per costruzione che i dati restino in Svizzera/UE. Filtra i dati personali, sceglie un fornitore europeo (Vertex EU per Gemini/Claude, Mistral in Francia per le email, Imagen EU per le immagini) e — se nessun fornitore sovrano è disponibile — si blocca con un errore (503), senza mai ripiegare di nascosto su un fornitore non europeo (fail-closed). I fornitori vietati sono bloccati nel codice. Perché: la responsabilità penale del founder sotto la legge svizzera (revFADP) arriva a CHF 250.000; la promessa "AI sovrana ospitata in Svizzera" è insieme il fossato competitivo e lo scudo legale, e l'unico modo di garantirla è rendere il sistema incapace di sbagliare.

flowchart TD
    CRON["Sveglia 06:00 Europe/Zurich"] --> LIST["Elenca le aziende attive"]
    LIST -->|"un evento per azienda"| EV(["Evento: analizza azienda"])
    EV --> A["Ramo ANALISI"]
    EV --> S["Ramo AZIONE (il Sole che agisce)"]
    A --> M["Metriche dei pianeti (solo numeri, niente dati personali)"]
    M --> B["Benchmark di settore"]
    B --> LOOP{"Chiave del modello presente?"}
    LOOP -->|Si| AGENT["Agente Claude Sonnet 4.6: registra 3-6 osservazioni"]
    LOOP -->|"No / errore"| RULE["Alternativa deterministica (it/de/fr/en)"]
    AGENT --> PERS["Salva osservazioni (idempotente)"]
    RULE --> PERS
    S --> CTX["Risolvi candidati (PII lato server)"]
    CTX --> GATE{"Autonomia per tipo azione"}
    GATE -->|off| KILL["Non agire"]
    GATE -->|propose| PROP["Proponi scheda 'da fare'"]
    GATE -->|auto| EXEC["Esegui davvero -> 'fatto per te'"]
    PERS --> HOME["Home: 'Spunti di oggi' + 'Fatto per te'"]
    PROP --> HOME
    EXEC --> HOME
    CRON2["Sveglia 07:00: sincronizza memoria"] --> MEM["Memoria viva (stato + episodi)"]
    PERS -.->|"osservazioni del giorno"| MEM
    MEM --> ASK["Il Sole risponde alle domande (RAG)"]

I sette pianeti, uno per uno

Ogni pianeta è un mondo di funzioni ("satelliti"). Qui per ciascuno: a cosa serve (e perché), i satelliti con il davanti (cosa vede l'utente) e il dietro (quali endpoint del server e quali tabelle del database), e lo stato reale. Legenda stato: ✅ pronto · 🟡 parziale · ⚪ scatola vuota (Roadmap). Lo stato vivo e aggiornato è sul /cantiere.

Disponibilità per piano (chi sblocca cosa): Web/Booking/CRM su tutti i piani; Content e Sales dal Pro; Marketing e Finanza dal Business. I pianeti bloccati non compaiono nemmeno nel 3D: in navigazione hanno un lucchetto.

🌐 Web — "il tuo sito e la tua presenza online"

Perché (per Loris): dare al cliente un sito professionale generato dall'AI in ~20 minuti, più gli strumenti per essere trovato (SEO) ed essere a norma (cookie/privacy). È la fondazione del traffico: per questo ha dieci satelliti, più di tutti.

Satellite	Cosa fa l'utente	Dietro (endpoint + tabelle)	Stato
Generatore di sito	Un wizard a 7 passi crea un sito completo	`POST /api/site-builder/start` → `sites`, `ai_generation_jobs`	✅
Analytics	Visite, conversioni, funnel	aggregatore (GA4/GSC ancora simulati)	🟡
SEO / trovabilità	Punteggio + correzioni con un clic	`POST /api/reach/audit`, `/auto-fix`	✅
Presenza locale (NAP)	Coerenza nome/indirizzo/telefono su Google	`POST /api/reach/nap-check`	🟡
Conformità	Stato GDPR/cookie del workspace	banner Klaro + checklist	🟡
Email Hub, Blog, Recensioni, Mappa di calore, Lead Magnet	(in sviluppo)	—	⚪

Il generatore di sito in dettaglio. Davanti: 7 passi (conferma settore → template → identità di marca → foto → testi → genera anteprima → pubblica). Dietro, una pipeline AI a 6 stadi asincrona (dura 15-30 minuti, ben oltre il limite di una singola richiesta server): si accoda un messaggio su una coda (Upstash QStash) verso un "worker" che esegue gli stadi con salvataggi intermedi, un tetto di spesa per piano (Starter 5 / Pro 10 / Business 15 CHF) e un controllo di qualità con ritentativi se il punteggio è sotto 85.

flowchart TD
    U[Wizard 7 passi] -->|POST /site-builder/start| Start[Crea sito + lavoro<br/>anonimizza i dati · accoda in coda]
    Start -->|202 + controllo ogni 2s| U
    Start -->|messaggio in coda| Worker[/worker · max 5 min/]
    Worker --> S1[1 - Stratega di marca · Opus]
    S1 --> S2[2 - Direttore artistico · Opus]
    S2 --> Loop{Per ogni pagina}
    Loop --> S3[3 - Copy · Kimi K2.6 + QA Sonnet]
    S3 --> S4[4 - Immagini AI · Imagen/Flux EU]
    S4 --> S5[5 - Revisore conversioni · Opus]
    S5 --> S6{6 - Revisore senior · punteggio >= 85?}
    S6 -->|si| OK[Pagina approvata]
    S6 -->|no, max 3 ritentativi| S3
    OK --> Loop
    Loop -->|tutte fatte| Done[Stato: anteprima]
    Done -->|pubblica| Pub[Aggiunge slug.multiverbe.app su Vercel · stato: pubblicato]
    Start -.->|costo oltre il tetto| Capped[Stato: bloccato per costo]

La pubblicazione è "zero-touch": aggiunge il sottodominio {nome}.multiverbe.app al progetto Vercel dei siti clienti via API, segna il sito come pubblicato e avvisa i motori di ricerca.

📅 Booking — "le prenotazioni, in automatico" (il pianeta più completo ✅)

Perché: far prenotare i clienti finali a tutte le ore da soli (widget sul sito), con calendario, regole anti-no-show e promemoria automatici. Sostituisce Treatwell/Calendly togliendo le commissioni. Dati reali in produzione: 28 prenotazioni, 16 servizi → è già in uso.

Satellite	Cosa fa l'utente	Dietro	Stato
Calendario	Vede/crea/conferma prenotazioni	`/api/booking/create, confirm, update, cancel`	✅
Risorse / Team / Regole	Configura tavoli, orari, acconti, penali no-show	`booking_settings, booking_services`	✅
Notifiche / Sync	Promemoria SMS/email/WhatsApp · calendari esterni	(promemoria smart già live)	⚪ interfaccia

Il flusso prenotazione. Lato pubblico (cliente finale, senza login) il widget è incorporabile sul sito: sceglie servizio → vede gli slot liberi (calcolati al volo da orari, durata, buffer e prenotazioni esistenti) → compila i dati con il consenso → riceve l'email. Lato titolare, alla conferma parte un promemoria intelligente (Inngest) la cui tempistica dipende dal settore: alto no-show → avviso a 2 ore prima; medio → 12 ore; basso → la sera prima.

sequenceDiagram
    autonumber
    actor Cliente
    participant W as Widget pubblico
    participant API as API Booking
    participant DB as Database
    participant ING as Promemoria smart
    actor Titolare
    Cliente->>W: Apre il widget
    W->>API: Chiede servizi e slot liberi
    API->>DB: Legge prenotazioni e blocchi
    Note over API: Calcola slot al volo (orari, durata, buffer)
    API-->>W: Slot disponibili
    Cliente->>W: Sceglie slot + dati + consenso
    W->>API: Crea prenotazione + token di annullamento
    API->>DB: Salva (in attesa)
    API->>ING: Programma il promemoria (per settore)
    Titolare->>API: Conferma
    API->>DB: Stato = confermato
    API-->>Cliente: Email di conferma
    ING-->>Cliente: Promemoria prima dell'appuntamento

Perché: generare post, immagini e (in arrivo) video nel marchio del cliente, nei formati giusti per ogni social, senza che lui sappia nulla di marketing. Tabelle pronte ma ancora a zero righe: motore spedito, non ancora usato in produzione.

Davanti: tre schede — Crea (scopo → social → guarda), Calendario, Risultati. Dietro: ogni generazione passa dal gateway sovrano europeo; se nessun fornitore EU è configurato, si blocca (503) invece di ripiegare su un fornitore non europeo. Sopra ci si mette una "lente esperta" (regole della piattaforma + schemi di copywriting AIDA/PAS + psicologia del colore) e l'identità del marchio.

flowchart LR
    U[Content Studio<br/>scopo -> social -> guarda] -->|genera| Auth[Verifica accesso + piano]
    Auth --> Lens[Identita del marchio + lente esperta]
    Lens --> Gate{Fornitore EU configurato?}
    Gate -->|si| PII[Filtro dati personali] --> Vertex[Vertex AI EU] --> Persist[Salva senza dati personali]
    Gate -->|no| Fail[503: serve un fornitore sovrano<br/>NESSUN ripiego non-EU]

🎯 CRM — "il fascicolo di ogni cliente" (✅)

Perché: tenere in un solo posto la storia di ogni cliente già acquisito (mentre Sales è per i potenziali): chi è, quanto vale, cosa gli hai scritto, i punti fedeltà. Dati reali: 38 contatti.

Satellite	Cosa fa	Dietro	Stato
Contatti	Rubrica unificata, ricerca, segmenti	`crm_contacts`	✅
Timeline	Storia interazioni multicanale	`contact_events`	✅
Valore cliente	LTV, rischio abbandono, segmenti	`crm_segments`	✅
Fedeltà	Punti, referral, livelli Gold/Silver/Bronze	`crm_loyalty_transactions`	✅
Messaggi	Casella unica WhatsApp/SMS/email/IG dal CRM	`/api/messages/send`	✅
Feedback / NPS	(in sviluppo)	—	⚪

💼 Sales — "la pipeline per chiudere nuovi clienti" (✅, il più ricco lato logica)

Perché: è lo strumento di Loris e dei venditori: gestire i potenziali clienti, spostarli per fasi fino alla firma, fare contatto a freddo via email, gestire le chiamate, e vedere chi vende di più. Multi-venditore con permessi. Dati reali: 12 trattative, 10 pipeline, 58 fasi, 3 sotto-account venditori.

Satellite	Cosa fa	Dietro	Stato
Pipeline	Kanban trattative per fasi, vista titolare/venditore, KPI, export	`sales_pipelines`, `deals`	✅
Contatto a freddo	Sequenza email a 3 passi	`/api/sales/generate-outreach`	✅
Chiamate	Coda chiamate + script + esito	`contact_events`	✅
Report	KPI vendite	aggregati	✅
Previsione AI / Sotto-account	(in sviluppo)	`sales_seller_subaccounts`	🟡/⚪

📣 Marketing — "tutte le campagne in un posto" (⚪ scatola vuota)

Perché: orchestrare campagne multicanale, pubblicità (Meta/Google/LinkedIn), newsletter e ritorno della spesa in un unico punto. Pianificato dopo l'MVP (Q2 giugno '26), solo piano Business. Oggi è quasi tutto segnaposto — coerente con la roadmap, da non promettere ai primi clienti come "live".

💰 Finanza — "i conti, senza cassa fisica" (⚪, settimo pianeta, MVP+)

Perché: contabilità gestionale e fatturazione. Promosso a MVP+ il 21 maggio. Nessun codice ancora (0%). Owner: Loris. Nota: la scena 3D mostra ancora 6 pianeti; aggiungere Finanza è un lavoro grafico aperto.

☀️ L'hub AI (il Sole)

Non è un pianeta orbitante: il clic sul centro apre cinque funzioni — Chat (chiedi al Sole, risposta fondata sui dati), Memoria/Brain (cosa sa l'AI dell'azienda), Strategia, Obiettivi, Agenda (vista calendario unificata del futuro, gemella del Diario; decisione 2026-07-03 v205, fase 1 in costruzione — vedi 02-product.md § Agenda del Sole). Sotto, lo "strato agentico" già attivo: esecuzioni registrate (agent_runs), decisioni (agent_decisions), conteggio token, e i lavori automatici del cervello.

Le schermate non-pianeta

Sopra la scena vivono: Impostazioni (8 schede: profilo, fatturazione, email, firma, notifiche, outreach, sito, social), Fatturazione (tabella prezzi Stripe + stato abbonamento + portale), Generatore di sito, Osservabilità lavori sito (founder), Dettaglio trattativa, Cmd+K (palette comandi), Banner cookie. Più le pagine pubbliche senza login già citate (widget prenotazione, report condiviso, "il tuo sito è pronto").

Onboarding: i primi tre minuti del cliente

Il momento più fragile nella vita di un software è il primo accesso. Se l'utente vede una pagina bianca con scritto "crea il tuo primo contatto", molla. Se vede la sua attività già rispecchiata, resta. Per questo l'onboarding di Multiverbe è basato sul settore: quando un parrucchiere si iscrive, non trova una dashboard vuota, ma KPI tipici del suo mestiere, le fasi di vendita giuste, modelli di documenti, idee di post e un'AI già "istruita" sul mondo dei parrucchieri.

Il flusso (obiettivo: ~3 minuti):

flowchart TD
    W[Benvenuto] --> M[Scegli la macro-categoria<br/>5 famiglie di settori]
    M --> S{Trovi il tuo settore?}
    S -->|si| Seed[Settore scelto]
    S -->|no, 'altro'| AI["Raccontami della tua azienda<br/>l'AI deduce il settore (max 4 domande)"]
    AI --> Seed
    Seed --> Pre[Predisposizione dei dati:<br/>KPI + pipeline + template + idee social<br/>+ seme AI del settore]
    Pre --> Work[Crea il workspace]
    Work --> Tour[Tour di 60 secondi]
    Tour --> Pay[Piano / prova 10 giorni]

Esistono due versioni: V1 (attiva di default) e V2 (più ricca, con 18 settori e l'aiuto AI; pronta ma dietro un interruttore spento, VITE_ONBOARDING_V2). Il fallback AI (sector-deduction.ts) capisce l'azienda da una frase libera in qualunque lingua e la mappa a uno dei settori canonici, salvando solo un'impronta (hash) della conversazione, mai il testo grezzo.

Settori e prompt: il prodotto che "conosce il mestiere"

La grande scommessa di prodotto è una sola: Multiverbe è consapevole del settore. Questo si realizza a tre livelli, tutti dinamici (cambiano in base al settore del cliente, non sono testo fisso uguale per tutti).

1. Il seme AI del settore (ai_brain_seed). Ogni settore porta un breve testo-seme che dice al Sole "come parla e cosa conta per questa attività". I settori sono 22 nel database (18 nel codice di riserva), organizzati in 5 macro-categorie: Ospitalità, Salute e Bellezza, Servizi Professionali, Vendita, Eventi e Creativi. Ogni settore porta con sé anche: KPI di default, fasi di pipeline, modelli di documenti, idee di calendario social, servizi tipici. I dati arrivano prima dal database (sempre aggiornabili senza toccare il codice), con il codice come riserva.

2. Le "costituzioni" di design del sito. Per generare un sito bello servono regole da designer senior specifiche per settore (un ristorante non è uno studio dentistico). Oggi esiste solo quella del ristorante su 22 settori: è il principale lavoro aperto per uniformare la qualità dei siti fuori dall'ospitalità. La pipeline a 6 stadi compone i prompt al volo dal settore + il contesto del marchio (non sono stringhe fisse).

3. La "lente esperta" dei contenuti. Il motore Content impila strati di conoscenza riusabile: regole delle piattaforme social, schemi di copywriting (AIDA, PAS, JTBD), psicologia del colore per settore, contesto di mercato. Così il contenuto non è generico ma ragionato come lo farebbe un social media manager.

flowchart LR
    Sec[Settore del cliente] --> Seed[Seme AI del settore]
    Sec --> KPI[KPI di default]
    Sec --> Pipe[Fasi di pipeline]
    Sec --> Doc[Modelli di documenti]
    Sec --> Soc[Idee social]
    Seed --> Sole((Il Sole<br/>parla 'da settore'))
    KPI --> Dash[Dashboard pre-compilata]
    Pipe --> Dash
    Doc --> Dash
    Soc --> Dash

Perché. È il fossato del prodotto: la concorrenza dà uno strumento vuoto e generico; Multiverbe dà uno strumento che il primo giorno sembra "fatto su misura" per quel mestiere. Più il settore è curato, più alto è il valore percepito e più basso il tempo al primo valore.

Dove impara Multiverbe (la memoria viva)

Non c'è alcun "addestramento" del modello AI. "Imparare", qui, sono tre meccanismi concreti e trasparenti:

Memoria viva (RAG). Quattro tabelle (entity_memory, entity_profile, entity_patterns, entity_interactions) fanno crescere il Sole con l'azienda: ogni giorno la memoria si arricchisce di fatti (lo stato attuale, aggiornato) ed episodi (la storia, che scade dopo 60 giorni). Quando si fa una domanda, il Sole ritrova i ricordi giusti per significato (non per parola). La ricerca per significato usa gli "embedding" (un modo di trasformare i testi in numeri per confrontarli); il fornitore scelto è Voyage. Oggi la chiave Voyage è spenta, quindi la memoria gira in versione ridotta (per parola chiave + recenza): accenderla è un miglioramento ad alta leva e basso rischio.
Rinforzo degli schemi. Quando uno schema si ripete, il sistema ne aumenta la "confidenza" e il "numero di volte usato". Gli schemi si rafforzano con la ripetizione.
La voce del marchio dai contenuti approvati. Quando il titolare approva un contenuto, quel pezzo entra in content_brand_signals; il Sole ne distilla la voce e i divieti del marchio. È un anello chiuso: approvazione umana → DNA del marchio → bozze future migliori. È l'antidoto allo "slop" (i testi generici da robot).

flowchart TD
    Q[Domanda dell'utente] --> RED[Ripulisci i dati personali]
    RED --> CFG{Chiave Voyage presente?}
    CFG -->|si| EMB[Embedding della domanda] --> RPC[Cerca per significato<br/>similarita x importanza x recenza]
    CFG -->|no / errore| FB[Riserva: recenza + importanza + parola chiave]
    RPC --> TOP[I 6 ricordi piu pertinenti]
    FB --> TOP
    TOP --> CTX[Contesto: Memoria + Stato pianeti + Oggi]
    CTX --> GEN[Claude risponde, fondato sui dati]
    GEN --> REM[Salva la conversazione: il Sole impara dall'uso]

Perché RAG e non addestramento. (a) Ogni azienda ha la sua memoria isolata: addestrare un modello per cliente è assurdo ed espone a fughe tra clienti. (b) I dati cambiano ogni giorno: un addestramento sarebbe vecchio appena finito. (c) Conformità: si può mostrare quali ricordi hanno informato una risposta, e si può cancellare la memoria di un cliente su richiesta (diritto all'oblio) — impossibile da pesi addestrati.

Il modello dei dati e l'isolamento tra clienti

I dati vivono in un database PostgreSQL su Supabase (regione Germania, eu-central-1), con oltre 95 tabelle. Sono organizzati per dominio:

Dominio	Tabelle chiave	A cosa servono
Inquilini (tenancy)	`workspaces`, `team_members`	L'azienda e le persone che la usano (titolare/collaboratori)
Pianeti — dati	`bookings`, `crm_contacts`, `deals`/`sales_pipelines`, `sites`	I dati operativi reali
Contenuti	`content_plans`, `content_assets`, `content_brand_memory`/`signals`	Contenuti e voce del marchio
Memoria	`entity_memory`, `entity_profile`, `entity_patterns`, `entity_interactions`	La memoria viva del Sole
Conoscenza	`knowledge_packs`, `sectors`, `sector_default_services`	Benchmark di settore e semi (dati condivisi, non per-cliente)
Fatturazione	`subscriptions`, `webhook_events`	Abbonamenti Stripe
Strato agentico	`agent_runs`, `agent_decisions`, `workspace_insights`, `workspace_planet_autonomy`, `workspace_token_usage`	Esecuzioni, decisioni, osservazioni, autonomia, quota token

L'isolamento tra clienti (multi-tenant). Quasi ogni tabella ha una colonna workspace_id e una regola di sicurezza riga-per-riga (RLS) che fa sì che ogni azienda veda solo i propri dati. Perché è critico: una falla che facesse vedere i dati di un cliente a un altro sarebbe una fuga di dati = responsabilità penale del founder (revFADP, fino a CHF 250.000) e notifica obbligatoria entro 72 ore (GDPR). Le tabelle condivise (settori, benchmark, tetti di piano) non hanno workspace_id perché sono uguali per tutti.

Prezzi e funzioni sbloccate per piano

I piani sbloccano pianeti, quote di token (il "carburante" dell'AI) e tetti (es. numero di siti generabili). I "tetti di piano" (tier_caps) sono dati nel database, modificabili senza toccare il codice.

Piano	Pianeti inclusi	Siti generabili	Tetto spesa generazione sito
Starter (CHF 590 + 79/mese)	Web, Booking, CRM (base)	1	5 CHF
Pro ⭐ (CHF 890 + 149/mese)	+ Content, Sales, CRM completo	3	10 CHF
Business (CHF 1.290 + 249/mese)	+ Marketing, Finanza, sub-account illimitati	10	15 CHF

Più la prova di 10 giorni con tutte le funzioni Pro senza carta, e la garanzia 30 giorni. Il dettaglio e le regole di sconto sono in canon/03-pricing.md.

✅ Risolto (2026-06-04, PR #185): la fatturazione nel codice ora mostra CHF 79/149/249, allineata al canon. src/lib/plans.ts prende il prezzo da MULTIVERBE_PRICING (fonte unica) e il default valuta è CHF. Era un drift EUR 29/49/99 più un bug di chiave tier (un cliente Pro veniva trattato come Starter), entrambi chiusi.

Dove lavora: feature, risparmi e crescita per settore

Per ciascuno dei 7 settori curati prima del lancio, ecco i pianeti più utili, il problema principale che risolviamo, il risparmio stimato per il cliente e il ritorno sull'investimento. I calcoli completi sono in canon/11-sectors-deep.md.

Settore	Pianeti chiave	Problema risolto	Risparmio stimato per il cliente	Ritorno	Piano
🍽️ Ristorazione	Booking, Web, Content, CRM	Mancate presentazioni 8-15%, recensioni non gestite	Circa CHF 4.900 al mese (meno no-show, tavoli più veloci, food cost)	circa 32×	Pro
🏨 Hotel e B&B	Booking, Web, CRM	Commissioni dei portali 15-25%, prezzi fissi	Circa CHF 7.000-12.000 al mese (prezzi dinamici, prenotazioni dirette, pacchetti)	50-80×	Pro
💇 Parrucchieri ed estetica	Booking, Content, CRM	Posti liberi all'ultimo minuto, commissioni Treatwell	Circa CHF 2.800-3.300 al mese (riempimento slot, fedeltà, zero commissioni)	18-22×	Pro
💪 Palestre e fitness	CRM, Booking, Content	Abbandono abbonati 35-50% all'anno	Circa CHF 3.000 al mese (meno abbandoni, più conversioni, vendite extra)	circa 20×	Pro
🦷 Studi medici e dentistici	Booking, CRM, Web	Mancate presentazioni 10-15%, dati non a norma	Circa CHF 4.000 al mese (promemoria, richiami, riduzione del rischio sui dati)	circa 16×	Business
🏘️ Agenzie immobiliari	Sales, Web, CRM, Content	Potenziali clienti non coltivati, contratti su carta	Circa una transazione in più al mese (circa CHF 18.000)	circa 72×	Business
📊 Studi professionali	CRM, Finanza, Web	Tempo fatturabile perso 15-25%, documenti dispersi	Circa CHF 16.000-25.000 al mese (tempo tracciato, fatturazione, nuovi clienti)	100-170×	Pro

I 14 settori restanti sono comunque coperti dall'avvio guidato generico (vedi canon/04-icp-personas.md); saranno curati nel dettaglio dopo i primi clienti paganti.

Il potenziale di crescita

Per il cliente: la centralità come leva

Più pianeti il cliente attiva, più Multiverbe diventa utile e più diventa difficile (e poco conveniente) andarsene. Il percorso tipico è: parte con un dolore acuto risolto bene (per esempio le prenotazioni), poi scopre il resto e sale di piano (da Starter a Pro a Business) durante le revisioni di valore a 30, 60 e 90 giorni. Ogni passaggio aggiunge pianeti e quindi valore.

Per Multiverbe: mercato e geografia

Mercato dei 7 settori principali in Ticino: circa CHF 12,8 milioni di fatturato ricorrente annuo potenziale. Conquistando il 5% si arriva a circa CHF 640.000 all'anno, il 10% a circa CHF 1,28 milioni (fonte: canon/11-sectors-deep.md).
Margine sano: il margine lordo ricorrente è almeno del 93% già da 25 clienti e si stabilizza intorno al 95% (fonte: canon/06-economics.md).
Espansione geografica: si parte dal Ticino, poi Svizzera tedesca e romanda, poi Italia del Nord, poi resto d'Europa, adattando il prodotto alle pratiche locali (fonte: canon/10-admin-ch.md e roadmap geografica).
Nuovi pianeti in arrivo: Risorse Umane (terzo e quarto trimestre 2026), poi Magazzino ed E-commerce (2027), che allargano ancora il valore per cliente.

flowchart LR
  S["Starter<br/>590 + 79/mese"] --> P["Pro<br/>890 + 149/mese"]
  P --> B["Business<br/>1.290 + 249/mese"]
  S -.->|"più pianeti, più valore"| B

Il metodo: il grafo della conoscenza del codice

Per tenere tutto sotto controllo "innanzitutto per Claude e poi per il team", il codice del prodotto è stato trasformato in un grafo della conoscenza (con lo strumento Graphify): una mappa di relazioni tra file e funzioni che permette di navigare il codice senza rileggerlo ogni volta, e di vedere a colpo d'occhio i punti critici.

Stato al 2026-06-04 (costruito davvero, il tentativo fermo del 26 maggio è risolto):

3.811 nodi e 7.942 archi sul cuore dell'app (api + src), in 181 gruppi (community). Estrazione strutturale deterministica, costo zero token.
Un solo "anello" banale (auto-riferimento), zero dipendenze circolari tra file diversi: segno di un'architettura a strati pulita.
I "nodi-dio" (i più collegati, da maneggiare con cura perché toccarli ha effetti ovunque): useWorkspace (162 archi, l'ossatura multi-cliente), il client supabase (83), useLocale (le 4 lingue), setCorsHeaders e rateLimitResponseHeaders (sicurezza API), lo store del cruscotto, l'enum dei pianeti. Sono esattamente le cose che ci si aspetta siano portanti, non grovigli accidentali.
Sempre aggiornato: un "hook" si attiva a ogni commit nel repo del codice e ricostruisce il grafo da solo. E le sessioni Claude future, nel repo del codice, interrogano il grafo prima di rispondere.
Risparmio misurato: 17,4× meno token per domanda rispetto a rileggere il codice (fino a 145× sui casi migliori).

In pratica: questo rende lo sviluppo più veloce e di qualità più alta, e permette di scovare colli di bottiglia tecnici (accoppiamenti pesanti, file "tuttofare") prima che diventino problemi. Manca solo dare un nome leggibile ai 181 gruppi (richiede una chiave AI dedicata): è un miglioramento minore segnato tra i "da fare a breve".

Discrepanze note da sistemare

Emerse dalla ricognizione del codice. Lo stato e la priorità di ognuna vivono nel /cantiere; qui restano elencate per completezza della mappa.

✅ Prezzi EUR vs CHF (RISOLTO 2026-06-04, PR #185): la fatturazione ora mostra CHF 79/149/249 (src/lib/plans.ts prende il prezzo da MULTIVERBE_PRICING, default valuta CHF). Chiuso anche un bug collegato: la chiave tier professional non combaciava con il pro salvato da Stripe, così un cliente Pro vedeva limiti e nome del piano Starter.
✅ KPI di testata reali nei pannelli (RISOLTO 2026-06-04, PR #175): i numeri grandi in cima ai pannelli pianeta (Booking, CRM, Sales, Web) ora sono reali via /api/planets/metrics; Content, Marketing e l'hub AI mostrano un trattino onesto finché non hanno dati. Tolte le sparkline finte.
Costituzioni di design solo per il ristorante (1 su 22 settori): qualità del sito diseguale fuori dall'ospitalità.
Marketing e diversi satelliti Web (Email Hub, Blog, Recensioni, Mappa di calore, Lead Magnet) sono scatole vuote: coerente con la roadmap, da non promettere come "live".
Screenshot del sito simulato (capturePageScreenshot è un segnaposto): lo stadio finale di revisione qualità del sito valuta un'immagine finta finché non si implementa la cattura reale.
La chat sole-ask usa un prompt italiano locale invece dell'identità condivisa multilingue: allinearla per piena parità nelle 4 lingue.
Smistamento modelli 60/30/10 ancora aspirazionale (quasi tutto su Sonnet 4.6): ottimizzazione di costo da fare a volumi maggiori.
Scena 3D a 6 pianeti mentre i pianeti canonici sono 7 (manca Finanza nella grafica).

Ultimo aggiornamento: 2026-06-04 · enciclopedia completa (richiesta del founder "la mappa del prodotto deve essere MOLTO più esplicativa e COMPLETA"). Sintesi di una ricognizione reale del codice su tre fronti (schermate+pianeti, cervello, settori+dati) più il grafo della conoscenza. Da aggiornare a ogni decisione che cambia prodotto, prezzi o settori, mantenendo allineate le fonti citate e il /cantiere. Responsabile: Gregorio (architettura prodotto) · sintesi mantenuta da Claude.