mockupAWS/prompt/prompt-zero.md

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:

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