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)
# 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
# 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:
- Apri http://localhost:3000
- Clicca "Nuovo Scenario"
- Inserisci nome, descrizione, seleziona regione AWS
- Clicca "Crea e Avvia"
Via API:
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
# 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:
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:
- Vai al tab "Report" dello scenario
- Seleziona formato (PDF o CSV)
- Clicca "Genera Report"
- Scarica il file
Via API:
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:
- Dalla lista scenari, seleziona 2+ scenari con i checkbox
- Clicca "Confronta Selezionati"
- 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)
- Spec-Driven: Definisci input/output prima di implementare
- Test First: Scrivi test che falliscono (Red)
- Implementa: Codice minimo per far passare test (Green)
- 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
# 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)
- API ingestion base
- 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:
- Fork il repository
- Crea un branch feature (
git checkout -b feature/amazing-feature) - Commit le modifiche (
git commit -m 'feat: add amazing feature') - Push al branch (
git push origin feature/amazing-feature) - 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