postgenerator/.planning/PROJECT.md

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