postgenerator/.planning/ROADMAP.md

Roadmap: PostGenerator

Overview

PostGenerator trasforma framework strategici di content marketing (Persuasion Nurturing + livelli Schwartz) in caroselli Instagram pronti per Canva Bulk Create. Il percorso di sviluppo segue una logica precisa: prima costruire la pipeline di generazione end-to-end funzionante (Fase 1), poi dare il controllo sulla qualita' dell'output tramite editor di prompt e anteprima (Fase 2), poi aggiungere gli strumenti organizzativi per un workflow sostenibile (Fase 3), infine arricchire con integrazioni opzionali (Fase 4). Ogni fase consegna un sistema verificabile e utilizzabile indipendentemente dalla successiva.

Phases

Phase Numbering:

• Integer phases (1, 2, 3): Planned milestone work
• Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)

Decimal phases appear between their surrounding integers in numeric order.

• Phase 1: Core Generation Pipeline - Infrastruttura + pipeline calendario → LLM → CSV funzionante end-to-end
• Phase 2: Prompt Control + Output Review - Editor prompt via UI e anteprima caroselli prima dell'export
• Phase 3: Organization Layer - Swipe File e gestione storico campagne per workflow sostenibile
• Phase 4: Enrichment - Integrazione Unsplash, context injection da Swipe File, polish UI

Phase Details

Phase 1: Core Generation Pipeline

Goal: L'utente puo' generare un calendario di 13 caroselli completi e scaricare un CSV valido per Canva Bulk Create con un click dalla Web UI deployata su VPS. Depends on: Nothing (first phase) Requirements: INF-01, INF-02, INF-03, INF-04, INF-05, INF-06, CAL-01, CAL-02, CAL-03, CAL-04, CAL-05, CAL-06, CAL-07, FMT-01, FMT-02, LLM-01, LLM-02, LLM-03, LLM-04, LLM-05, LLM-06, PRM-01, PRM-02, PRM-03, PRM-04, CSV-01, CSV-02, CSV-03, CSV-04, IMG-01, IMG-04, UI-01, UI-02, UI-03, UI-04, UI-07, UI-08 Success Criteria (what must be TRUE):

1. L'utente accede a https://lab.mlhub.it/postgenerator/ e la Web UI si carica senza errori
2. L'utente inserisce obiettivo campagna e settimane desiderate, clicca "Genera Calendario" e vede un progress indicator per ogni post in generazione
3. Al termine della generazione, l'utente puo' scaricare un file CSV che si apre correttamente in Excel con caratteri italiani intatti e header che corrispondono esattamente ai placeholder del template Canva
4. Il CSV contiene esattamente 13 righe di contenuto con la distribuzione Persuasion Nurturing corretta (4 valore, 2 storytelling, 2 news, 3 riprova, 1 coinvolgimento, 1 promo) e i livelli Schwartz assegnati
5. Se la generazione di un singolo post fallisce (errore API), gli altri post del batch sono salvati e scaricabili; il post fallito e' marcato come errore senza bloccare il resto Plans: TBD

Plans:

• 01-01: Infrastructure setup — FastAPI + React SPA single container, Docker multi-stage build, subpath /postgenerator/ configurato correttamente (root_path via Uvicorn, Vite base, nginx lab-router)
• 01-02: Core services — CalendarService (distribuzione 13 post, Schwartz, nicchie, date), FormatSelector (mapping tipo x Schwartz → formato), PromptService base (carica .txt, compile variabili), file-based storage layout
• 01-03: LLM pipeline — LLMService (Claude API, retry, backoff, rate limit, JSON validation), CSVBuilder (header Canva locked, utf-8-sig encoding), per-item error isolation
• 01-04: Web UI base — Dashboard, form Genera Calendario, form Genera Singolo Post, Output Review (anteprima slide-by-slide), Impostazioni, progress indicator bulk

---

Phase 2: Prompt Control + Output Review

Goal: L'utente puo' modificare i prompt direttamente dalla Web UI senza toccare il codice, rigenerare singoli post insoddisfacenti, e rivedere l'anteprima completa di ogni carosello prima di esportare il CSV. Depends on: Phase 1 Requirements: PRM-05, UI-05 Success Criteria (what must be TRUE):

1. L'utente apre la sezione Prompt Editor, vede la lista dei file .txt disponibili, clicca su un prompt e ne modifica il contenuto direttamente nel browser
2. Dopo aver salvato un prompt modificato, l'utente genera un nuovo post e il contenuto prodotto riflette le modifiche apportate al prompt
3. L'utente puo' rigenerare un singolo post dell'anteprima senza rigenerare l'intero batch Plans: TBD

Plans:

• 02-01: PromptService CRUD completo — endpoint FastAPI per lista/leggi/scrivi file prompt, validazione variabili richieste, UI Prompt Editor (lista, textarea, salva)
• 02-02: Per-item regeneration — endpoint rigenera singolo post per ID slot, aggiornamento anteprima senza rigenerare il batch, integrazione con Output Review UI

---

Phase 3: Organization Layer

Goal: L'utente puo' salvare rapidamente idee e topic interessanti in un Swipe File consultabile, e ritrovare e ri-scaricare calendari generati in sessioni precedenti. Depends on: Phase 1 Requirements: SWP-01, SWP-02, SWP-03, SWP-04, UI-06 Success Criteria (what must be TRUE):

1. L'utente aggiunge un'idea al Swipe File con topic, nicchia e note; l'idea appare immediatamente nella lista e persiste al riavvio del container
2. L'utente puo' eliminare una voce dal Swipe File e la lista si aggiorna
3. L'utente puo' selezionare un topic dallo Swipe File come override per uno slot specifico prima di avviare la generazione del calendario Plans: TBD

Plans:

• 03-01: SwipeService — CRUD JSON collections (swipe_file.json), endpoint FastAPI lista/aggiungi/elimina, UI Swipe File Manager (aggiungi, lista, elimina)
• 03-02: Swipe-to-calendar integration — meccanismo per selezionare topic da Swipe File come override slot nel form Genera Calendario (CAL-07 + SWP-04)

---

Phase 4: Enrichment

Goal: L'utente con API key Unsplash configurata vede URL immagini reali nel CSV invece di placeholder; l'utente puo' passare voci dello Swipe File come contesto durante la generazione topic per risultati piu' aderenti alle proprie osservazioni. Depends on: Phase 3 Requirements: IMG-02, IMG-03 Success Criteria (what must be TRUE):

1. Se l'API key Unsplash e' configurata nelle Impostazioni, il CSV esportato contiene URL immagini reali (non placeholder) per ogni slide
2. Se Unsplash non e' configurato o supera il rate limit, il CSV usa URL placeholder senza errori e senza bloccare l'export
3. La cache locale evita chiamate duplicate a Unsplash per keyword identiche nella stessa sessione Plans: TBD

Plans:

• 04-01: Unsplash integration — UnsplashService via httpx async, cache JSON locale, fallback trasparente a placeholder, integrazione nel pipeline CSV quando API key presente

---

Progress

Execution Order: Phases execute in numeric order: 1 → 2 → 3 → 4

Phase	Plans Complete	Status	Completed
1. Core Generation Pipeline	0/4	Not started	-
2. Prompt Control + Output Review	0/2	Not started	-
3. Organization Layer	0/2	Not started	-
4. Enrichment	0/1	Not started	-