mockupAWS/export/prd.md

Product Requirements Document (PRD)

Prodotto: mockupAWS - Backend Profiler & Cost Estimator
Versione: 0.2.0
Data: 2026-04-07
Stato: In sviluppo

---

1. Overview

mockupAWS è un ambiente di simulazione locale (homelab) progettato per replicare i layer di ingestion ed elaborazione cloud del progetto LogWhispererAI. 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.

1.1 Problema

Gli utenti di LogWhispererAI non hanno visibilità sui costi AWS che genereranno in produzione basati sul loro volume di log. Inviare log reali ad AWS senza stima preventiva può generare costi imprevisti e elevati. Inoltre, manca uno strumento per:

• Confrontare scenari di costo diversi nel tempo
• Archiviare e consultare stime passate
• Generare report professionali da condividere con il team

1.2 Soluzione

Un simulatore locale con interfaccia web che:

• Riceve log tramite endpoint HTTP (compatibile Logstash)
• Permette di definire e salvare scenari di simulazione
• Calcola metriche di costo accurate usando prezzi AWS reali
• Storicizza tutti gli scenari in database
• Genera report dettagliati e condivisibili
• Identifica problemi di sicurezza (PII leaks)
• Fornisce una dashboard web per gestione e consultazione

---

2. Obiettivi

2.1 Business

• Ridurre il rischio di costi AWS imprevisti per gli utenti LogWhispererAI
• Fornire stime di costo accurate con margine di errore < 5%
• Accelerare il ciclo di sviluppo testando localmente prima del deploy
• Identificare ottimizzazioni di costo (batching, deduplicazione)
• Fornire report storici per analisi trend costi nel tempo
• Facilitare la comunicazione costi tra team DevOps e Management

2.2 Utente

• Creare e gestire scenari di simulazione con parametri personalizzabili
• Consultare lo storico di tutti gli scenari eseguiti
• Generare e scaricare report PDF/CSV dei costi stimati
• Ottenere una stima immediata dei costi AWS basata sul traffico reale
• Identificare log che contengono dati sensibili prima dell'invio al cloud
• Valutare l'impatto di ottimizzazioni (batch size, frequenza invio)
• Simulare scenari "what-if" con diversi volumi di traffico
• Confrontare scenari tra loro per decisioni data-driven

2.3 KPI (Key Performance Indicators)

Metrica	Target	Descrizione
Accuratezza stima costi	> 95%	Confronto tra stima mockupAWS e costi AWS reali
Latenza endpoint	< 100ms	Tempo di risposta per ingestion singolo log
Detection PII	> 90%	Rilevamento pattern email nei log
Throughput	> 1000 RPS	Richieste al secondo gestibili
Test Coverage	> 80%	Copertura test automatici
Tempo generazione report	< 5s	Generazione report completo scenario
Persistenza scenari	100%	Nessuna perdita dati scenari salvati

---

3. User Stories

US-001: Creazione Scenario

Come DevOps engineer,
voglio creare un nuovo scenario di simulazione specificando nome, descrizione e parametri,
per organizzare le mie stime di costo in sessioni distinte e tracciabili.

Acceptance Criteria:

• Posso creare uno scenario via UI web con nome, descrizione e tag
• Posso impostare parametri: regione AWS, tier servizi, durata simulazione
• Lo scenario viene salvato in database con timestamp creazione
• Ricevo uno scenario ID univoco per riferimento

US-002: Esecuzione Simulazione Scenario

Come DevOps engineer,
voglio inviare log a uno scenario specifico,
per accumulare metriche di costo isolate da altri scenari.

Acceptance Criteria:

• Posso specificare lo scenario ID nell'header o query parameter
• I log vengono associati allo scenario corretto
• Le metriche vengono aggregate per scenario
• Posso vedere metriche in tempo reale durante la simulazione

US-003: Storicizzazione Scenari

Come system architect,
voglio consultare tutti gli scenari passati con i loro dati,
per analizzare l'evoluzione dei costi nel tempo.

Acceptance Criteria:

• Lista scenari ordinata per data (più recenti prima)
• Filtri per data, tag, nome, stato
• Visualizzazione dettaglio singolo scenario
• Possibilità di archiviare/eliminare scenari vecchi

