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. 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. Costruito con FastAPI + React, deployato su VPS Hostinger come container Docker.

## 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

- v1 Calendar & Campaign (CAL-01..07) — v1
- v1 Format Selection (FMT-01..02) — v1
- v1 LLM Content Generation (LLM-01..06) — v1
- v1 Prompt System (PRM-01..05) — v1
- v1 CSV & Export (CSV-01..04) — v1
- v1 Image Keywords (IMG-01..04) — v1
- v1 Swipe File (SWP-01..04) — v1
- v1 Web UI (UI-01..08) — v1
- v1 Infrastructure (INF-01..06) — v1

Full details: `.planning/milestones/v1-REQUIREMENTS.md`

### Active

(None — define next milestone requirements with `/gsd:new-milestone`)

### 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
- Video/Reel generation — solo caroselli per MVP

## Context

### Current State

Shipped v1 MVP con 8,080 LOC (4,157 Python + 3,923 TypeScript) in 48 file sorgente.
Tech stack: FastAPI 0.115 + React 19 + Tailwind v4 + TanStack Query + Vite.
Deploy target: Docker single container su VPS Hostinger (lab.mlhub.it/postgenerator/).
Storage: file system (prompts/, outputs/, data/, swipe_file.json) — no database.

**Pending validation:**
- Deploy su VPS e test end-to-end con API key reali (Claude + Unsplash)
- Qualita' prompt italiani con dati reali
- CSV import in Canva Bulk Create con caratteri italiani

### 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) → L4 (consapevole problema) → L3 (consapevole soluzioni) → L2 (consapevole prodotto) → L1 (pronto acquisto)

**3. 7 Formati Narrativi:**
PAS, AIDA, BAB, Listicle, Storytelling/Eroe, Dato+Implicazione, Obiezione+Risposta

**4. Struttura Carosello (8 slide):**
COVER → PROBLEMA → CONTESTO → SVILUPPO A → SVILUPPO B → SVILUPPO C → SINTESI → CTA

### Nicchie B2B Target
Generico PMI (~50%), Dentisti/Studi medici, Avvocati/Studi legali, E-commerce, Local business, Agenzie

## Constraints

- **Stack**: Python 3.12 + FastAPI backend, React + Tailwind frontend
- **LLM**: Claude API (anthropic SDK)
- **Storage**: File system locale (no DB)
- **Deploy**: Docker su VPS Hostinger, URL https://lab.mlhub.it/postgenerator/
- **Immagini**: keyword + Unsplash opzionale
- **Template Canva**: placeholder con nomi identici alle colonne CSV
- **Lingua**: tutti i contenuti generati in italiano
- **Interfaccia**: Web UI come interfaccia principale

## Key Decisions

| Decision | Rationale | Outcome |
|----------|-----------|---------|
| Claude API come LLM provider | Familiarita' ecosistema Anthropic, qualita' output italiano | v1 Good |
| FastAPI + React (non Flask + HTML/JS) | Migliore separazione, UI ricca, coerenza VPS echosystem | v1 Good |
| File system storage (no DB) | Semplicita' MVP, prompt e config come file editabili | v1 Good |
| Nomi placeholder dal briefing | Template Canva creato dopo, basato sui nomi CSV definiti | v1 Good |
| Topic generation ibrida | Auto-generati + override manuale per trend/intuizioni | v1 Good |
| Unsplash opzionale | Keyword sempre, fetch solo se API key configurata | v1 Good |
| root_path SOLO via Uvicorn --root-path | Mai nel costruttore FastAPI — pitfall subpath risolto | v1 Good |
| CSV utf-8-sig + CANVA_FIELDS locked | Compatibilita' Excel, header bloccati con assert | v1 Good |
| Pipeline singleton con fallback disco | Mantiene _jobs tra request, ricostruisce da JSON | v1 Good |
| Design stone/amber B2B | Non gradienti viola generici, palette professionale | v1 Good |
| Risoluzione Unsplash una volta dopo batch | Batch efficiente, no re-risoluzione su regen singolo | v1 Good |
| Dizionario statico IT→EN (~30 keyword) | No API traduzione esterna, keyword B2B sufficienti | v1 Good |
| Lazy init services (PromptService, SwipeService) | Sincronizzazione con lifespan FastAPI directory creation | v1 Good |
| localResults separato in OutputReview | Edit inline senza mutare cache TanStack Query | v1 Good |
| topic_overrides come dict[int, str] | Chiave = slot_index, Pydantic converte str key → int | v1 Good |

## Tech Debt (from v1)

- Pipeline singleton non invalidato su API key change (media)
- Campo campagna inviato ma ignorato in export (bassa)
- brand_name hardcoded in generation_pipeline.py (bassa)
- Job interrotti durante restart non recuperabili (bassa)

---
*Last updated: 2026-03-09 after v1 milestone*