feat: initial project setup with scenarios, database and web ui

Add complete mockupAWS platform for AWS cost estimation: - FastAPI backend with scenario management - PostgreSQL database schema for scenarios, metrics, logs - AWS pricing table with real pricing data - React frontend dashboard (planned) - PII detection and token counting - Report generation (PDF/CSV) - Complete test suite with pytest - Docker Compose setup - Documentation: README, PRD, Architecture - OpenCode configuration (.opencode/)
2026-04-07 12:52:18 +02:00
parent b539134280
commit 59e5cf48f0
23 changed files with 2982 additions and 29 deletions
--- a/README.md
+++ b/README.md
@@ -1,41 +1,307 @@
 # mockupAWS - Backend Profiler & Cost Estimator

-## Obiettivo del Progetto
-`mockupAWS` è un ambiente di simulazione locale (homelab) progettato per replicare i layer di ingestion ed elaborazione cloud del progetto LogWhispererAI. 
+> **Versione:** 0.2.0 (In Sviluppo)  
+> **Stato:** Database & Scenari Implementation

-Lo scopo principale non è analizzare i log, ma **profilare il traffico e calcolare i driver di costo** dei servizi AWS (SQS, Lambda, Bedrock/LLM) prima del deploy in produzione. Inviando log tramite Logstash a questo mockup, è possibile ottenere una stima precisa della fatturazione basata su traffico simulato o reale.
+## Panoramica

-## Architettura e Metriche Misurate
-Il mockup espone endpoint che simulano il comportamento dei servizi AWS, raccogliendo metriche essenziali:
+`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.

-* **Simulazione Ingestion (Amazon SQS / API Gateway):**
-  * Misurazione delle richieste HTTP al secondo (RPS).
-  * Calcolo della dimensione media dei payload (monitorando i blocchi di fatturazione da 64KB).
-  * *Principio applicato: Safety First* - Validazione dell'integrità del payload in ingresso e verifica dell'avvenuta sanitizzazione dei dati (assenza di PII/Secreti).
+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

-* **Simulazione Compute (AWS Lambda):**
-  * Profilazione dell'efficacia del batching e della deduplicazione.
-  * *Principio applicato: Little Often* - Test del processamento a piccoli batch per simulare la lettura ottimizzata dalle code.
+## Caratteristiche Principali

-* **Simulazione LLM (Amazon Bedrock):**
-  * Conteggio esatto dei token in ingresso (Input Tokens) tramite tokenizer (es. `tiktoken`).
-  * *Principio applicato: Double Check* - Validazione finale del prompt generato prima del calcolo dei costi simulati.
+### 🎯 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
+- Dark/Light mode
+- Form guidato per creazione scenari
+- Vista dettaglio con metriche, costi, logs e PII detection
+- Export report PDF/CSV
+
+### 🔒 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     │ │              │ │              │               │
+│  └──────────────┘ └──────────────┘ └──────────────┘               │
+└────────────────────────────────────────────────────────────────────┘
+```
+
+## 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
+
+### Frontend
+- **React** (≥18) - UI framework
+- **Vite** - Build tool
+- **Tailwind CSS** (≥3.4) - Styling
+- **shadcn/ui** - Componenti UI
+- **Recharts** - Grafici e visualizzazioni
+
+### DevOps
+- **Docker** + Docker Compose
+- **Nginx** - Reverse proxy
+- **uv** - Package manager Python

 ## Requisiti
-* Docker / Docker Compose
-* Node.js (v20+) o Python (3.11+) [A seconda dello stack scelto per lo script]
-* Logstash (configurato per puntare agli endpoint esposti da questo mockup)

-## Flusso di Sviluppo (Spec-Driven & TDD)
-Questo repository adotta un approccio rigoroso allo sviluppo:
+- Docker & Docker Compose
+- Python 3.11+ (se sviluppo locale)
+- Node.js 20+ (se sviluppo frontend)
+- ~2GB RAM disponibili

-1. **Spec-Driven**: Nessuna implementazione senza prima aver definito le specifiche di input/output.
-2. **Test-Driven Development (TDD)**: I test per il calcolo delle metriche e la validazione dei payload (es. conteggio token, validazione limiti SQS) devono essere scritti *prima* della logica di routing.
-3. **Gestione del Codice**: 
-   * Flusso Git basato su **Conventional Commits** (`feat:`, `fix:`, `chore:`, `test:`).
-   * Commit atomici e mirati.
-   * Compilazione del file `CHANGELOG.md` aderente allo standard **Common Changelog**.
-4. **Pull Requests**: Le PR devono includere l'esito dei test e la descrizione chiara del driver di costo AWS che si sta andando a simulare o correggere.
+## Installazione e Avvio

-## Come avviare la simulazione
-*(Da completare una volta definito lo stack esatto e i comandi di avvio, es. `docker-compose up --build`)*
+### 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:3000
+# - API: http://localhost:8000
+# - API Docs: http://localhost:8000/docs
+```
+
+### Metodo 2: Sviluppo Locale
+
+```bash
+# Backend
+uv sync
+uv run alembic upgrade head  # Migrazioni database
+uv run uvicorn src.main:app --reload
+
+# Frontend (in un altro terminale)
+cd frontend
+npm install
+npm run dev
+```
+
+## 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
+
+## 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 (In Corso)
+- [x] API ingestion base
+- [x] Calcolo metriche (SQS, Lambda, Bedrock)
+- [ ] Database PostgreSQL
+- [ ] Tabelle scenari e persistenza
+- [ ] Tabella prezzi AWS
+
+### v0.3.0
+- [ ] Frontend React con dashboard
+- [ ] Form creazione scenario
+- [ ] Visualizzazione metriche in tempo reale
+
+### v0.4.0
+- [ ] Generazione report PDF/CSV
+- [ ] Confronto scenari
+- [ ] Grafici interattivi
+
+### v1.0.0
+- [ ] Autenticazione e autorizzazione
+- [ ] API Keys
+- [ ] Backup automatico
+- [ ] Documentazione completa
+
+## 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*