US-004: Tabella Costi AWS

Come cloud cost manager,
voglio che il sistema usi i prezzi AWS reali aggiornati,
per avere stime accurate e confrontabili con la fattura reale.

Acceptance Criteria:

• Tabella prezzi AWS SQS, Lambda, Bedrock configurabile
• Supporto multi-regione (us-east-1, eu-west-1, ecc.)
• Possibilità di aggiornare i prezzi manualmente
• Storico variazioni prezzi nel tempo

US-005: Generazione Report

Come team lead,
voglio generare report PDF/CSV dettagliati di uno scenario,
per condividerli con il management o il cliente.

Acceptance Criteria:

• Report include: riepilogo costi, dettaglio per servizio, grafici
• Formato PDF professionalmente formattato
• Formato CSV per analisi in Excel
• Possibilità di includere note e raccomandazioni

US-006: Interfaccia Web Dashboard

Come utente non-tecnico,
voglio una dashboard web intuitiva,
per creare scenari e visualizzare report senza usare API.

Acceptance Criteria:

• UI responsive (desktop, tablet, mobile)
• Form creazione scenario guidato
• Dashboard metriche in tempo reale con grafici
• Lista scenari con azioni rapide (view, duplicate, delete)
• Dark/Light mode

US-007: Confronto Scenari

Come decision maker,
voglio confrontare due o più scenari side-by-side,
per valutare l'impatto di diverse configurazioni.

Acceptance Criteria:

• Selezione multipla scenari da confrontare
• Vista comparativa costi totali e per servizio
• Indicatore delta (costo maggiore/minore) con percentuale
• Export confronto in PDF

US-008: Rilevamento Data Leak

Come security engineer,
voglio che il sistema rilevi automaticamente email nei log,
per prevenire l'esposizione di PII ai servizi cloud.

Acceptance Criteria:

• Il sistema identifica pattern email (es. user@example.com)
• Incrementa un contatore di violazioni safety
• Il contatore è visibile nel report dello scenario
• Possibilità di configurare pattern PII custom

US-009: Simulazione Batching

Come system architect,
voglio simulare l'effetto della deduplicazione sui costi LLM,
per valutare se implementare dedup in produzione.

Acceptance Criteria:

• Posso inviare log multipli a uno scenario
• Il sistema conta i token solo per messaggi unici (deduplicazione)
• Vedo nel report il numero di invocazioni Lambda simulate
• Posso confrontare costi con/senza deduplicazione

---

4. Requisiti Funzionali

4.1 Gestione Scenari

REQ-001: Creazione Scenario

Priorità: Alta

Descrizione: Sistema per creare e gestire scenari di simulazione isolati.

Criteri di Accettazione:

• Modello dati Scenario: id, nome, descrizione, tag[], stato, created_at, updated_at
• Parametri configurabili: regione AWS, tier servizi, durata stimata
• API POST /scenarios per creazione
• Validazione nome univoco per utente

REQ-002: Associazione Log a Scenario

Priorità: Alta

Descrizione: I log ingestiti devono essere associati a uno scenario specifico.

Criteri di Accettazione:

• Header X-Scenario-ID o query param scenario_id nell'endpoint /ingest
• Se non specificato, crea scenario "default" o rifiuta
• Metriche aggregate per scenario in database
• Isolamento completo dati tra scenari diversi

REQ-003: Stati Scenario

Priorità: Media

Descrizione: Gestione del ciclo di vita di uno scenario.

Criteri di Accettazione:

• Stati: draft, running, completed, archived
• Transizioni: draft→running→completed→archived
• Solo scenari running accettano nuovi log
• Scenari archived in sola lettura

4.2 Database e Persistenza

REQ-004: Modello Dati Scenari

Priorità: Alta

Descrizione: Tabella/Collection per salvare i metadati degli scenari.

Criteri di Accettazione:

