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*