# Prompt Zero: mockupAWS - Project Kickoff

## 🎯 Missione

Sviluppare **mockupAWS**, un ambiente di simulazione locale per profilare traffico log e calcolare i driver di costo AWS (SQS, Lambda, Bedrock/LLM) prima del deploy in produzione.

**Repository:** `/home/google/Sources/LucaSacchiNet/mockupAWS`  
**PRD:** `/home/google/Sources/LucaSacchiNet/mockupAWS/export/prd.md`

---

## 📊 Stato Attuale

- ✅ **PRD Completo**: Requisiti funzionali e non funzionali definiti (v0.2.0)
- ✅ **Team Configurato**: 6 agenti specializzati pronti
- ⚠️ **Codice Base Parziale**: API base implementata (v0.1), manca database e persistenza
- ❌ **Database**: Schema da creare (PostgreSQL)
- ❌ **Frontend**: Dashboard React da implementare
- ❌ **Docker**: Configurazione da creare

### Cosa è già fatto:
- FastAPI base con endpoint `/ingest`, `/metrics`, `/reset`, `/flush`
- Calcolo metriche: SQS blocks, token count (tiktoken), PII detection
- Test suite pytest (5 test passanti)
- Documentazione: README, PRD, architettura
- Struttura progetto e configurazione uv

### Cosa manca (Priorità):
1. Database PostgreSQL con tabelle scenarios, logs, metrics, pricing
2. Alembic migrations
3. API CRUD scenari complete
4. Calcolo costi con prezzi AWS reali
5. Frontend React con dashboard
6. Docker Compose setup

---

## 👥 Team di Sviluppo

| Agente | Ruolo | Config | Responsabilità |
|--------|-------|--------|----------------|
| `@spec-architect` | Software Architect | `.opencode/agents/spec-architect.md` | Specifiche tecniche, architettura, coordinamento |
| `@db-engineer` | Database Engineer | `.opencode/agents/db-engineer.md` | Schema DB, Alembic migrations, queries |
| `@backend-dev` | Backend Developer | `.opencode/agents/backend-dev.md` | FastAPI endpoints, services, tests |
| `@frontend-dev` | Frontend Developer | `.opencode/agents/frontend-dev.md` | React dashboard, UI components |
| `@devops-engineer` | DevOps Engineer | `.opencode/agents/devops-engineer.md` | Docker, CI/CD, deployment |
| `@qa-engineer` | QA Engineer | `.opencode/agents/qa-engineer.md` | Testing strategy, E2E tests |

---

## 🔄 Workflow Obbligatorio

```
┌─────────────────────────────────────────────────────────────────┐
│  FASE 1: ARCHITETTURA & DATABASE                                 │
│  @spec-architect + @db-engineer                                 │
│  └── Finalizza architecture.md + Crea schema DB + Migrations     │
│                                                                  │
│  ↓                                                               │
│                                                                  │
│  FASE 2: BACKEND API                                             │
│  @backend-dev + @db-engineer                                    │
│  └── Implementa API CRUD scenari + Persistenza metriche          │
│                                                                  │
│  ↓                                                               │
│                                                                  │
│  FASE 3: FRONTEND                                                │
│  @frontend-dev                                                   │
│  └── Dashboard React + Forms + Visualizzazione dati              │
│                                                                  │
│  ↓                                                               │
│                                                                  │
│  FASE 4: DEVOPS & QA                                             │
│  @devops-engineer + @qa-engineer                                │
│  └── Docker Compose + CI/CD + Testing E2E                        │
└─────────────────────────────────────────────────────────────────┘
```

---

## 🚀 Task Iniziale: Fase 1 - Architettura e Database

**AGENTE:** `@spec-architect` + `@db-engineer`

**OBIETTIVO:** Completare le specifiche tecniche e creare il database schema.

### Azioni Richieste

#### 1. @spec-architect - Analisi e Specifiche

1. **Leggere** `/home/google/Sources/LucaSacchiNet/mockupAWS/export/prd.md`

2. **Analizzare** il codice esistente in `/home/google/Sources/LucaSacchiNet/mockupAWS/src/`

