docs: update documentation and add Docker configuration for v0.3.0

- Update README.md with v0.3.0 completion status and improved setup instructions - Update export/progress.md with completed tasks (53/55, 96% progress) - Update export/architecture.md with current project structure and implementation status - Add docker-compose.yml with PostgreSQL service - Add Dockerfile.backend for production builds - Add frontend/Dockerfile for multi-stage builds - Update .gitignore with comprehensive rules for Python, Node.js, and Docker Project status: - v0.2.0: Database and Backend API ✅ - v0.3.0: Frontend React implementation ✅ - v0.4.0: Reports and visualization (planned)
2026-04-07 15:17:15 +02:00
parent 500e14c4a8
commit 311a576f40
7 changed files with 758 additions and 282 deletions
--- a/README.md
+++ b/README.md
@@ -1,7 +1,7 @@
 # mockupAWS - Backend Profiler & Cost Estimator

-> **Versione:** 0.2.0 (In Sviluppo)  
-> **Stato:** Database & Scenari Implementation
+> **Versione:** 0.3.0 (Completata)  
+> **Stato:** Database, Backend & Frontend Implementation Complete

 ## Panoramica

@@ -78,24 +78,31 @@ A differenza dei semplici calcolatori di costo online, mockupAWS permette di:
 ## Stack Tecnologico

 ### Backend
- **FastAPI** (≥0.110) - Framework web async
- **PostgreSQL** (≥15) - Database relazionale
- **SQLAlchemy** (≥2.0) - ORM con supporto async
- **Alembic** - Migrazioni database
- **tiktoken** - Tokenizer per calcolo costi LLM
- **Pydantic** (≥2.7) - Validazione dati
+- **FastAPI** (≥0.110) - Framework web async ad alte prestazioni
+- **PostgreSQL** (≥15) - Database relazionale con supporto JSON
+- **SQLAlchemy** (≥2.0) - ORM moderno con supporto async/await
+- **Alembic** - Migrazioni database versionate
+- **Pydantic** (≥2.7) - Validazione dati e serializzazione
+- **tiktoken** - Tokenizer ufficiale OpenAI per calcolo costi LLM
+- **python-jose** - JWT handling (preparato per v1.0.0)

 ### Frontend
- **React** (≥18) - UI framework
- **Vite** - Build tool
- **Tailwind CSS** (≥3.4) - Styling
- **shadcn/ui** - Componenti UI
- **Recharts** - Grafici e visualizzazioni
+- **React** (≥18) - UI library con hooks e functional components
+- **Vite** (≥5.0) - Build tool ultra-veloce con HMR
+- **TypeScript** (≥5.0) - Type safety e developer experience
+- **Tailwind CSS** (≥3.4) - Utility-first CSS framework
+- **shadcn/ui** - Componenti UI accessibili e personalizzabili
+- **TanStack Query** (React Query) - Data fetching e caching
+- **Axios** - HTTP client con interceptors
+- **React Router** - Client-side routing
+- **Lucide React** - Icone moderne e consistenti

 ### DevOps
- **Docker** + Docker Compose
- **Nginx** - Reverse proxy
- **uv** - Package manager Python
+- **Docker** & Docker Compose - Containerizzazione
+- **Nginx** - Reverse proxy (pronto per produzione)
+- **uv** - Package manager Python veloce e moderno
+- **Ruff** - Linter e formatter Python
+- **ESLint** & **Prettier** - Code quality frontend

 ## Requisiti

@@ -106,6 +113,13 @@ A differenza dei semplici calcolatori di costo online, mockupAWS permette di:

 ## Installazione e Avvio

+### Prerequisiti
+
+- Docker & Docker Compose
+- Python 3.11+ (per sviluppo locale)
+- Node.js 20+ (per sviluppo frontend)
+- PostgreSQL 15+ (se non usi Docker)
+
 ### Metodo 1: Docker Compose (Consigliato)

 ```bash
@@ -117,23 +131,60 @@ cd mockupAWS
 docker-compose up --build

 # L'applicazione sarà disponibile su:
-# - Web UI: http://localhost:3000
+# - Web UI: http://localhost:5173  (Vite dev server)
 # - API: http://localhost:8000
 # - API Docs: http://localhost:8000/docs
+# - Database: localhost:5432
 ```

 ### Metodo 2: Sviluppo Locale

+**Step 1: Database**
 ```bash
-# Backend
-uv sync
-uv run alembic upgrade head  # Migrazioni database
-uv run uvicorn src.main:app --reload
+# Usa Docker solo per PostgreSQL
+docker-compose up -d postgres
+# oppure configura PostgreSQL localmente
+```

-# Frontend (in un altro terminale)
+**Step 2: Backend**
+```bash
+# Installa dipendenze Python
+uv sync
+
+# Esegui migrazioni database
+uv run alembic upgrade head
+
+# Avvia server API
+uv run uvicorn src.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+**Step 3: Frontend (in un altro terminale)**
+```bash
 cd frontend
+
+# Installa dipendenze
 npm install
