From f6d9215b52326034fd95c47a5e4efabbfa035b69 Mon Sep 17 00:00:00 2001 From: Michele Date: Sun, 8 Mar 2026 01:57:09 +0100 Subject: [PATCH] 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 --- .planning/STATE.md | 37 ++-- .../01-01-SUMMARY.md | 159 ++++++++++++++++++ 2 files changed, 180 insertions(+), 16 deletions(-) create mode 100644 .planning/phases/01-core-generation-pipeline/01-01-SUMMARY.md diff --git a/.planning/STATE.md b/.planning/STATE.md index 357cd8e..4d456d2 100644 --- 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 diff --git a/.planning/phases/01-core-generation-pipeline/01-01-SUMMARY.md b/.planning/phases/01-core-generation-pipeline/01-01-SUMMARY.md new file mode 100644 index 0000000..72d51ad --- /dev/null +++ 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 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*