mockupAWS/README.md

# mockupAWS - Backend Profiler & Cost Estimator

> **Versione:** 0.2.0 (In Sviluppo)  
> **Stato:** Database & Scenari Implementation

## 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
- 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
- Python 3.11+ (se sviluppo locale)
- Node.js 20+ (se sviluppo frontend)
- ~2GB RAM disponibili

## Installazione e Avvio

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