Michele/postgenerator
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(01-01): complete infrastructure skeleton plan

Browse Source 
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
This commit is contained in:
Michele
2026-03-08 01:57:09 +01:00
parent 62f4b487b0
commit f6d9215b52
2 changed files with 180 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
.planning/STATE.md
View File

@@ -10,28 +10,28 @@ See: .planning/PROJECT.md (updated 2026-03-07)
## Current Position ## Current Position
Phase: 1 of 4 (Core Generation Pipeline) Phase: 1 of 4 (Core Generation Pipeline)
Plan: 0 of 4 in current phase Plan: 1 of 4 in current phase
Status: Ready to plan Status: In progress — Plan 01 completato, pronto per Plan 02
Last activity: 2026-03-07 — Roadmap e STATE.md inizializzati dopo requirements e research Last activity: 2026-03-08 — Completato 01-01-PLAN.md (infrastructure skeleton)
Progress: [░░░░░░░░░░] 0% Progress: [█░░░░░░░░░] 6% (1/16 piani totali stimati)
## Performance Metrics ## Performance Metrics
**Velocity:** **Velocity:**
- Total plans completed: 0 - Total plans completed: 1
- Average duration: — min - Average duration: 6 min
- Total execution time: 0 hours - Total execution time: 6 min
**By Phase:** **By Phase:**
| Phase | Plans | Total | Avg/Plan | | Phase | Plans | Total | Avg/Plan |
|-------|-------|-------|----------| |-------|-------|-------|----------|
| - | - | - | - | | 01-core-generation-pipeline | 1/4 | 6 min | 6 min |
**Recent Trend:** **Recent Trend:**
- Last 5 plans: — - Last 5 plans: 6 min
- Trend: — - Trend: baseline stabilita
*Updated after each plan completion* *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]: 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]: 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 - [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 ### Pending Todos
None yet. None.
### Blockers/Concerns ### 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]: 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) - [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 - [Phase 1]: Baseline qualita' prompt italiani da validare dopo prima generazione reale (post 01-03)
## Session Continuity ## Session Continuity
Last session: 2026-03-07 Last session: 2026-03-08T00:55:40Z
Stopped at: Roadmap creato, STATE.md inizializzato — pronto per /gsd:plan-phase 1 Stopped at: Completato 01-01-PLAN.md — Infrastructure skeleton (FastAPI + React/Vite/Docker)
Resume file: None Resume file: None

159
.planning/phases/01-core-generation-pipeline/01-01-SUMMARY.md Normal file
View File

@@ -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*