3. **Aggiornare** `/home/google/Sources/LucaSacchiNet/mockupAWS/export/architecture.md` con:
   - Stack tecnologico dettagliato (conferma FastAPI + PostgreSQL + React)
   - Struttura cartelle progetto finale
   - Diagrammi flusso dati (Mermaid o ASCII)
   - API specifications complete (OpenAPI specs)
   - Piano di sicurezza (JWT, API keys)

4. **Creare** `/home/google/Sources/LucaSacchiNet/mockupAWS/export/kanban.md` con:
   - Task breakdown per Fase 1 (Database + Backend API)
   - Task breakdown per Fase 2 (Frontend)
   - Stima complessità (XS/S/M/L)
   - Dipendenze tra task
   - Regola "little often": task < 2 ore

5. **Inizializzare** `/home/google/Sources/LucaSacchiNet/mockupAWS/export/progress.md` con:
   - Feature corrente: "Fase 1 - Database e Backend API"
   - Stato: "🔴 Pianificazione"
   - Percentuale: 10%

#### 2. @db-engineer - Schema Database

1. **Progettare** schema PostgreSQL completo:
   ```sql
   -- Tabelle richieste:
   - scenarios (metadata scenario)
   - scenario_logs (log ricevuti con hash)
   - scenario_metrics (metriche aggregate)
   - aws_pricing (prezzi AWS per regione)
   - reports (report generati)
   ```

2. **Creare** Alembic setup:
   - `alembic init alembic`
   - Configurare `alembic.ini`
   - Creare `migrations/env.py` con async support

3. **Creare** migrazioni iniziali:
   - `001_create_scenarios_table.py`
   - `002_create_scenario_logs_table.py`
   - `003_create_scenario_metrics_table.py`
   - `004_create_aws_pricing_table.py`
   - `005_create_reports_table.py`
   - `006_seed_aws_pricing_data.py`

4. **Documentare** in `docs/database_schema.md`:
   - Schema ER completo
   - Indici creati
   - Constraints e foreign keys

### Criteri di Accettazione Fase 1

- [ ] `architecture.md` completo con tutte le sezioni
- [ ] `kanban.md` con task pronti per sviluppo
- [ ] `progress.md` inizializzato con stato attuale
- [ ] Schema database progettato e documentato
- [ ] Migrazioni Alembic create e testate
- [ ] Tabelle create correttamente in PostgreSQL

---

## 📋 Requisiti Chiave (Dal PRD)

### Priorità Alta (MVP v0.2.0)

1. **Database & Persistenza**
   - PostgreSQL con tabelle scenarios, logs, metrics, pricing
   - Alembic migrations
   - Seed dati prezzi AWS reali

2. **API Scenari**
   - CRUD completo: GET/POST/PUT/DELETE /api/v1/scenarios
   - Gestione stati: draft → running → completed → archived
   - Associazione log a scenario via X-Scenario-ID header

3. **Calcolo Costi**
   - Formula SQS: blocks × price_per_million / 1000000
   - Formula Lambda: invocations × price + gb_seconds × price
   - Formula Bedrock: tokens × price_per_1k / 1000
   - Prezzi per regione (us-east-1, eu-west-1)

4. **Testing**
   - Test coverage > 80%
   - Unit tests per services
   - Integration tests per API

### Priorità Media (v0.3.0)

5. **Dashboard Web**
   - React + TypeScript + Tailwind
   - Lista scenari con filtri
   - Form creazione scenario
   - Vista dettaglio con metriche

6. **Report**
   - Export CSV
   - Visualizzazione grafici

### Priorità Bassa (v0.4.0)

7. **Report PDF**
8. **Confronto scenari**
9. **Autenticazione**

---

## 🛡️ Vincoli e Best Practices

### Sicurezza (Critico)
- SQL injection prevention (SQLAlchemy ORM)
- XSS prevention (React escaping)
- CSRF protection
- Rate limiting (slowapi)
- Hashing messaggi per privacy
- No PII in logs persistenti

### Qualità
- Test coverage ≥ 80%
- TDD obbligatorio per backend
- Type hints obbligatori (Python + TypeScript)
- Conventional commits
- Commit atomici

