docs(01-01): complete infrastructure skeleton plan

Tasks completed: 2/2 - Task 1: Backend FastAPI skeleton + Docker build config - Task 2: React + Vite + Tailwind v4 SPA scaffold con API client SUMMARY: .planning/phases/01-core-generation-pipeline/01-01-SUMMARY.md
2026-03-08 01:57:09 +01:00
parent 62f4b487b0
commit f6d9215b52
2 changed files with 180 additions and 16 deletions
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@@ -10,28 +10,28 @@ See: .planning/PROJECT.md (updated 2026-03-07)
 ## Current Position

 Phase: 1 of 4 (Core Generation Pipeline)
-Plan: 0 of 4 in current phase
-Status: Ready to plan
-Last activity: 2026-03-07 — Roadmap e STATE.md inizializzati dopo requirements e research
+Plan: 1 of 4 in current phase
+Status: In progress — Plan 01 completato, pronto per Plan 02
+Last activity: 2026-03-08 — Completato 01-01-PLAN.md (infrastructure skeleton)

-Progress: [░░░░░░░░░░] 0%
+Progress: [█░░░░░░░░░] 6% (1/16 piani totali stimati)

 ## Performance Metrics

 **Velocity:**
- Total plans completed: 0
- Average duration: — min
- Total execution time: 0 hours
+- Total plans completed: 1
+- Average duration: 6 min
+- Total execution time: 6 min

 **By Phase:**

 | Phase | Plans | Total | Avg/Plan |
 |-------|-------|-------|----------|
-| - | - | - | - |
+| 01-core-generation-pipeline | 1/4 | 6 min | 6 min |

 **Recent Trend:**
- Last 5 plans: —
- Trend: —
+- Last 5 plans: 6 min
+- Trend: baseline stabilita

 *Updated after each plan completion*

@@ -47,19 +47,24 @@ Recent decisions affecting current work:
 - [Setup]: CSV encoding = utf-8-sig (BOM) sempre; CANVA_FIELDS locked come costante prima di qualsiasi codice di generazione
 - [Setup]: Prompt di sistema scritti IN italiano (non inglese + "scrivi in italiano")
 - [Setup]: Per-item error isolation dal primo loop di generazione — un fallimento non blocca il batch
+- [01-01]: root_path SOLO via Uvicorn --root-path nel Dockerfile CMD, VERIFICATO e funzionante
+- [01-01]: API_BASE='/postgenerator/api' nel frontend — Pitfall #9 risolto nella configurazione base
+- [01-01]: SPAStaticFiles montato come ultima operazione in main.py — pattern stabilito
+- [01-01]: fastapi[standard]==0.135.1, anthropic==0.84.0 pinned in requirements.txt
+- [01-01]: docker-compose NO porte esposte, named volume postgenerator-data per persistenza

 ### Pending Todos

-None yet.
+None.

 ### Blockers/Concerns

- [Phase 1]: Canva field schema (placeholder names) non ancora definiti — devono essere locked come CANVA_FIELDS prima di scrivere codice generazione o LLM output schema
- [Phase 1]: Validare token usage reale per batch 13 post con claude-sonnet-4-5 contro limite Tier 1 (8,000 OTPM) — necessario inter-request delay configurabile (2-3s)
- [Phase 1]: Baseline qualita' prompt italiani da validare dopo prima generazione reale
+- [Phase 1]: Canva field schema (placeholder names) non ancora definiti — devono essere locked come CANVA_FIELDS prima di scrivere codice generazione o LLM output schema (da affrontare in 01-02)
+- [Phase 1]: Validare token usage reale per batch 13 post con claude-sonnet-4-5 contro limite Tier 1 (8,000 OTPM) — necessario inter-request delay configurabile (2-3s) (da affrontare in 01-03)
+- [Phase 1]: Baseline qualita' prompt italiani da validare dopo prima generazione reale (post 01-03)

 ## Session Continuity

-Last session: 2026-03-07
-Stopped at: Roadmap creato, STATE.md inizializzato — pronto per /gsd:plan-phase 1
+Last session: 2026-03-08T00:55:40Z
+Stopped at: Completato 01-01-PLAN.md — Infrastructure skeleton (FastAPI + React/Vite/Docker)
 Resume file: None
