d222d21618
- Update README.md with v0.4.0 features and screenshots placeholders - Update architecture.md with v0.4.0 implementation status - Update progress.md marking all 27 tasks as completed - Create CHANGELOG.md with complete release notes - Add v0.4.0 frontend components and hooks
470 lines
17 KiB
Markdown
470 lines
17 KiB
Markdown
# mockupAWS - Backend Profiler & Cost Estimator
|
|
|
|
> **Versione:** 0.4.0 (Completata)
|
|
> **Stato:** Release Candidate
|
|
|
|
## Panoramica
|
|
|
|
`mockupAWS` è una piattaforma di simulazione locale (homelab) progettata per **profilare il traffico e calcolare i driver di costo** dei servizi AWS (SQS, Lambda, Bedrock/LLM) prima del deploy in produzione.
|
|
|
|
A differenza dei semplici calcolatori di costo online, mockupAWS permette di:
|
|
- **Creare scenari di simulazione** isolati e tracciabili
|
|
- **Inviare log reali** tramite HTTP API (compatibile Logstash)
|
|
- **Storicizzare** tutte le metriche in database PostgreSQL
|
|
- **Calcolare costi** usando prezzi AWS reali aggiornabili
|
|
- **Generare report** PDF/CSV professionali
|
|
- **Confrontare scenari** per decisioni data-driven
|
|
- **Rilevare PII** nei log prima dell'invio al cloud
|
|
|
|
## Caratteristiche Principali
|
|
|
|
### 🎯 Gestione Scenari
|
|
- Crea scenari di simulazione con nome, descrizione e tag
|
|
- Isola completamente i dati tra scenari diversi
|
|
- Stati dello scenario: `draft` → `running` → `completed` → `archived`
|
|
- Confronta scenari side-by-side con indicatori di delta costi
|
|
|
|
### 💰 Calcolo Costi AWS Reale
|
|
- Tabella prezzi AWS configurabile per regione
|
|
- Calcolo accurato basato su:
|
|
- **SQS**: $0.40 per milione richieste (blocchi 64KB)
|
|
- **Lambda**: $0.20 per milione richieste + $0.0000166667 per GB-second
|
|
- **Bedrock**: Prezzi per token input/output (variano per modello)
|
|
- Supporto multi-regione (us-east-1, eu-west-1, ecc.)
|
|
|
|
### 📊 Interfaccia Web
|
|
- Dashboard responsive con grafici in tempo reale
|
|
- Form guidato per creazione scenari
|
|
- Vista dettaglio con metriche, costi, logs e PII detection
|
|
|
|
### 📈 Data Visualization & Reports (v0.4.0)
|
|
- **Report Generation**: PDF/CSV professionali con template personalizzabili
|
|
- **Data Visualization**: Grafici interattivi con Recharts (Pie, Area, Bar)
|
|
- **Scenario Comparison**: Confronto side-by-side di 2-4 scenari con delta costi
|
|
- **Dark/Light Mode**: Toggle tema con rilevamento preferenza sistema
|
|
|
|
### 🔒 Sicurezza
|
|
- Rilevamento automatico email (PII) nei log
|
|
- Hashing dei messaggi per privacy
|
|
- Deduplicazione automatica per simulazione batching ottimizzato
|
|
- Autenticazione JWT/API Keys (in sviluppo)
|
|
|
|
## Architettura
|
|
|
|
```
|
|
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
|
|
│ Logstash │ │ React Web UI │ │ API Clients │
|
|
│ (o Client) │ │ (Dashboard) │ │ (CI/CD) │
|
|
└────────┬────────┘ └────────┬─────────┘ └────────┬────────┘
|
|
│ │ │
|
|
│ HTTP POST │ HTTPS │ API Key
|
|
│ /ingest │ /api/v1/* │ /api/v1/*
|
|
▼ ▼ ▼
|
|
┌────────────────────────────────────────────────────────────────────┐
|
|
│ API LAYER (FastAPI + Uvicorn) │
|
|
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌───────────┐ │
|
|
│ │ /scenarios │ │ /ingest │ │ /reports │ │ /pricing │ │
|
|
│ │ /metrics │ │ (scenario) │ │ generate │ │ (admin) │ │
|
|
│ └─────────────┘ └─────────────┘ └─────────────┘ └───────────┘ │
|
|
└────────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌────────────────────────────────────────────────────────────────────┐
|
|
│ DATABASE LAYER (PostgreSQL 15+) │
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
│ │ scenarios │ │scenario_logs │ │ aws_pricing │ │
|
|
│ │ scenario_ │ │ reports │ │ │ │
|
|
│ │ metrics │ │ │ │ │ │
|
|
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
|
└────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Screenshots
|
|
|
|
> **Nota:** Gli screenshot saranno aggiunti nella release finale.
|
|
|
|
### Dashboard
|
|
|
|
*Dashboard principale con lista scenari e metriche overview*
|
|
|
|
### Scenario Detail con Grafici
|
|
|
|
*Vista dettaglio scenario con cost breakdown chart e time series*
|
|
|
|
### Scenario Comparison
|
|
|
|
*Confronto side-by-side di multipli scenari con indicatori delta*
|
|
|
|
### Dark Mode
|
|
|
|
*Tema scuro applicato a tutta l'interfaccia*
|
|
|
|
### Report Generation
|
|
|
|
*Generazione e download report PDF/CSV*
|
|
|
|
## Stack Tecnologico
|
|
|
|
### Backend
|
|
- **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 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 - 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
|
|
|
|
- Docker & Docker Compose
|
|
- Python 3.11+ (se sviluppo locale)
|
|
- Node.js 20+ (se sviluppo frontend)
|
|
- ~2GB RAM disponibili
|
|
|
|
## 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
|
|
# Clona il repository
|
|
git clone <repository-url>
|
|
cd mockupAWS
|
|
|
|
# Avvia tutti i servizi (API + Database + Frontend)
|
|
docker-compose up --build
|
|
|
|
# L'applicazione sarà disponibile su:
|
|
# - 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
|
|
# Usa Docker solo per PostgreSQL
|
|
docker-compose up -d postgres
|
|
# oppure configura PostgreSQL localmente
|
|
```
|
|
|
|
**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
|
|
|
|
### 1. Creare uno Scenario
|
|
|
|
Via Web UI:
|
|
1. Apri http://localhost:3000
|
|
2. Clicca "Nuovo Scenario"
|
|
3. Inserisci nome, descrizione, seleziona regione AWS
|
|
4. Clicca "Crea e Avvia"
|
|
|
|
Via API:
|
|
```bash
|
|
curl -X POST http://localhost:8000/api/v1/scenarios \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"name": "Produzione Q2",
|
|
"description": "Simulazione traffico produzione",
|
|
"region": "us-east-1",
|
|
"tags": ["production"]
|
|
}'
|
|
# Response: { "id": "uuid-scenario-123", ... }
|
|
```
|
|
|
|
### 2. Inviare Log allo Scenario
|
|
|
|
```bash
|
|
# Usa lo scenario ID ricevuto
|
|
curl -X POST http://localhost:8000/ingest \
|
|
-H "Content-Type: application/json" \
|
|
-H "X-Scenario-ID: uuid-scenario-123" \
|
|
-d '{"message": "Error: connection timeout", "source": "api"}'
|
|
```
|
|
|
|
Oppure configura Logstash:
|
|
```ruby
|
|
output {
|
|
http {
|
|
url => "http://localhost:8000/ingest"
|
|
headers => ["X-Scenario-ID", "uuid-scenario-123"]
|
|
content_type => "application/json"
|
|
format => "json"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 3. Monitorare in Tempo Reale
|
|
|
|
- Apri la Web UI http://localhost:3000
|
|
- Seleziona il tuo scenario
|
|
- Osserva metriche in tempo reale:
|
|
- Richieste totali
|
|
- Costo stimato cumulativo
|
|
- Blocchi SQS fatturabili
|
|
- Token LLM contati
|
|
- Violazioni PII rilevate
|
|
|
|
### 4. Generare Report
|
|
|
|
Via Web UI:
|
|
1. Vai al tab "Report" dello scenario
|
|
2. Seleziona formato (PDF o CSV)
|
|
3. Clicca "Genera Report"
|
|
4. Scarica il file
|
|
|
|
Via API:
|
|
```bash
|
|
curl -X POST http://localhost:8000/api/v1/scenarios/uuid-scenario-123/reports \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"format": "pdf", "include_logs": false}'
|
|
```
|
|
|
|
### 5. Confrontare Scenari
|
|
|
|
Nella Web UI:
|
|
1. Dalla lista scenari, seleziona 2+ scenari con i checkbox
|
|
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
|
|
│ └── report_service.py # PDF/CSV generation (v0.4.0)
|
|
├── frontend/ # Frontend React
|
|
│ ├── src/
|
|
│ │ ├── App.tsx # Root component
|
|
│ │ ├── components/
|
|
│ │ │ ├── layout/ # Header, Sidebar, Layout
|
|
│ │ │ ├── ui/ # shadcn components
|
|
│ │ │ ├── charts/ # Recharts components (v0.4.0)
|
|
│ │ │ ├── comparison/ # Comparison components (v0.4.0)
|
|
│ │ │ └── reports/ # Report generation UI (v0.4.0)
|
|
│ │ ├── hooks/ # React Query hooks
|
|
│ │ ├── lib/
|
|
│ │ │ ├── api.ts # Axios client
|
|
│ │ │ ├── utils.ts # Utility functions
|
|
│ │ │ └── theme-provider.tsx # Dark mode (v0.4.0)
|
|
│ │ ├── pages/ # Page components
|
|
│ │ │ ├── Dashboard.tsx
|
|
│ │ │ ├── ScenarioDetail.tsx
|
|
│ │ │ ├── ScenarioEdit.tsx
|
|
│ │ │ ├── Compare.tsx # Scenario comparison (v0.4.0)
|
|
│ │ │ └── Reports.tsx # Reports page (v0.4.0)
|
|
│ │ └── types/
|
|
│ │ └── api.ts # TypeScript types
|
|
│ ├── e2e/ # E2E tests (v0.4.0)
|
|
│ ├── package.json
|
|
│ ├── playwright.config.ts # Playwright config (v0.4.0)
|
|
│ └── 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
|
|
Validazione rigorosa dei payload e rilevamento PII prima di qualsiasi elaborazione.
|
|
|
|
### 🔄 Little Often
|
|
Processamento a piccoli batch per simulare l'ottimizzazione Lambda e minimizzare costi.
|
|
|
|
### ✓ Double Check
|
|
Ogni calcolo (token count, billing blocks, costi) è verificato. Target: >95% accuratezza vs AWS reale.
|
|
|
|
## Sviluppo
|
|
|
|
### Flusso di Lavoro (TDD)
|
|
|
|
1. **Spec-Driven**: Definisci input/output prima di implementare
|
|
2. **Test First**: Scrivi test che falliscono (Red)
|
|
3. **Implementa**: Codice minimo per far passare test (Green)
|
|
4. **Refactor**: Migliora codice mantenendo test passanti
|
|
|
|
### Convenzioni Git
|
|
|
|
- **Conventional Commits**: `feat:`, `fix:`, `test:`, `docs:`, `chore:`
|
|
- Commit atomici
|
|
- Esempio: `feat: add scenario cost calculation with AWS pricing`
|
|
|
|
### Comandi Utili
|
|
|
|
```bash
|
|
# Test
|
|
uv run pytest # Tutti i test
|
|
uv run pytest -v # Verbose
|
|
uv run pytest --cov=src # Con coverage
|
|
|
|
# Database
|
|
uv run alembic revision --autogenerate -m "description"
|
|
uv run alembic upgrade head
|
|
uv run alembic downgrade -1
|
|
|
|
# Formattazione
|
|
uv run ruff check src/
|
|
uv run ruff format src/
|
|
|
|
# Frontend
|
|
cd frontend
|
|
npm run lint
|
|
npm run build
|
|
```
|
|
|
|
## Roadmap
|
|
|
|
### v0.2.0 ✅ Completata
|
|
- [x] API ingestion base
|
|
- [x] Calcolo metriche (SQS, Lambda, Bedrock)
|
|
- [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 ✅ 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 ✅ Completata (2026-04-07)
|
|
- [x] Generazione report PDF/CSV con ReportLab
|
|
- [x] Confronto scenari (2-4 scenari side-by-side)
|
|
- [x] Grafici interattivi con Recharts (Pie, Area, Bar)
|
|
- [x] Dark/Light mode toggle con rilevamento sistema
|
|
- [x] E2E Testing suite con 100 test cases (Playwright)
|
|
|
|
### v0.5.0 🔄 Pianificata
|
|
- [ ] Autenticazione JWT e autorizzazione
|
|
- [ ] API Keys management
|
|
- [ ] User preferences (tema, notifiche)
|
|
- [ ] Export dati avanzato (JSON, Excel)
|
|
|
|
### v1.0.0 ⏳ Future
|
|
- [ ] Backup automatico database
|
|
- [ ] Documentazione API completa (OpenAPI)
|
|
- [ ] Performance optimizations
|
|
- [ ] Production deployment guide
|
|
- [ ] Testing E2E
|
|
|
|
## Contributi
|
|
|
|
Contributi sono benvenuti! Per favore:
|
|
1. Fork il repository
|
|
2. Crea un branch feature (`git checkout -b feature/amazing-feature`)
|
|
3. Commit le modifiche (`git commit -m 'feat: add amazing feature'`)
|
|
4. Push al branch (`git push origin feature/amazing-feature`)
|
|
5. Apri una Pull Request
|
|
|
|
## Licenza
|
|
|
|
Distribuito sotto licenza MIT. Vedi `LICENSE` per dettagli.
|
|
|
|
---
|
|
|
|
**MockupAWS** - Parte del progetto LogWhispererAI
|
|
*Stima i costi AWS prima di spenderli davvero*
|