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