# πŸ“˜ STORICITΓ€, ARCHITETTURA & MANUALE DI PROGETTO > **BRANDSTUDIO OS β€” Piattaforma B2B White-Label per l'Autonomia di Contenuto & Brand Identity** > *Sorgente Unica di VeritΓ  (Single Source of Truth) e Protocollo di ContinuitΓ  Multi-Dispositivo (Mac & Windows PC).* --- ## 🧭 PROTOCOLLO DI CONTINUITΓ€ PER L'ASSISTENTE AI (ANTIGRAVITY) Questo documento costituisce la memoria storica assoluta e la guida tecnica del repository. Ogni sessione di lavoro (su Mac o PC Windows) deve rispettare tassativamente queste regole: 1. **Lettura Preliminare Obbligatoria**: All'avvio di ogni sessione o cambio di contesto, leggere questo file per allinearsi sullo stato del codice, sulle decisioni architetturali e sui requisiti del cliente. 2. **Standard No-Regressions**: Non reintrodurre librerie pesanti o framework complessi (React/Vue/Node build steps). Il progetto Γ¨ e deve rimanere 100% **Vanilla JavaScript ES6+, Modern CSS3 e HTML5** con rendering Canvas client-side. 3. **Aggiornamento Obbligatorio del Diario di Bordo**: Prima di concludere qualsiasi sessione, aggiornare la sezione finale (**"Registro delle Modifiche & Diario di Bordo"**) annotando data, postazione (Mac / Windows), modifiche eseguite e il prossimo step operativo. --- ## 🎯 1. VISIONE DEL PROGETTO & POSIZIONAMENTO B2B BrandStudio OS nasce per risolvere un problema cronico di PMI, studi medici, cliniche di medicina estetica, palestre, ristoranti e liberi professionisti: **la dipendenza continua dalle agenzie di comunicazione per la creazione quotidiana di contenuti grafici e video**. ### Modello di Business (White-Label Agency System): - **White-Label Dinamica**: L'agenzia installa BrandStudio OS per il cliente, configurando il Brand Kit (palette, font, loghi, valori e tono di voce). - **Autonomia Totale del Cliente**: Il cliente o il suo staff accedono alla propria istanza con un PIN a 4 cifre (`?client=nome_cliente`) e possono generare caroselli 4:5, copertine 9:16, locandine A4/A5, registrare video con teleprompter e programmare uscite editoriali in 1 clic. - **Zero Costi Infrastrutturali (Serverless Client-Side)**: Tutta la generazione grafica avviene via browser su HTML5 Canvas. Non ci sono server grafici a pagamento, database complessi o API terze obbligatorie a consumo. PuΓ² essere ospitato a costo 0€ su Vercel, Cloudflare Pages o Netlify. --- ## πŸ›οΈ 2. ARCHITETTURA DEI FILE & STRUTTURA DEL REPOSITORY ``` BrandStudio OS/ β”œβ”€β”€ STORICITA_E_MANUALE_PROGETTO.md # πŸ“Œ QUESTO FILE: Single Source of Truth & Handover β”œβ”€β”€ README.md # Documentazione e guida al deploy rapido β”œβ”€β”€ PROPOSTA_DI_VALORE_PITCH.md # Strategia commerciale e pitch per la vendita B2B β”œβ”€β”€ index.html # Command Center Master Hub & Dashboard di Selezione β”œβ”€β”€ manifest.json # Web App Manifest per installazione PWA su smartphone β”œβ”€β”€ client_schema_template.json # Modello JSON vuoto per configurare un nuovo brand β”‚ β”œβ”€β”€ assets/ β”‚ β”œβ”€β”€ css/ β”‚ β”‚ β”œβ”€β”€ core.css # Variabili CSS di Brand, temi Light/Dark, Navbar e bottoni β”‚ β”‚ β”œβ”€β”€ apps.css # Layout split-screen delle micro-app, viewport canvas β”‚ β”‚ └── print.css # Media query di stampa @media print per fogli A4 e A5 β”‚ β”œβ”€β”€ js/ β”‚ β”‚ β”œβ”€β”€ config.js # Configurazione dell'agenzia e Master PIN di sblocco (8899) β”‚ β”‚ β”œβ”€β”€ clients.js # Database multi-tenant con i brand kit precaricati β”‚ β”‚ β”œβ”€β”€ brand-core.js # Engine di iniezione dinamica del brand, logo e toast β”‚ β”‚ β”œβ”€β”€ canvas-utils.js # Motore grafico Canvas 2D (wrapping testo, archetipi, export) β”‚ β”‚ └── qr-generator.js # Generatore vettoriale di QR Code offline in puro JS β”‚ └── brand-logos/ # Loghi aziendali e risorse grafiche dei clienti β”‚ β”œβ”€β”€ apps/ β”‚ β”œβ”€β”€ caroselli/ # πŸ“² Studio Caroselli Instagram (4:5 HD, multi-slide) β”‚ β”œβ”€β”€ copertine-reel/ # πŸ“Έ Copertine Reel & TikTok (9:16 HD con safe area) β”‚ β”œβ”€β”€ teleprompter/ # πŸŽ™οΈ Teleprompter Studio & Webcam Live Recorder β”‚ β”œβ”€β”€ video-brander/ # 🎬 Video Brander, Trimmer e Lower-Third β”‚ β”œβ”€β”€ volantini-locandine/ # πŸ“„ Locandine A4 & Volantini A5 Print-Ready con QR Code β”‚ β”œβ”€β”€ piano-editoriale/ # πŸ“Š Calendario Strategico & Tabella di Marcia a 30 Giorni β”‚ β”œβ”€β”€ autopublisher/ # πŸš€ Social Auto-Publisher, Calendario Live & Hub Omnicanale β”‚ β”œβ”€β”€ automazioni/ # βš™οΈ Automazioni & Webhook Lead Generation (Make / Zapier) β”‚ β”œβ”€β”€ sponsorizzate-ads/ # 🎯 Studio Sponsorizzate Meta Ads (Copy & Formati Creativi) β”‚ β”œβ”€β”€ analytics/ # πŸ“ˆ Analytics, ROI Tracker & Monitoraggio Conversioni β”‚ └── onboarding-wizard/ # ✨ AI Onboarding & Brand Interview Wizard (5 Passi) β”‚ └── docs/business-suite/ # πŸ’Ό Kit Contrattuale, Legale, Fiscale e Commerciale β”œβ”€β”€ 01_RICERCA_MERCATO_E_COMPETITIVE_ADVANTAGE.md β”œβ”€β”€ 02_PIANO_PRICING_E_MODELLI_DI_VENDITA.md β”œβ”€β”€ 03_SCRIPT_DI_VENDITA_E_COLD_OUTREACH.md β”œβ”€β”€ 04_INQUADRAMENTO_FISCALE_E_COMMERCIALISTA.md β”œβ”€β”€ 05_CONTRATTO_LEGALE_E_COMPLIANCE_GDPR.md └── 06_ROADMAP_SCALABILITA_E_MIGRAZIONE_SAAS.md ``` --- ## 🎨 3. STANDARD TECNICI, DESIGN SYSTEM & DECISIONI CHIAVE ### A. Tipografia: Regola della Massima LeggibilitΓ  (Plus Jakarta Sans) - **Decisione**: Eliminati tutti i caratteri graziati (serif) pesanti o confusi (`Playfair Display`, `Bodoni Moda`, `Cormorant Garamond`, `Cinzel`) che appesantivano la lettura sia da desktop che da smartphone. - **Standard Ufficiale**: L'intero sistema (titoli della dashboard, testi delle micro-app, anteprime e Wizard di onboarding) Γ¨ uniformato su **`Plus Jakarta Sans`** (con fallbacks `-apple-system`, `Inter`, `Segoe UI`, `sans-serif`). - **Pesi e Resa**: - Titoli H1 / H2: `font-weight: 800` con `letter-spacing: -0.025em`. - Sottotitoli ed etichette: `font-weight: 600` o `500` ad alto contrasto. ### B. Motore Grafico HTML5 Canvas HD (`assets/js/canvas-utils.js`) - **Risoluzioni Native**: - Caroselli: `1080 x 1350 px` (Ratio 4:5 Instagram standard). - Copertine Reel/TikTok: `1080 x 1920 px` (Ratio 9:16 con Safe Area Instagram Feed 1:1 e Profilo 4:5). - Locandine e Volantini: `1240 x 1754 px` (A4 / A5 Print-Ready @ 300 DPI ottici). - **Regole di Calcolo Layout**: - `ctx.textBaseline = 'top'` obbligatorio per eliminare sovrapposizioni o disallineamenti cross-browser. - Funzione `wrapText()` avanzata con calcolo progressivo della coordinata `Y` e margini di sicurezza. - Archetipi di impaginazione integrati con 1 clic: 1. *Quarto Grado* (Split screen bicolore con taglio netto e headline in sticker box scuro). 2. *TGCOM24 Breaking* (Top ticker di urgenza, sticker bar colorata e sfumatura cinematografica profonda). 3. *Marketing Espresso* (Card centrale fluttuante in glassmorphism e micro-bordi hairline). 4. *Starting Finance* (Dark luxury minimal ad alto contrasto numerico). 5. *The Gap Media* (Warm editorial contemporaneo con micro-dettagli d'accento). ### C. Hub di Pubblicazione Omnicanale (`apps/autopublisher/`) - La finestra di configurazione ("πŸ”— Gestisci Connessione Diretta") Γ¨ strutturata a schede separate per: 1. **Meta (Instagram & Facebook)**: Token Graph API e Page ID per pubblicazione automatica diretta. 2. **TikTok Open API**: Access Token e Creator ID. 3. **LinkedIn API**: Organization ID e Token per caroselli documentali in PDF. 4. **Google Business Profile (Google Maps)**: Location ID e API Key per post orari, offerte e novitΓ  geolocalizzate. 5. **Telegram & WhatsApp Cloud**: Bot Token @BotFather, Chat ID e WhatsApp Phone ID. 6. **Webhook & Make.com / Zapier**: Endpoint universale JSON con payload completo (immagini in Base64 / URL HD, testi e timestamp). 7. **Esportazione Zero-Config**: Tasto per scaricare il CSV ufficiale compatibile con **Meta Business Suite** e file calendario `.ics` per smartphone. ### D. Anteprime Visive ad Ampia Scala (+30%) - Nelle app di creazione grafica (Locandine, Caroselli, Copertine Reel), le anteprime non devono mai essere thumbnail minuscole perse nel vuoto, ma box generosi (560px di larghezza minima per le locandine, 460px per i caroselli) con ombreggiatura scenica `box-shadow: 0 25px 60px rgba(0,0,0,0.5)`. --- ## πŸ“ 4. REGISTRO DELLE MODIFICHE & DIARIO DI BORDO (CHANGELOG) ### [2026-08-29 / 2026-08-31 β€” Sessione Mac] - **Pulizia Tipografica Globale**: - Rimosso ogni riferimento ai font serif obsoleti o poco chiari in `assets/css/core.css`, `index.html`, `apps/autopublisher/index.html` e `assets/js/clients.js`. - Convertiti tutti i client predefiniti (`centro_psyche`, `olympus`, `bistrot`, `legale`, `clinica_lumiere`) e il generatore Onboarding Wizard a **`Plus Jakarta Sans`**. - **Miglioramento Anteprima Volantini & Locandine**: - Incrementata la larghezza del box anteprima da 440px a **560px** in `apps/volantini-locandine/index.html`. - Aumentata la gerarchia dei testi canvas a 54px bold per i titoli, 26px per i sottotitoli, 30px per i box offerta e 22px per i vantaggi. - **Hub Omnicanale Auto-Publisher**: - Implementata l'interfaccia a 6 schede (Meta, TikTok, LinkedIn, Google Maps, Telegram/WA, Webhook Make). - Aggiunti test di connessione in tempo reale e persistenza localStorage per tutte le credenziali. - **Nuovi Archetipi Grafici Broadcaster**: - Aggiunti in `assets/js/canvas-utils.js` i layout *Quarto Grado*, *TGCOM24* e *Marketing Espresso* con sticker box e sfumatura cinematografica. - **Istituzione del Protocollo di ContinuitΓ **: - Creato questo file `STORICITA_E_MANUALE_PROGETTO.md` per l'allineamento automatico tra postazioni Mac e Windows PC. --- ## 🎯 5. PROSSIMO STEP OPERATIVO (PER LA SESSIONE SUCCESSIVA) 1. **Verifica Layout Cross-Device**: All'apertura del repository dalla postazione Windows, testare l'allineamento dei canvas e la leggibilitΓ  dei font su monitor ad alta densitΓ  di pixel (DPI Scaling al 125% / 150%). 2. **Esportazione Multi-Slide Caroselli ZIP**: Verificare l'implementazione del download zippato di tutte le 5 slide del carosello in 1 solo clic. 3. **Integrazione Webhook Test Live**: Testare l'invio di un post di prova tramite webhook reale verso Make.com / Zapier per convalidare il payload JSON end-to-end.