commit 5335b3b0ae987823ad8d48fdbfe82f474294527a Author: Michele Date: Sat Mar 7 13:44:43 2026 +0100 docs: initialize project Instagram carousel automation system for B2B content marketing - strategic content engine with Persuasion Nurturing, Schwartz levels, and niche rotation producing Canva Bulk Create CSV Co-Authored-By: Claude Opus 4.6 diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md new file mode 100644 index 0000000..778ac4a --- /dev/null +++ b/.planning/PROJECT.md @@ -0,0 +1,131 @@ +# PostGenerator + +## What This Is + +Sistema di automazione per la generazione di caroselli Instagram in bulk per una pagina B2B che promuove consulenza AI a PMI italiane. Non un semplice generatore di testi: un motore di content marketing strategico che orchestra campagne coordinate secondo framework di persuasion nurturing, livelli di consapevolezza Schwartz e rotazione nicchie verticali. L'output principale e' un CSV compatibile con Canva Bulk Create. + +## Core Value + +Generare un calendario editoriale completo (13 post = 2 settimane) di caroselli Instagram strategicamente orchestrati, pronti per l'importazione in Canva Bulk Create, con un click dalla Web UI. + +## Requirements + +### Validated + +(None yet — ship to validate) + +### Active + +- [ ] Calendar Generator che produce cicli di 13 post con distribuzione Persuasion Nurturing +- [ ] Integrazione Claude API per generazione contenuti carosello in formato JSON strutturato +- [ ] Sistema di prompt editabili (file-based) per ogni combinazione formato+tipo contenuto +- [ ] CSV Builder con header compatibile Canva Bulk Create (8 slide per carosello) +- [ ] Format Selector automatico (tipo_contenuto x livello_schwartz -> formato_narrativo) +- [ ] Campaign Planner con sequenza 4 fasi (attira/cattura/coinvolgi/converti) +- [ ] Rotazione nicchie B2B (generico 50%, verticali 50% in rotazione) +- [ ] Topic generation ibrida: auto-generati dall'LLM + override manuale +- [ ] Swipe File per cattura rapida idee/topic +- [ ] Web UI completa: genera calendario, genera singolo post, prompt editor, swipe file, impostazioni +- [ ] Image keyword generation per ogni slide (fetch Unsplash opzionale se API key configurata) +- [ ] Deploy Docker su VPS Hostinger (lab.mlhub.it/postgenerator/) + +### Out of Scope + +- Database relazionale — file system sufficiente per MVP (prompts/, outputs/, data/) +- Pubblicazione diretta su Instagram — il sistema produce CSV, Canva genera i grafici +- Scheduling/pianificazione automatica — le date sono suggerite, la pubblicazione e' manuale +- Analytics/tracking performance — fase successiva dopo validazione del content engine +- Multi-utente/autenticazione — uso personale di Michele +- Template Canva generation — i template si creano manualmente su Canva + +## Context + +### Framework Strategici Integrati + +Il sistema combina tre framework. Ogni post generato porta il tag di tutti e tre i layer: + +**1. Persuasion Nurturing (mix per ciclo di 13 post):** +- 4 post valore (educare, L4/L3) +- 2 post storytelling (intrattenere, L5/L4) +- 2 post news settore (intrattenere/educare, L5/L4) +- 3 post riprova sociale (persuadere, L3/L2) +- 1 post coinvolgimento (intrattenere, tutti) +- 1 post promozione (convertire, L1/L2) + +**2. 5 Livelli di Consapevolezza (Schwartz):** +- L5 (inconsapevole): storytelling emotivo, domande provocatorie +- L4 (consapevole problema): nominare il problema, agitarlo +- L3 (consapevole soluzioni): educare sui criteri, posizionarsi +- L2 (consapevole prodotto): casi studio, testimonianze, FAQ +- L1 (pronto acquisto): offerta chiara, urgenza, social proof + +**3. 4 Funzioni del Contenuto:** +- Intrattenere -> Educare -> Persuadere -> Convertire + +**4 Step di Campagna:** +- Attira -> Cattura -> Coinvolgi -> Converti + +### 7 Formati Narrativi +PAS, AIDA, BAB, Listicle, Storytelling/Eroe, Dato+Implicazione, Obiezione+Risposta + +### Struttura Carosello (8 slide) +1. COVER (hook + subtitle) +2. PROBLEMA (agitazione) +3. CONTESTO (dati/scenario) +4. SVILUPPO A (primo punto) +5. SVILUPPO B (approfondimento) +6. SVILUPPO C (esempio pratico) +7. SINTESI (recap/trasformazione) +8. CTA (call to action) + +### Regole di Copywriting +- Comunicare sempre: chi sei, perche' fidarsi, perche' sei unico, come puoi aiutarlo +- "Cosa fare" mai "come farlo" — il come e' cio' per cui pagano +- Tono: diretto, provocatorio, costruttivo +- Lingua: italiano +- Target: imprenditori e manager italiani + +### Nicchie B2B Target +- Generico PMI/imprenditori (~50%) +- Dentisti/Studi medici +- Avvocati/Studi legali +- E-commerce +- Local business +- Agenzie (mktg/consulenza) + +### Header CSV Canva Bulk Create +``` +campagna,fase_campagna,tipo_contenuto,formato_narrativo,funzione,livello_schwartz, +target_nicchia,data_pub_suggerita,cover_title,cover_subtitle,cover_image_url, +s2_headline,s2_body,s2_image_url,s3_headline,s3_body,s3_image_url, +s4_headline,s4_body,s4_image_url,s5_headline,s5_body,s5_image_url, +s6_headline,s6_body,s6_image_url,s7_headline,s7_body,s7_image_url, +cta_text,cta_subtext,cta_button_label +``` + +I campi metadato (prima di cover_title) restano nel CSV per analisi ma Canva li ignora. + +## Constraints + +- **Stack**: Python 3.12 + FastAPI backend, React + Tailwind frontend — adattato a VPS echosystem +- **LLM**: Claude API (anthropic SDK) — provider principale +- **Storage**: File system locale (no DB) — prompts/, outputs/, data/, swipe_file.json +- **Deploy**: Docker su VPS Hostinger, URL https://lab.mlhub.it/postgenerator/ +- **Immagini**: keyword generate dal sistema, Unsplash fetch opzionale (API key non ancora disponibile) +- **Template Canva**: placeholder con nomi identici alle colonne CSV (da cover_title in poi) +- **Lingua**: tutti i contenuti generati in italiano +- **Interfaccia**: Web UI come interfaccia principale (non CLI) + +## Key Decisions + +| Decision | Rationale | Outcome | +|----------|-----------|---------| +| Claude API come LLM provider | Familiarita' con ecosistema Anthropic, qualita' output italiano | — Pending | +| FastAPI + React (non Flask + HTML/JS) | Migliore separazione, UI piu' ricca, coerenza con echosystem VPS | — Pending | +| File system storage (no DB) | Semplicita' MVP, prompt e config come file editabili | — Pending | +| Nomi placeholder dal briefing | Template Canva creato dopo, basato sui nomi CSV definiti | — Pending | +| Topic generation ibrida | Auto-generati di default, override manuale per trend/intuizioni | — Pending | +| Unsplash opzionale | Genera keyword sempre, fetch immagini solo se API key configurata | — Pending | + +--- +*Last updated: 2026-03-07 after initialization*