scenarios (
  id: UUID PK,
  name: VARCHAR(255) NOT NULL,
  description: TEXT,
  tags: JSON ARRAY,
  status: ENUM('draft', 'running', 'completed', 'archived'),
  region: VARCHAR(50), -- es. 'us-east-1'
  created_at: TIMESTAMP,
  updated_at: TIMESTAMP,
  completed_at: TIMESTAMP NULL,
  total_requests: INTEGER DEFAULT 0,
  total_cost_estimate: DECIMAL(10,4)
)

REQ-005: Modello Dati Metriche

Priorità: Alta

Descrizione: Tabella per salvare le metriche dettagliate per scenario.

Criteri di Accettazione:

scenario_metrics (
  id: UUID PK,
  scenario_id: UUID FK,
  timestamp: TIMESTAMP,
  metric_type: VARCHAR(50), -- 'sqs', 'lambda', 'bedrock', 'safety'
  metric_name: VARCHAR(100),
  value: DECIMAL(15,4),
  unit: VARCHAR(20), -- 'count', 'bytes', 'tokens', 'usd'
  metadata: JSON -- dettagli aggiuntivi
)

REQ-006: Modello Dati Log Ricevuti

Priorità: Media

Descrizione: Storage dei log ricevuti (opzionale, configurabile retention).

Criteri di Accettazione:

scenario_logs (
  id: UUID PK,
  scenario_id: UUID FK,
  received_at: TIMESTAMP,
  message_hash: VARCHAR(64), -- SHA256 per deduplicazione
  message_preview: VARCHAR(500), -- troncato per privacy
  source: VARCHAR(100),
  size_bytes: INTEGER,
  has_pii: BOOLEAN,
  token_count: INTEGER,
  sqs_blocks: INTEGER
)

4.3 Tabella Costi AWS

REQ-007: Tabella Prezzi Servizi AWS

Priorità: Alta

Descrizione: Tabella configurabile con i prezzi reali dei servizi AWS per regione.

Criteri di Accettazione:

aws_pricing (
  id: UUID PK,
  service: VARCHAR(50), -- 'sqs', 'lambda', 'bedrock'
  region: VARCHAR(50), -- 'us-east-1', 'eu-west-1'
  tier: VARCHAR(50), -- 'standard', 'on-demand'
  price_per_unit: DECIMAL(10,8),
  unit: VARCHAR(20), -- 'request', 'token', 'gb-second'
  effective_from: DATE,
  effective_to: DATE NULL,
  is_active: BOOLEAN DEFAULT true,
  source_url: VARCHAR(500) -- link documentazione AWS
)

Prezzi Iniziali (Esempio):

Servizio	Regione	Tier	Prezzo	Unità
SQS	us-east-1	Standard	$0.40	per milione richieste
Lambda	us-east-1	x86	$0.0000166667	per GB-second
Lambda	us-east-1	Request	$0.20	per milione richieste
Bedrock	us-east-1	Claude 3 Sonnet	$0.003	per 1K token input
Bedrock	us-east-1	Claude 3 Sonnet	$0.015	per 1K token output

REQ-008: Calcolo Costi con Prezzi Reali

Priorità: Alta

Descrizione: Calcolo automatico dei costi usando i prezzi dalla tabella aws_pricing.

Criteri di Accettazione:

• Calcolo costo SQS: blocks * price_per_million / 1000000
• Calcolo costo Lambda: invocations * price_per_request + gb_seconds * price_per_gb_second
• Calcolo costo Bedrock: input_tokens * price_per_1k_input / 1000 + output_tokens * price_per_1k_output / 1000
• Supporto multi-regione (prezzi diversi per regione)
• Totale costo stima aggregato per scenario

REQ-009: Aggiornamento Prezzi

Priorità: Media

Descrizione: Interfaccia per aggiornare i prezzi AWS manualmente o via API.

Criteri di Accettazione:

• API CRUD per gestione prezzi (protetta da auth)
• Validazione prezzi > 0
• Storico prezzi (effective_from/to)
• Possibilità di importare prezzi da CSV

4.4 Interfaccia Web

REQ-010: Dashboard Principale

Priorità: Alta

Descrizione: Pagina principale con overview di tutti gli scenari.

Criteri di Accettazione:

• Lista scenari con: nome, stato, data creazione, costo totale stimato
• Filtri rapidi: tutti, running, completati, archiviati
• Grafico trend costi ultimi 30 giorni
• Card riepilogo: totale scenari, costo medio, scenario più costoso
• Bottone "Nuovo Scenario" prominente

REQ-011: Form Creazione Scenario

Priorità: Alta

Descrizione: Form guidato per creare nuovo scenario.

Criteri di Accettazione:

• Step 1: Info base (nome, descrizione, tag)
• Step 2: Configurazione AWS (regione, tier servizi)
• Step 3: Parametri simulazione (durata, volume atteso)
• Validazione campi obbligatori
• Preview costo base stimato
• Bottone "Crea e Avvia"

REQ-012: Vista Dettaglio Scenario

Priorità: Alta

Descrizione: Pagina dettaglio con tutte le metriche di uno scenario.

Criteri di Accettazione:

• Header: nome, stato, date, azioni (start, stop, archive, delete)
• Tab "Overview": metriche principali, grafici tempo reale
• Tab "Costi": breakdown per servizio, grafici a torta/barre
• Tab "Logs": lista log ricevuti (paginata, con filtri)
• Tab "PII": report violazioni sicurezza rilevate
• Tab "Report": generazione e download report

REQ-013: Confronto Scenari

Priorità: Media

Descrizione: Vista comparativa di multipli scenari.

Criteri di Accettazione:

• Selezione multipla scenari da lista (checkbox)
• Vista side-by-side o tabella comparativa
• Grafici comparativi: costo totale, costo per servizio
• Indicatori delta: +15% più costoso, -10% più economico
• Bottone "Export Confronto PDF"

REQ-014: Pagina Report

Priorità: Media

Descrizione: Generazione e gestione report.

Criteri di Accettazione:

• Configurazione report: formato (PDF/CSV), data range, dettaglio
• Preview report prima del download
• Download diretto
• Storico report generati
• Possibilità di aggiungere note personalizzate

REQ-015: Impostazioni Sistema

Priorità: Bassa

Descrizione: Pagina configurazione applicazione.

Criteri di Accettazione:

• Tab "Prezzi AWS": visualizzazione e modifica tabella prezzi
• Tab "Database": info storage usato, retention policy
• Tab "API": gestione API keys, webhook
• Tab "Tema": dark/light mode, accent color

4.5 API Backend (Aggiunte)

REQ-016: API Scenari

Priorità: Alta

Criteri di Accettazione:

• GET /api/v1/scenarios - Lista scenari (con paginazione, filtri)
• POST /api/v1/scenarios - Crea nuovo scenario
• GET /api/v1/scenarios/{id} - Dettaglio scenario
• PUT /api/v1/scenarios/{id} - Aggiorna scenario
• DELETE /api/v1/scenarios/{id} - Elimina scenario
• POST /api/v1/scenarios/{id}/start - Avvia scenario
• POST /api/v1/scenarios/{id}/stop - Ferma scenario
• POST /api/v1/scenarios/{id}/archive - Archivia scenario

REQ-017: API Report

Priorità: Media

Criteri di Accettazione:

• POST /api/v1/scenarios/{id}/reports - Genera nuovo report
• GET /api/v1/scenarios/{id}/reports - Lista report generati
• GET /api/v1/reports/{report_id}/download - Download report
• GET /api/v1/scenarios/compare?ids=id1,id2 - Confronto scenari

REQ-018: API Costi

Priorità: Media

Criteri di Accettazione:

• GET /api/v1/pricing - Lista prezzi AWS configurati
• PUT /api/v1/pricing/{id} - Aggiorna prezzo
• POST /api/v1/pricing/bulk-update - Aggiornamento multiplo
• GET /api/v1/scenarios/{id}/cost-breakdown - Dettaglio costi scenario

4.6 Funzionalità Esistenti (v0.1)

REQ-019: Endpoint Ingestion (Aggiornato)

Priorità: Alta

Descrizione: Endpoint HTTP POST /ingest aggiornato per supportare scenari.

Criteri di Accettazione:

• Accetta header X-Scenario-ID: <uuid>
• Se scenario non trovato o non running → HTTP 400
• Log salvato in database associato allo scenario
• Metriche aggiornate in tempo reale