### Organizzazione
- Task "little often" (< 2 ore)
- Documentazione in `/export/`
- Bug complessi in `/docs/bug_ledger.md`
- PR con code review

---

## 📁 Struttura Progetto Finale

```
/home/google/Sources/LucaSacchiNet/mockupAWS/
├── export/                      # Output spec-driven
│   ├── prd.md                  # Product Requirements
│   ├── architecture.md         # Architettura sistema
│   ├── kanban.md              # Task breakdown
│   └── progress.md            # Tracciamento progresso
├── docs/
│   ├── architecture.md        # ADR (Architecture Decision Records)
│   ├── bug_ledger.md          # Bug tracking
│   └── database_schema.md     # Schema DB documentazione
├── prompt/
│   └── prompt-zero.md         # Questo file
├── .opencode/
│   └── agents/                # Configurazioni agenti
│       ├── spec-architect.md
│       ├── backend-dev.md
│       ├── db-engineer.md
│       ├── frontend-dev.md
│       ├── devops-engineer.md
│       └── qa-engineer.md
├── backend/                    # FastAPI application
│   ├── src/
│   │   ├── __init__.py
│   │   ├── main.py            # Entry point
│   │   ├── config.py          # Configuration
│   │   ├── models/            # SQLAlchemy models
│   │   ├── schemas/           # Pydantic schemas
│   │   ├── api/               # API endpoints
│   │   ├── services/          # Business logic
│   │   └── core/              # Utils, auth, etc.
│   ├── tests/
│   │   ├── unit/
│   │   ├── integration/
│   │   └── conftest.py
│   ├── alembic/               # Database migrations
│   ├── Dockerfile
│   └── pyproject.toml
├── frontend/                   # React application
│   ├── src/
│   │   ├── components/        # React components
│   │   ├── pages/             # Page components
│   │   ├── hooks/             # Custom hooks
│   │   ├── services/          # API clients
│   │   └── types/             # TypeScript types
│   ├── public/
│   ├── Dockerfile
│   └── package.json
├── docker-compose.yml          # Full stack orchestration
├── nginx.conf                  # Reverse proxy config
└── README.md
```

---

## ✅ Checklist Pre-Sviluppo

- [ ] @spec-architect ha letto questo prompt e il PRD
- [ ] @db-engineer ha revisionato il PRD sezione database
- [ ] Team allineato sulle priorita (MVP v0.2.0)
- [ ] Architettura approvata
- [ ] Schema database pronto

---

## 🎬 Prossima Azione

**@spec-architect**: Inizia analizzando il PRD e il codice esistente, poi aggiorna `architecture.md` e `kanban.md`.

**@db-engineer**: Inizia progettando lo schema database e le migrazioni Alembic.

**NON iniziare l'implementazione del codice di business logic** finché architettura e schema DB non sono completati e revisionati.

---

## 📞 Note per il Team

- **Domande sul PRD?** Leggi prima `export/prd.md` completamente
- **Codice esistente?** Esamina `/home/google/Sources/LucaSacchiNet/mockupAWS/src/` prima di iniziare
- **Ambiguità?** Chiedi prima di procedere
- **Vincoli tecnici?** Documentali in `architecture.md`
- **Task troppo grandi?** Spezza in task più piccoli seguendo "little often"

---

**Data Creazione:** 2026-04-07  
**Versione:** 2.0  
**Stato:** Pronto per kickoff - Fase 1: Architettura e Database

---

## 📝 Note sullo Stato Attuale

Il progetto ha già una base solida con:
- API FastAPI funzionante con metriche base
- Test suite completa (pytest)
- Documentazione PRD dettagliata

Il team deve ora:
1. Completare l'architettura tecnica
2. Implementare il database layer
3. Evolvere l'API esistente per supportare scenari
4. Costruire il frontend
5. Containerizzare tutto

Il lavoro può procedere in parallelo dopo la fase di architettura:
- Backend e DB possono procedere insieme
- Frontend può iniziare con mock data
- DevOps può preparare l'infrastruttura