+
+# Avvia server sviluppo
 npm run dev
+
+# L'app sarà disponibile su http://localhost:5173
+```
+
+### Configurazione Ambiente
+
+Crea un file `.env` nella root del progetto:
+
+```env
+# Database
+DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/mockupaws
+
+# API
+API_V1_STR=/api/v1
+PROJECT_NAME=mockupAWS
+
+# Frontend (se necessario)
+VITE_API_URL=http://localhost:8000
 ```

 ## Utilizzo
@@ -214,6 +265,64 @@ Nella Web UI:
 2. Clicca "Confronta Selezionati"
 3. Visualizza comparazione costi e metriche

+## Struttura del Progetto
+
+```
+mockupAWS/
+├── src/                          # Backend FastAPI
+│   ├── main.py                   # Entry point applicazione
+│   ├── api/
+│   │   ├── deps.py              # Dependencies (DB session, auth)
+│   │   └── v1/                  # API v1 endpoints
+│   │       ├── scenarios.py     # CRUD scenari
+│   │       ├── ingest.py        # Ingestione log
+│   │       └── metrics.py       # Metriche e costi
+│   ├── core/
+│   │   ├── config.py            # Configurazione app
+│   │   ├── database.py          # SQLAlchemy setup
+│   │   └── exceptions.py        # Gestione errori
+│   ├── models/                  # SQLAlchemy models
+│   │   ├── scenario.py
+│   │   ├── scenario_log.py
+│   │   ├── scenario_metric.py
+│   │   ├── aws_pricing.py
+│   │   └── report.py
+│   ├── schemas/                 # Pydantic schemas
+│   ├── repositories/            # Repository pattern
+│   └── services/                # Business logic
+│       ├── pii_detector.py
+│       ├── cost_calculator.py
+│       └── ingest_service.py
+├── frontend/                     # Frontend React
+│   ├── src/
+│   │   ├── App.tsx              # Root component
+│   │   ├── components/
+│   │   │   ├── layout/          # Header, Sidebar, Layout
+│   │   │   └── ui/              # shadcn components
+│   │   ├── hooks/               # React Query hooks
+│   │   ├── lib/
+│   │   │   ├── api.ts           # Axios client
+│   │   │   └── utils.ts         # Utility functions
+│   │   ├── pages/               # Page components
+│   │   │   ├── Dashboard.tsx
+│   │   │   ├── ScenarioDetail.tsx
+│   │   │   └── ScenarioEdit.tsx
+│   │   └── types/
+│   │       └── api.ts           # TypeScript types
+│   ├── package.json
+│   └── vite.config.ts
+├── alembic/                      # Database migrations
+│   └── versions/                 # Migration files
+├── export/                       # Documentazione progetto
+│   ├── prd.md                   # Product Requirements
+│   ├── architecture.md          # Architettura sistema
+│   ├── kanban.md                # Task breakdown
+│   └── progress.md              # Progress tracking
+├── docker-compose.yml            # Docker orchestration
+├── pyproject.toml               # Python dependencies
+└── README.md                    # Questo file
+```
+
 ## Principi di Design

 ### 🔐 Safety First
@@ -265,28 +374,37 @@ npm run build

 ## Roadmap

-### v0.2.0 (In Corso)
+### v0.2.0 ✅ Completata
 - [x] API ingestion base
 - [x] Calcolo metriche (SQS, Lambda, Bedrock)
- [ ] Database PostgreSQL
- [ ] Tabelle scenari e persistenza
- [ ] Tabella prezzi AWS
+- [x] Database PostgreSQL con SQLAlchemy 2.0 async
+- [x] Tabelle scenari e persistenza
+- [x] Tabella prezzi AWS (seed dati per us-east-1, eu-west-1)
+- [x] Migrazioni Alembic (6 migrations)
+- [x] Repository pattern + Services layer
+- [x] PII detection e cost calculation

-### v0.3.0
- [ ] Frontend React con dashboard
- [ ] Form creazione scenario
- [ ] Visualizzazione metriche in tempo reale
+### v0.3.0 ✅ Completata
+- [x] Frontend React 18 con Vite
+- [x] Dashboard responsive con Tailwind CSS
+- [x] Form creazione/modifica scenari
+- [x] Lista scenari con paginazione
+- [x] Pagina dettaglio scenario
+- [x] Integrazione API con Axios + React Query
+- [x] Componenti UI shadcn/ui

-### v0.4.0
+### v0.4.0 (Prossima Release)
 - [ ] Generazione report PDF/CSV
 - [ ] Confronto scenari
- [ ] Grafici interattivi
+- [ ] Grafici interattivi con Recharts
+- [ ] Dark/Light mode toggle

 ### v1.0.0
- [ ] Autenticazione e autorizzazione
- [ ] API Keys
- [ ] Backup automatico
- [ ] Documentazione completa
+- [ ] Autenticazione JWT e autorizzazione
+- [ ] API Keys management
+- [ ] Backup automatico database
+- [ ] Documentazione API completa (OpenAPI)
+- [ ] Testing E2E

 ## Contributi