REQ-020: Calcolo Metriche (Persistenza)

Priorità: Alta

Descrizione: Le metriche calcolate devono essere salvate in database.

Criteri di Accettazione:

• Ogni log salvato in scenario_logs
• Metriche aggregate salvate in scenario_metrics
• Aggiornamento costo totale in scenarios.total_cost_estimate
• Deduplicazione basata su hash messaggio

---

5. Requisiti Non Funzionali

5.1 Performance

• Throughput: Supporto per almeno 1000 richieste/secondo
• Latenza: P95 < 100ms per endpoint /ingest
• Latenza UI: P95 < 2s per caricamento pagine web
• Memoria: Uso memoria < 1GB per traffico normale
• Generazione Report: < 5s per scenario con 100k log
• CPU: Basso overhead rispetto a semplice pass-through

5.2 Sicurezza

• Validazione input: Sanitizzazione payload JSON e parametri UI
• PII Detection: Rilevamento pattern email nei log
• Persistenza: Crittografia dati sensibili in database (hash messaggi)
• Autenticazione: JWT o session-based per UI web
• Autorizzazione: Ruoli (admin, user, readonly)
• API Keys: Per accesso programmatico protetto

5.3 Affidabilità

• Disponibilità: 99.9% uptime
• Backup: Backup giornaliero database
• Recovery: Restore database < 1 ora
• Test Coverage: > 80% copertura test automatici

5.4 Manutenibilità

• Codice: Type hints obbligatori, follow PEP8
• Documentazione: Docstring per tutte le funzioni pubbliche
• TDD: Test scritti prima dell'implementazione
• Git: Conventional Commits (feat:, fix:, test:)
• Migrazioni: Alembic per schema database

5.5 Usabilità

• UI: Responsive design (mobile, tablet, desktop)
• Temi: Dark/Light mode
• Accessibilità: WCAG 2.1 AA compliance
• I18n: Preparazione per multi-lingua (italiano/inglese)
• Errori: Messaggi chiari, log dettagliati

---

6. Stack Tecnologico

6.1 Backend

Componente	Tecnologia	Versione	Motivazione
Framework Web	FastAPI	>=0.110.0	Async nativo, validazione Pydantic, docs auto
Server ASGI	Uvicorn	>=0.29.0	Performance, supporto async
Validazione	Pydantic	>=2.7.0	Type safety, serializzazione
Tokenizer	tiktoken	>=0.6.0	Compatibile OpenAI/Bedrock
Testing	pytest	>=8.1.1	TDD, fixtures, coverage
HTTP Client	httpx	>=0.27.0	Async testing
Package Manager	uv	latest	Veloce, gestione dipendenze moderna
Python	CPython	>=3.11	Type hints avanzati, performance

6.2 Database

Componente	Tecnologia	Versione	Motivazione
Database	PostgreSQL	>=15	ACID, JSON support, performance
ORM	SQLAlchemy	>=2.0	Standard de-facto, async support
Migrazioni	Alembic	latest	Gestione schema database
Driver	asyncpg	latest	Driver async per PostgreSQL

6.3 Frontend

Componente	Tecnologia	Versione	Motivazione
Framework	React	>=18	Component-based, ecosystem
Build Tool	Vite	latest	Veloce, HMR
UI Library	Tailwind CSS	>=3.4	Utility-first, customizzabile
Componenti	shadcn/ui	latest	Accessible, customizable
Charts	Recharts	latest	React-native, D3-based
State	React Query	latest	Server state management
HTTP Client	Axios	latest	Standard, interceptors

6.4 DevOps

Componente	Tecnologia	Versione	Motivazione
Container	Docker	latest	Isolamento, portabilità
Compose	Docker Compose	latest	Multi-container dev
Reverse Proxy	Nginx	latest	Static files, SSL

---

7. Principi di Design

7.1 Safety First

Tutti i payload in ingresso vengono validati. I log contenenti possibili dati sensibili (PII) vengono identificati e tracciati senza bloccare il flusso. I dati persistenti sono minimizzati (hash al posto di contenuti completi).

7.2 Little Often