--- a/.planning/phases/01-core-generation-pipeline/01-01-SUMMARY.md
+++ b/.planning/phases/01-core-generation-pipeline/01-01-SUMMARY.md
@@ -0,0 +1,159 @@
+---
+phase: 01-core-generation-pipeline
+plan: 01
+subsystem: infra
+tags: [fastapi, react, vite, tailwindcss, docker, uvicorn, react-router, tanstack-query]
+
+# Dependency graph
+requires: []
+provides:
+  - FastAPI app skeleton con SPAStaticFiles catch-all e health endpoint
+  - config.py con DATA_PATH, PROMPTS_PATH, OUTPUTS_PATH, CAMPAIGNS_PATH, CONFIG_PATH
+  - React SPA scaffold con Vite, Tailwind v4, react-router, TanStack Query
+  - API client con base URL /postgenerator/api (Pitfall #9 risolto)
+  - Dockerfile multi-stage (node:22-slim -> python:3.12-slim)
+  - docker-compose.yml con proxy_net, named volume, NO porte esposte
+  - root_path impostato SOLO via Uvicorn --root-path (Pitfall #4 risolto)
+affects:
+  - 01-02 (routers e servizi usano backend/main.py e config.py)
+  - 01-03 (generation pipeline usa config.py paths)
+  - 01-04 (frontend usa api/client.ts come unico punto di accesso API)
+  - tutti i piani futuri che aggiungono routes al backend
+
+# Tech tracking
+tech-stack:
+  added:
+    - fastapi[standard]==0.135.1
+    - anthropic==0.84.0
+    - httpx==0.28.1
+    - python-dotenv==1.2.2
+    - aiofiles==24.1.0
+    - react 19 (via Vite react-ts template)
+    - vite 7.3.1
+    - tailwindcss v4 + @tailwindcss/vite
+    - react-router-dom
+    - @tanstack/react-query
+    - lucide-react
+  patterns:
+    - SPAStaticFiles: StaticFiles subclass con 404->index.html fallback per SPA routing
+    - root_path via Uvicorn --root-path, mai nel costruttore FastAPI()
+    - API_BASE='/postgenerator/api' come costante nel frontend
+    - basename="/postgenerator" in BrowserRouter
+    - Vite proxy dev: /postgenerator/api -> localhost:8000 (strip /postgenerator)
+    - Lifespan context manager per startup directory creation
+    - Mount SPA SEMPRE dopo tutti i router API
+
+key-files:
+  created:
+    - backend/__init__.py
+    - backend/main.py
+    - backend/config.py
+    - backend/routers/__init__.py
+    - requirements.txt
+    - .env.example
+    - Dockerfile
+    - docker-compose.yml
+    - frontend/vite.config.ts (modificato da template)
+    - frontend/src/App.tsx (modificato da template)
+    - frontend/src/index.css (modificato da template)
+    - frontend/src/api/client.ts
+  modified:
+    - .gitignore (aggiunto frontend/dist/, backend/data/outputs/)
+
+key-decisions:
+  - "root_path SOLO via Uvicorn --root-path nel Dockerfile CMD, mai nel costruttore FastAPI() — evita Pitfall #4 double-path"
+  - "API_BASE='/postgenerator/api' nel frontend client — evita Pitfall #9 subpath API URL"
+  - "SPAStaticFiles montato COME ULTIMA OPERAZIONE dopo tutti i router API"
+  - "fastapi[standard]==0.135.1 (latest), anthropic==0.84.0 (latest) — versioni pinned"
+  - "docker-compose: NO porte esposte, solo proxy_net external — traffic via lab-router nginx"
+  - "Named volume postgenerator-data per persistenza dati cross-container"
+
+patterns-established:
+  - "SPAStaticFiles pattern: override get_response con try/except per 404->index.html fallback"
+  - "Lifespan pattern: asynccontextmanager per startup side effects (directory creation)"
+  - "Subpath pattern: base vite + basename router + API_BASE client tutti allineati su /postgenerator/"
+
+# Metrics
+duration: 6min
+completed: 2026-03-08
+---
+
+# Phase 1 Plan 01: Infrastructure Skeleton Summary
+
+**FastAPI + React/Vite/Tailwind v4 skeleton deployabile su subpath /postgenerator/, con tutti i pitfall infrastrutturali (#4, #9) risolti nella configurazione base**
+
+## Performance
+
+- **Duration:** 6 min
+- **Started:** 2026-03-08T00:49:36Z
+- **Completed:** 2026-03-08T00:55:40Z
+- **Tasks:** 2/2
+- **Files modified:** 19
+
+## Accomplishments
+
+- Backend FastAPI skeleton con SPAStaticFiles catch-all, health endpoint GET /api/health, e lifespan per directory creation
+- config.py con tutte le path constants lette da env (DATA_PATH, PROMPTS_PATH, OUTPUTS_PATH, CAMPAIGNS_PATH, CONFIG_PATH)
+- React SPA scaffold completo: Vite + Tailwind v4 + react-router + TanStack Query + lucide-react, build pulita a 253.90kB
+- Docker multi-stage build: node:22-slim per build React, python:3.12-slim per runtime, --root-path /postgenerator solo in CMD
+- docker-compose.yml con container lab-postgenerator-app, proxy_net external, named volume, NO porte esposte
+
+## Task Commits
+
+Ogni task committato atomicamente:
+
+1. **Task 1: Backend FastAPI skeleton + Docker build config** - `50d5708` (feat)
+2. **Task 2: React + Vite + Tailwind v4 SPA scaffold con API client** - `62f4b48` (feat)
+
+**Plan metadata:** (da aggiungere dopo commit docs)
+
+## Files Created/Modified
+
+- `backend/main.py` - FastAPI app con SPAStaticFiles, health endpoint, lifespan
+- `backend/config.py` - Path constants da env: DATA_PATH, PROMPTS_PATH, OUTPUTS_PATH, CAMPAIGNS_PATH, CONFIG_PATH
+- `backend/__init__.py` - Package marker (vuoto)
+- `backend/routers/__init__.py` - Package marker (vuoto)
+- `requirements.txt` - fastapi[standard]==0.135.1, anthropic==0.84.0, httpx==0.28.1, python-dotenv==1.2.2, aiofiles==24.1.0
+- `.env.example` - Template variabili ambiente (ANTHROPIC_API_KEY, LLM_MODEL, DATA_PATH)
+- `Dockerfile` - Multi-stage: frontend-builder (node:22-slim) + runtime (python:3.12-slim), --root-path in CMD
+- `docker-compose.yml` - lab-postgenerator-app, proxy_net, postgenerator-data volume
+- `frontend/vite.config.ts` - base='/postgenerator/', tailwindcss plugin, dev proxy
+- `frontend/src/api/client.ts` - API_BASE='/postgenerator/api', apiFetch<T> con error handling
+- `frontend/src/App.tsx` - QueryClientProvider + BrowserRouter basename="/postgenerator" + HomePage
+- `frontend/src/index.css` - @import "tailwindcss" (Tailwind v4 syntax)
+- `.gitignore` - Aggiunto frontend/dist/, backend/data/outputs/
+
+## Decisions Made
+
+- root_path impostato SOLO via Uvicorn `--root-path /postgenerator` nel Dockerfile CMD — mai nel costruttore `FastAPI()`. Evita Pitfall #4 (double-path).
+- API_BASE = '/postgenerator/api' nel frontend client.ts — path assoluto che funziona dietro nginx lab-router. Evita Pitfall #9.
+- SPAStaticFiles montato come ULTIMA operazione in main.py — garantisce che tutti i router API abbiano precedenza.
+- fastapi[standard]==0.135.1 (latest al momento), anthropic==0.84.0 (latest) — pinned per riproducibilita' build.
+- docker-compose senza porte esposte pubblicamente — tutto il traffico transita via proxy_net e lab-router nginx.
+
+## Deviations from Plan
+
+Nessuna. Piano eseguito esattamente come scritto.
+
+Il piano specificava `python-dotenv==1.2.2` (versione nel plan) e la versione disponibile confermata. Idem per `aiofiles==24.1.0`.
+
+## Issues Encountered
+
+Nessuno.
+
+## User Setup Required
+
+None — nessun servizio esterno richiede configurazione manuale per questo piano.
+Per l'esecuzione reale: copiare `.env.example` in `.env` e aggiungere `ANTHROPIC_API_KEY`.
+
+## Next Phase Readiness
+
+- Backend skeleton pronto per ricevere router (plan 01-02: FormatSelector, Schemas)
+- Frontend pronto per ricevere pagine e componenti
+- Docker build verificato — build produce output corretto
+- API client testabile: `apiFetch<{status:string}>('/health')` deve restituire `{status:'ok'}`
+- Blockers aperti da STATE.md: CANVA_FIELDS schema da definire (plan 01-02), token usage da validare (plan 01-03)
+
+---
+*Phase: 01-core-generation-pipeline*
+*Completed: 2026-03-08*