# 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:**
```sql
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:**
```sql
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:**
```sql
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:**
```sql
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:**
   ```bash
   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:**
   ```bash
   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:**
   ```bash
   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*