Il processamento avviene in piccoli batch frequenti, simulando l'approccio ottimale per Lambda e minimizzando i costi. I report sono generati on-demand e non in background per risparmiare risorse.

7.3 Double Check

Ogni calcolo critico (token count, billing blocks, costi) è verificato con test specifici. Le stime devono essere accurate al 95%+ rispetto ai costi AWS reali. I prezzi AWS sono verificabili e aggiornabili.

7.4 Data-Driven Decisions

L'interfaccia web facilita il confronto tra scenari per supportare decisioni basate sui dati. Ogni scenari è tracciabile e confrontabile nel tempo.

---

8. Architettura di Alto Livello

┌─────────────────────────────────────────────────────────────────────────┐
│                              CLIENT LAYER                                │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────────┐ │
│  │   Logstash      │  │   React Web UI  │  │   API Consumers         │ │
│  │   (o Client)    │  │   (Browser)     │  │   (CI/CD, Scripts)      │ │
│  └────────┬────────┘  └────────┬────────┘  └────────────┬────────────┘ │
└───────────┼────────────────────┼────────────────────────┼──────────────┘
            │                    │                        │
            │ HTTP POST          │ HTTPS                  │ API Key
            │ /ingest            │ /api/v1/*              │ /api/v1/*
            ▼                    ▼                        ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                              API LAYER (FastAPI)                         │
│  ┌────────────────────────────────────────────────────────────────────┐ │
│  │  Authentication & Authorization (JWT / API Key)                    │ │
│  └────────────────────────────────────────────────────────────────────┘ │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌──────────────────┐  │
│  │ /scenarios  │ │ /ingest     │ │ /reports    │ │ /pricing         │  │
│  │ CRUD        │ │ (scenario)  │ │ generate    │ │ CRUD            │  │
│  └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └────────┬─────────┘  │
└─────────┼───────────────┼───────────────┼─────────────────┼────────────┘
          │               │               │                 │
          ▼               ▼               ▼                 ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                           SERVICE LAYER                                  │
│  ┌────────────────┐ ┌────────────────┐ ┌──────────────────────────────┐ │
│  │  Scenario      │ │  Ingestion     │ │  Cost Calculator             │ │
│  │  Service       │ │  Service       │ │  (AWS Pricing)               │ │
│  │  - CRUD        │ │  - Queue       │ │  - SQS cost                  │ │
│  │  - Lifecycle   │ │  - Batch       │ │  - Lambda cost               │ │
│  │  - Validation  │ │  - Deduplicate │ │  - Bedrock cost              │ │
│  └────────────────┘ └────────────────┘ └──────────────────────────────┘ │
│  ┌────────────────┐ ┌────────────────┐ ┌──────────────────────────────┐ │
│  │  Report        │ │  PII Detector  │ │  Tokenizer                   │ │
│  │  Generator     │ │  (Safety)      │ │  (tiktoken)                  │ │
│  │  - PDF         │ │  - Email check │ │  - cl100k_base               │ │
│  │  - CSV         │ │  - Pattern     │ │  - Token count               │ │
│  └────────────────┘ └────────────────┘ └──────────────────────────────┘ │
└─────────┬───────────────────────────────────────────────────┬───────────┘
          │                                                   │
          ▼                                                   ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                           DATABASE LAYER (PostgreSQL)                    │
│  ┌────────────────┐ ┌────────────────┐ ┌──────────────────────────────┐ │
│  │  scenarios     │ │  scenario_logs │ │  aws_pricing                 │ │
│  │  - metadata    │ │  - logs        │ │  - prices                    │ │
│  │  - config      │ │  - metrics     │ │  - history                   │ │
│  └────────────────┘ └────────────────┘ └──────────────────────────────┘ │
│  ┌────────────────┐ ┌────────────────┐                                  │
│  │  scenario_     │ │  reports       │                                  │
│  │  metrics       │ │  - generated   │                                  │ │
│  │  - aggregated  │ │  - metadata    │                                  │ │
│  └────────────────┘ └────────────────┘                                  │
└─────────────────────────────────────────────────────────────────────────┘

---

9. Criteri di Accettazione Release

v0.2.0 - Scenari e Persistenza

• Database PostgreSQL configurato e funzionante
• Tabelle scenarios, scenario_logs, scenario_metrics create
• API CRUD scenari complete (/scenarios)
• Associazione log a scenario funzionante
• Tabella aws_pricing con dati reali popolata
• Calcolo costi usando prezzi dalla tabella
• Storicizzazione automatica metriche
• Test coverage > 80%
• Documentazione API (OpenAPI)

v0.3.0 - Interfaccia Web

• Dashboard React funzionante
• Form creazione scenario
• Vista dettaglio scenario con metriche
• Lista scenari con filtri
• Dark/Light mode
• Responsive design
• Export report CSV

v0.4.0 - Report e Confronto

• Generazione report PDF
• Pagina confronto scenari
• Grafici interattivi (Recharts)
• API confronto scenari
• Export confronto PDF

v1.0.0 - Produzione

• Autenticazione e autorizzazione
• API Keys management
• Backup automatico database
• Monitoraggio e alerting
• Documentazione utente completa
• Performance test superati

---

10. Roadmap

Q2 2026

• Maggio: Database, API scenari, persistenza metriche
• Giugno: Tabella prezzi AWS, calcolo costi, test integrazione

Q3 2026

• Luglio: Frontend React base, dashboard, lista scenari
• Agosto: Form creazione, vista dettaglio, grafici
• Settembre: Report PDF, confronto scenari, polish UI

Q4 2026

• Ottobre: Auth, security, API keys
• Novembre: Performance optimization, caching
• Dicembre: Bug fixing, documentazione, release v1.0

Future Releases (post-v1.0)

• Supporto multi-utente con workspace
• Integration test con vero account AWS (read-only)
• Machine learning per predizione costi
• Alerting automatico se costo supera soglia
• Supporto Azure e GCP oltre ad AWS

---

11. Appendici

11.1 Schema Database Completo (ER Diagram)

┌─────────────────┐       ┌──────────────────┐       ┌─────────────────┐
│   scenarios     │       │ scenario_metrics │       │  scenario_logs  │
├─────────────────┤       ├──────────────────┤       ├─────────────────┤
│ PK id           │◄──────┤ FK scenario_id   │       │ FK scenario_id  │
│    name         │       │    timestamp     │       │    received_at  │
│    description  │       │    metric_type   │       │    message_hash │
│    tags[]       │       │    metric_name   │       │    preview      │
│    status       │       │    value         │       │    source       │
│    region       │       │    unit          │       │    size_bytes   │
│    created_at   │       │    metadata      │       │    has_pii      │
│    updated_at   │       └──────────────────┘       │    token_count  │
│    total_cost   │                                  └─────────────────┘
└─────────────────┘
          │
          │
          ▼
┌─────────────────┐       ┌──────────────────┐
│  aws_pricing    │       │     reports      │
├─────────────────┤       ├──────────────────┤
│ PK id           │       │ PK id            │
│    service      │       │ FK scenario_id   │
│    region       │       │    format        │
│    tier         │       │    file_path     │
│    price        │       │    generated_at  │
│    unit         │       │    metadata      │
│    effective_   │       └──────────────────┘
│    from/to      │
│    is_active    │
└─────────────────┘

11.2 Esempio Flusso Completo

1. Creazione Scenario:

   POST /api/v1/scenarios
   {
     "name": "Produzione Q2",
     "description": "Simulazione traffico produzione",
     "region": "us-east-1",
     "tags": ["production", "q2"]
   }
   → Response: { "id": "uuid-scenario-123" }
   

2. Invio Log:

   POST /ingest
   Header: X-Scenario-ID: uuid-scenario-123
   Body: { "message": "Error: connection timeout", "source": "api" }
   

3. Visualizzazione Web:

   • User apre dashboard
   • Seleziona scenario "Produzione Q2"
   • Vede metriche in tempo reale
   • Grafici costi per servizio

4. Generazione Report:

   POST /api/v1/scenarios/uuid-scenario-123/reports
   { "format": "pdf", "include_logs": false }
   

   → Download report completo

---

Documento mantenuto dal team LogWhispererAI. Ultimo aggiornamento: 2026-04-07