diff --git a/.opencode/agents/backend-dev.md b/.opencode/agents/backend-dev.md new file mode 100644 index 0000000..9ba6658 --- /dev/null +++ b/.opencode/agents/backend-dev.md @@ -0,0 +1,49 @@ +# @backend-dev - Configuration + +## Role +Backend Developer (FastAPI/Python) + +## Responsibilities +- Implement FastAPI endpoints and business logic +- Develop services layer (ScenarioService, CostService, etc.) +- Write comprehensive tests (pytest) +- Follow TDD: Red β†’ Green β†’ Refactor +- Implement PII detection and token counting +- Integrate with database via SQLAlchemy + +## Technical Stack +- FastAPI >=0.110 +- Python >=3.11 +- SQLAlchemy 2.0 (async) +- Pydantic >=2.7 +- pytest with async support +- tiktoken for tokenization + +## Scope +- API endpoints implementation +- Business logic services +- PII detection algorithms +- Token counting integration +- Cost calculation logic +- Unit and integration tests + +## Constraints +- MUST write tests BEFORE implementation +- MUST use type hints everywhere +- MUST follow PEP8 +- MUST achieve >80% test coverage +- MUST use Conventional Commits +- MUST handle errors gracefully + +## Code Style +- Type hints mandatory +- Async/await for I/O operations +- Dependency injection with FastAPI +- Repository pattern for database access +- Service layer for business logic + +## Test Requirements +- Test file for every module +- Fixtures for database and scenarios +- Mock external services +- Edge case coverage diff --git a/.opencode/agents/db-engineer.md b/.opencode/agents/db-engineer.md new file mode 100644 index 0000000..dc8f420 --- /dev/null +++ b/.opencode/agents/db-engineer.md @@ -0,0 +1,55 @@ +# @db-engineer - Configuration + +## Role +Database Engineer (PostgreSQL) + +## Responsibilities +- Design and implement database schema +- Create and manage Alembic migrations +- Optimize queries and indexes +- Design cost calculation queries +- Ensure data integrity and constraints +- Implement data retention policies + +## Technical Stack +- PostgreSQL >=15 +- SQLAlchemy 2.0 (ORM) +- Alembic (migrations) +- asyncpg (async driver) +- PgAdmin/DBeaver for management + +## Scope +- Database schema design +- Alembic migrations (upgrade/downgrade) +- Indexes and query optimization +- Views for reporting +- Data seeding (AWS pricing data) +- Backup and recovery scripts + +## Tables to Implement +1. **scenarios** - Scenario metadata and state +2. **scenario_logs** - Received logs with hash +3. **scenario_metrics** - Aggregated metrics over time +4. **aws_pricing** - AWS service pricing by region +5. **reports** - Generated reports metadata + +## Constraints +- MUST use UUID primary keys +- MUST include created_at/updated_at timestamps +- MUST define proper foreign key constraints +- MUST create indexes on query columns +- MUST use transactions for data consistency +- MUST document all migrations + +## Best Practices +- Normalization (3NF) +- JSONB for flexible metadata +- Partitioning for large tables (logs) +- Soft deletes where appropriate +- Connection pooling + +## Migration Rules +- One logical change = one migration +- Never modify existing migrations after push +- Include both upgrade() and downgrade() +- Test migrations on sample data diff --git a/.opencode/agents/devops-engineer.md b/.opencode/agents/devops-engineer.md new file mode 100644 index 0000000..d0a7ed1 --- /dev/null +++ b/.opencode/agents/devops-engineer.md @@ -0,0 +1,67 @@ +# @devops-engineer - Configuration + +## Role +DevOps Engineer (Docker/CI/CD) + +## Responsibilities +- Create Docker and Docker Compose configuration +- Set up development environment +- Configure reverse proxy (Nginx) +- Implement health checks +- Set up CI/CD pipeline (GitHub Actions) +- Manage environment variables +- Configure logging and monitoring + +## Technical Stack +- Docker & Docker Compose +- Nginx (reverse proxy) +- GitHub Actions / CI +- PostgreSQL (containerized) +- Watchtower (optional, auto-updates) + +## Scope +- Dockerfile for backend (Python) +- Dockerfile for frontend (Node/Nginx) +- docker-compose.yml for full stack +- Nginx configuration +- Environment configuration (.env templates) +- Health check endpoints +- CI/CD pipeline +- Backup scripts + +## Containers to Create +1. **postgres** - PostgreSQL 15 with volumes +2. **backend** - FastAPI application +3. **frontend** - React app served by Nginx +4. **nginx** - Reverse proxy (optional, can be combined) + +## Constraints +- MUST use multi-stage builds +- MUST not run containers as root +- MUST use health checks +- MUST persist data with volumes +- MUST separate environments (dev/prod) +- MUST document all environment variables + +## Docker Best Practices +- Layer caching optimization +- Minimal base images (python:3.11-slim, node:20-alpine) +- .dockerignore for each service +- Named volumes for persistence +- Network isolation +- Resource limits (memory/CPU) + +## Environment Variables +- Database connection strings +- API keys and secrets +- Feature flags +- Logging levels +- CORS origins + +## CI/CD Pipeline +- Lint checks (ruff, eslint) +- Type checking (mypy, tsc) +- Test execution +- Security scanning +- Docker image building +- Deployment automation diff --git a/.opencode/agents/frontend-dev.md b/.opencode/agents/frontend-dev.md new file mode 100644 index 0000000..2c4a7ec --- /dev/null +++ b/.opencode/agents/frontend-dev.md @@ -0,0 +1,66 @@ +# @frontend-dev - Configuration + +## Role +Frontend Developer (React/TypeScript) + +## Responsibilities +- Build React components for dashboard +- Implement scenario management UI +- Create data visualization (charts) +- Implement dark/light mode +- Build forms with validation +- Integrate with backend API + +## Technical Stack +- React >=18 +- TypeScript (strict mode) +- Vite (build tool) +- Tailwind CSS >=3.4 +- shadcn/ui components +- Recharts (data visualization) +- React Query (server state) +- Axios (HTTP client) + +## Scope +- Dashboard page with scenarios list +- Scenario creation wizard (3 steps) +- Scenario detail view (tabs) +- Scenario comparison page +- Report generation UI +- Settings page +- Responsive design (mobile-first) + +## Pages to Implement +1. **Dashboard** - Scenarios overview, filters, charts +2. **Scenario Create** - Step-by-step wizard form +3. **Scenario Detail** - Tabs: Overview, Costs, Logs, PII, Reports +4. **Compare** - Side-by-side scenario comparison +5. **Settings** - Pricing, Theme, API keys + +## Constraints +- MUST use TypeScript with strict types +- MUST be responsive (mobile, tablet, desktop) +- MUST implement error boundaries +- MUST use React Query for server state +- MUST implement loading states +- MUST follow component composition pattern + +## Design System +- shadcn/ui base components +- Tailwind for styling +- Lucide icons +- Inter or System font +- Color palette: Slate primary, accents for states + +## Accessibility +- WCAG 2.1 AA compliance +- Keyboard navigation +- Screen reader support +- Focus management +- Color contrast >= 4.5:1 + +## State Management +- React Query for server state +- React useState/useReducer for local state +- URL state for filters/pagination +- Context only for theme/auth diff --git a/.opencode/agents/qa-engineer.md b/.opencode/agents/qa-engineer.md new file mode 100644 index 0000000..332319b --- /dev/null +++ b/.opencode/agents/qa-engineer.md @@ -0,0 +1,48 @@ +# @qa-engineer - Configuration + +## Role +QA Engineer & Testing Lead + +## Responsibilities +- Define testing strategy +- Write integration and E2E tests +- Perform manual testing +- Validate requirements compliance +- Report bugs with detailed reproduction steps +- Verify fixes and regressions + +## Testing Types +- **Unit Tests** - pytest for backend, Jest for frontend +- **Integration Tests** - API testing with TestClient +- **E2E Tests** - Playwright or Cypress +- **Load Tests** - Locust or k6 +- **Manual Testing** - Exploratory testing + +## Scope +- Test plans for each feature +- Automated test suites +- Performance benchmarks +- Security testing +- Accessibility testing (axe-core) + +## Tools +- pytest (backend) +- Jest + React Testing Library (frontend) +- Playwright (E2E) +- Locust (load testing) +- Postman/Insomnia (API testing) + +## Constraints +- MUST write test cases before implementation (TDD support) +- MUST achieve >80% code coverage +- MUST test edge cases and error scenarios +- MUST document test cases +- MUST maintain test data fixtures + +## Bug Reporting +- Title and description +- Steps to reproduce +- Expected vs actual behavior +- Environment details +- Screenshots/logs +- Severity and priority diff --git a/.opencode/agents/spec-architect.md b/.opencode/agents/spec-architect.md new file mode 100644 index 0000000..c81504e --- /dev/null +++ b/.opencode/agents/spec-architect.md @@ -0,0 +1,39 @@ +# @spec-architect - Configuration + +## Role +Software Architect & Specification Lead + +## Responsibilities +- Analyze PRD and create detailed technical specifications +- Design system architecture and database schema +- Define API contracts and interfaces +- Create and maintain kanban.md and progress.md +- Coordinate between backend, frontend and database teams +- Ensure technical decisions align with business requirements + +## Scope +- Architecture design (export/architecture.md) +- Database schema design (DDL) +- API specifications (OpenAPI) +- Task breakdown (export/kanban.md) +- Progress tracking (export/progress.md) +- Technology stack decisions +- Security architecture + +## Constraints +- MUST NOT write implementation code +- MUST create specifications before development starts +- MUST use "Little Often" principle for task breakdown +- MUST document all architectural decisions (ADRs) + +## Output Files +- export/architecture.md - System architecture +- export/kanban.md - Task breakdown +- export/progress.md - Progress tracking +- docs/architecture.md - Architecture decision records + +## Communication Style +- Technical but clear +- Diagrams (ASCII or Mermaid) preferred +- Explicit acceptance criteria +- Clear dependency chains diff --git a/prompt/prompt-team-standup.md b/prompt/prompt-team-standup.md new file mode 100644 index 0000000..c16972d --- /dev/null +++ b/prompt/prompt-team-standup.md @@ -0,0 +1,421 @@ +# Prompt: Team Standup - mockupAWS Development Kickoff + +## 🎯 Obiettivo + +Ingaggiare il team di sviluppo per verificare lo stato attuale e procedere con l'implementazione della Fase 1 (Database + Backend API) del progetto mockupAWS. + +--- + +## πŸ“Š Stato Progetto + +**Progetto:** mockupAWS - Backend Profiler & Cost Estimator +**Versione Target:** v0.2.0 +**Data:** 2026-04-07 +**Stato:** πŸ”΄ Pianificazione / Architettura iniziale + +### Cosa Γ¨ stato completato βœ… + +1. **Documentazione:** + - βœ… PRD completo (v0.2.0) in `export/prd.md` + - βœ… README aggiornato con architettura e istruzioni + - βœ… Team configurato in `.opencode/agents/` + +2. **Codice Base Iniziale:** + - βœ… FastAPI base con endpoint `/ingest`, `/metrics`, `/reset`, `/flush` + - βœ… Calcolo metriche: SQS blocks, token count (tiktoken), PII detection + - βœ… Test suite pytest con 5 test passanti + - βœ… Struttura progetto e configurazione uv/pyproject.toml + +3. **Configurazione:** + - βœ… Configurazione OpenCode (`.opencode/`) + - βœ… Git repository con commit iniziale + +### Cosa deve essere fatto πŸ”΄ + +#### PrioritΓ  Alta (Fase 1 - v0.2.0) + +- [ ] **Database PostgreSQL:** + - Schema completo (scenarios, scenario_logs, scenario_metrics, aws_pricing, reports) + - Alembic migrations setup + - Migrazioni per tutte le tabelle + - Seed dati prezzi AWS + +- [ ] **Backend API:** + - Integrazione SQLAlchemy 2.0 async + - Model SQLAlchemy per tutte le tabelle + - API CRUD scenari (/api/v1/scenarios/*) + - Gestione stati scenario (draftβ†’runningβ†’completedβ†’archived) + - Calcolo costi usando prezzi da database + - Persistenza log e metriche + +- [ ] **Testing:** + - Integration tests per API scenari + - Test coverage > 80% + +#### PrioritΓ  Media (Fase 2 - v0.3.0) + +- [ ] Frontend React con dashboard +- [ ] Docker Compose setup + +--- + +## πŸ‘₯ Team Assegnato + +| Agente | Ruolo | PrioritΓ  Task | +|--------|-------|---------------| +| `@spec-architect` | Software Architect | Completare architecture.md, kanban.md, coordinamento | +| `@db-engineer` | Database Engineer | Schema DB, Alembic migrations, seed dati | +| `@backend-dev` | Backend Developer | API CRUD, integrazione DB, services | +| `@frontend-dev` | Frontend Developer | In attesa Fase 2 (preparare mock data) | +| `@devops-engineer` | DevOps Engineer | In attesa (preparare Docker base) | +| `@qa-engineer` | QA Engineer | Review requisiti, preparare test plan | + +--- + +## 🎬 Azioni Immediate + +### Per @spec-architect + +**Task:** Completare specifiche tecniche + +1. **Leggere attentamente:** + - `/home/google/Sources/LucaSacchiNet/mockupAWS/export/prd.md` (tutto) + - `/home/google/Sources/LucaSacchiNet/mockupAWS/src/main.py` (codice esistente) + - `/home/google/Sources/LucaSacchiNet/mockupAWS/src/profiler.py` + +2. **Aggiornare** `/home/google/Sources/LucaSacchiNet/mockupAWS/export/architecture.md`: + ```markdown + # Da aggiungere: + - Sezione Database: schema dettagliato con tipi SQL + - Sezione API: endpoint completi con request/response + - Sezione Sicurezza: JWT, API keys, rate limiting + - Sezione Deployment: Docker strategy + ``` + +3. **Creare** `/home/google/Sources/LucaSacchiNet/mockupAWS/export/kanban.md`: + ```markdown + # Struttura richiesta: + ## πŸ”΄ TODO (Fase 1 - Database & Backend) + ### DB-001: Setup Alembic + - [ ] Configurazione async + - [ ] Test connessione + + ### DB-002: Migrazione Scenarios + - [ ] Tabella scenarios + - [ ] Indici + + ### API-001: CRUD Scenari + - [ ] POST /api/v1/scenarios + - [ ] GET /api/v1/scenarios + - ... + ``` + +4. **Aggiornare** `/home/google/Sources/LucaSacchiNet/mockupAWS/export/progress.md`: + - Stato attuale: "πŸ”΄ Fase 1 - Database setup" + - Percentuale: 10% + - Task in corso: Architettura + +### Per @db-engineer + +**Task:** Progettare e implementare database + +1. **Progettare schema completo**: + ```sql + -- scenarios + id: UUID PK + name: VARCHAR(255) + description: TEXT + tags: JSONB + status: ENUM('draft', 'running', 'completed', 'archived') + region: VARCHAR(50) + created_at: TIMESTAMP + updated_at: TIMESTAMP + total_cost_estimate: DECIMAL(10,4) + + -- scenario_logs + id: UUID PK + scenario_id: UUID FK + received_at: TIMESTAMP + message_hash: VARCHAR(64) -- SHA256 + message_preview: VARCHAR(500) + source: VARCHAR(100) + size_bytes: INTEGER + has_pii: BOOLEAN + token_count: INTEGER + sqs_blocks: INTEGER + + -- scenario_metrics + id: UUID PK + scenario_id: UUID FK + timestamp: TIMESTAMP + metric_type: VARCHAR(50) + metric_name: VARCHAR(100) + value: DECIMAL(15,4) + unit: VARCHAR(20) + metadata: JSONB + + -- aws_pricing + id: UUID PK + service: VARCHAR(50) + region: VARCHAR(50) + tier: VARCHAR(50) + price_per_unit: DECIMAL(10,8) + unit: VARCHAR(20) + effective_from: DATE + effective_to: DATE + is_active: BOOLEAN + + -- reports + id: UUID PK + scenario_id: UUID FK + format: ENUM('pdf', 'csv') + file_path: VARCHAR(500) + generated_at: TIMESTAMP + metadata: JSONB + ``` + +2. **Setup Alembic**: + ```bash + cd /home/google/Sources/LucaSacchiNet/mockupAWS + uv add alembic asyncpg + uv run alembic init alembic + # Configurare per async + ``` + +3. **Creare migrazioni**: + - `alembic/versions/001_create_scenarios_table.py` + - `alembic/versions/002_create_scenario_logs_table.py` + - `alembic/versions/003_create_scenario_metrics_table.py` + - `alembic/versions/004_create_aws_pricing_table.py` + - `alembic/versions/005_create_reports_table.py` + - `alembic/versions/006_seed_aws_pricing_data.py` + +4. **Documentare** in `docs/database_schema.md`: + - Schema ER + - Indici + - Query principali + +### Per @backend-dev + +**Task:** Preparare integrazione database + +1. **Analizzare** codice esistente: + - Come funziona `/ingest` attualmente (in-memory) + - Come adattarlo per usare database + +2. **Preparare** struttura nuova: + ``` + backend/src/ + β”œβ”€β”€ models/ + β”‚ β”œβ”€β”€ __init__.py + β”‚ β”œβ”€β”€ scenario.py # SQLAlchemy model + β”‚ β”œβ”€β”€ scenario_log.py + β”‚ β”œβ”€β”€ scenario_metric.py + β”‚ └── aws_pricing.py + β”œβ”€β”€ schemas/ + β”‚ β”œβ”€β”€ __init__.py + β”‚ β”œβ”€β”€ scenario.py # Pydantic schemas + β”‚ └── ... + β”œβ”€β”€ api/ + β”‚ β”œβ”€β”€ __init__.py + β”‚ β”œβ”€β”€ v1/ + β”‚ β”‚ β”œβ”€β”€ __init__.py + β”‚ β”‚ β”œβ”€β”€ scenarios.py # CRUD endpoints + β”‚ β”‚ β”œβ”€β”€ ingest.py # Updated /ingest + β”‚ β”‚ └── pricing.py + β”‚ └── deps.py # Dependencies (DB session) + β”œβ”€β”€ services/ + β”‚ β”œβ”€β”€ __init__.py + β”‚ β”œβ”€β”€ scenario_service.py + β”‚ β”œβ”€β”€ cost_calculator.py + β”‚ └── ingest_processor.py + └── core/ + β”œβ”€β”€ config.py # Settings (DB URL, etc.) + └── database.py # DB connection/session + ``` + +3. **Aspettare** completamento schema DB prima di iniziare implementazione + +### Per @qa-engineer + +**Task:** Preparare test strategy + +1. **Creare** `docs/test_plan.md`: + ```markdown + # Test Plan mockupAWS v0.2.0 + + ## Unit Tests + - [ ] ScenarioService.create() + - [ ] ScenarioService.update_status() + - [ ] CostCalculator.calculate_sqs_cost() + - [ ] CostCalculator.calculate_lambda_cost() + - [ ] IngestProcessor.process_log() + + ## Integration Tests + - [ ] POST /api/v1/scenarios - Crea scenario + - [ ] GET /api/v1/scenarios - Lista scenari + - [ ] POST /ingest with X-Scenario-ID - Ingest log + - [ ] GET /api/v1/scenarios/{id}/metrics - Get metrics + - [ ] State transitions: draftβ†’runningβ†’completed + + ## E2E Tests (preparazione) + - [ ] Flow completo: Crea β†’ Ingest 10 log β†’ Verifica metriche + - [ ] Confronto costi: scenario A vs scenario B + ``` + +2. **Review** requisiti PRD per completezza test coverage + +### Per @frontend-dev (preparazione) + +**Task:** Preparare ambiente e mock data + +1. **Setup** struttura frontend: + ```bash + mkdir -p /home/google/Sources/LucaSacchiNet/mockupAWS/frontend + cd /home/google/Sources/LucaSacchiNet/mockupAWS/frontend + npm create vite@latest . -- --template react-ts + npm install + npm install tailwindcss postcss autoprefixer + npx tailwindcss init -p + npm install @tanstack/react-query axios recharts lucide-react + npm install -D @types/node + ``` + +2. **Preparare** mock data per sviluppo UI: + ```typescript + // mock/scenarios.ts + export const mockScenarios = [ + { + id: "uuid-1", + name: "Produzione Q2", + status: "running", + total_cost_estimate: 125.50, + total_requests: 15000, + created_at: "2026-04-01T10:00:00Z" + }, + // ... + ]; + ``` + +3. **Attendere** completamento API backend + +### Per @devops-engineer (preparazione) + +**Task:** Preparare Docker base + +1. **Creare** `docker-compose.yml` base: + ```yaml + version: '3.8' + services: + postgres: + image: postgres:15-alpine + environment: + POSTGRES_DB: mockupaws + POSTGRES_USER: app + POSTGRES_PASSWORD: changeme + volumes: + - postgres_data:/var/lib/postgresql/data + ports: + - "5432:5432" + + # backend e frontend da aggiungere dopo + + volumes: + postgres_data: + ``` + +2. **Preparare** `backend/Dockerfile`: + ```dockerfile + FROM python:3.11-slim + WORKDIR /app + COPY pyproject.toml . + RUN pip install uv && uv pip install -r pyproject.toml + COPY . . + CMD ["uv", "run", "uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000"] + ``` + +--- + +## πŸ“‹ Checklist Team + +### @spec-architect +- [ ] Leggere PRD completo +- [ ] Aggiornare architecture.md con dettagli DB e API +- [ ] Creare kanban.md con task Fase 1 +- [ ] Aggiornare progress.md + +### @db-engineer +- [ ] Progettare schema completo +- [ ] Setup Alembic +- [ ] Creare migrazioni +- [ ] Documentare schema + +### @backend-dev +- [ ] Analizzare codice esistente +- [ ] Preparare struttura nuova +- [ ] In attesa schema DB + +### @qa-engineer +- [ ] Creare test_plan.md +- [ ] Review requisiti + +### @frontend-dev +- [ ] Setup ambiente React +- [ ] Preparare mock data + +### @devops-engineer +- [ ] Creare docker-compose.yml base +- [ ] Preparare Dockerfile backend + +--- + +## 🎯 Success Criteria + +La Fase 1 Γ¨ completata quando: + +- [ ] Database PostgreSQL funzionante con tutte le tabelle +- [ ] Migrazioni Alembic funzionanti (upgrade/downgrade) +- [ ] API CRUD scenari complete e testate +- [ ] Endpoint `/ingest` aggiornato per persistere log +- [ ] Calcolo costi usando prezzi da database +- [ ] Test coverage > 80% +- [ ] Documentazione tecnica aggiornata + +--- + +## ⏰ Timeline Suggerita + +| Settimana | Focus | Deliverable | +|-----------|-------|-------------| +| Week 1 | Architettura + DB | Schema DB, migrazioni, architettura approvata | +| Week 2 | Backend API | CRUD scenari, persistenza, calcolo costi | +| Week 3 | Testing + Refinement | Test >80%, bug fixing, ottimizzazioni | +| Week 4 | Frontend base | Dashboard lista scenari, form creazione | + +--- + +## πŸ“ž Comunicazione + +- **Daily standup:** Aggiornare `export/progress.md` +- **Domande tecniche:** Documentare in `docs/architecture.md` +- **Blocchi:** Aggiungere a `export/kanban.md` colonna BLOCKED +- **Decisioni:** Sempre in Conventional Commits + +--- + +**Prompt creato:** 2026-04-07 +**Team Lead:** @spec-architect +**Stato:** Pronto per esecuzione + +--- + +## πŸš€ Prossima Azione Concreta + +**Tutti gli agenti coinvolti:** Leggete questo prompt e la vostra configurazione in `.opencode/agents/`, poi procedete con i task assegnati. + +**PrioritΓ  immediata:** +1. @spec-architect completa architecture.md +2. @db-engineer inizia schema DB +3. @backend-dev prepara struttura + +Iniziate ora! πŸ’ͺ diff --git a/prompt/prompt-zero.md b/prompt/prompt-zero.md index 886c6c8..cca021f 100644 --- a/prompt/prompt-zero.md +++ b/prompt/prompt-zero.md @@ -1,141 +1,216 @@ -# Prompt Zero: [NOME_PROGETTO] - Project Kickoff +# Prompt Zero: mockupAWS - Project Kickoff ## 🎯 Missione -Sviluppare **[NOME_PROGETTO]**, [descrizione breve del progetto - da personalizzare]. +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:** `[ROOT_PROGETTO]` -**PRD:** `[ROOT_PROGETTO]/export/prd.md` +**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 -- βœ… **Team Configurato**: Agenti specializzati pronti -- ❌ **Nessun Codice**: Progetto da zero -- ❌ **Nessuna Specifica Tecnica**: Da creare +- βœ… **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 | File Config | -|--------|-------|-------------| -| `@spec-architect` | Definisce specifiche e architettura | `.opencode/agents/spec-architect.md` | -| `@tdd-developer` | Implementazione TDD | `.opencode/agents/tdd-developer.md` | -| `@git-manager` | Gestione commit Git | `.opencode/agents/git-manager.md` | +| 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: SPECIFICA β”‚ -β”‚ @spec-architect β”‚ -β”‚ └── Legge PRD β†’ Crea architecture.md, kanban.md β”‚ -β”‚ β”‚ -β”‚ ↓ β”‚ -β”‚ β”‚ -β”‚ FASE 2: IMPLEMENTAZIONE β”‚ -β”‚ @tdd-developer β”‚ -β”‚ └── RED β†’ GREEN β†’ REFACTOR per ogni task β”‚ -β”‚ β”‚ -β”‚ ↓ β”‚ -β”‚ β”‚ -β”‚ FASE 3: COMMIT β”‚ -β”‚ @git-manager β”‚ -β”‚ └── Commit atomico + Conventional Commits β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ 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 - Specifica +## πŸš€ Task Iniziale: Fase 1 - Architettura e Database -**AGENTE:** `@spec-architect` +**AGENTE:** `@spec-architect` + `@db-engineer` -**OBIETTIVO:** Analizzare il PRD e creare le specifiche tecniche dettagliate. +**OBIETTIVO:** Completare le specifiche tecniche e creare il database schema. ### Azioni Richieste -1. **Leggere** `[ROOT_PROGETTO]/export/prd.md` +#### 1. @spec-architect - Analisi e Specifiche -2. **Creare** la struttura di output: - ``` - [ROOT_PROGETTO]/export/ - β”œβ”€β”€ prd.md # Requisiti prodotti (estratto/dettaglio) - β”œβ”€β”€ architecture.md # Architettura sistema - β”œβ”€β”€ kanban.md # Task breakdown - └── progress.md # Tracciamento progresso - ``` +1. **Leggere** `/home/google/Sources/LucaSacchiNet/mockupAWS/export/prd.md` -3. **Produrre** `architecture.md` con: - - Stack tecnologico dettagliato - - Struttura cartelle progetto - - Diagrammi flusso dati - - Schema database completo (DDL) - - Interfacce API (OpenAPI specs) - - Sicurezza (cifratura, autenticazione) +2. **Analizzare** il codice esistente in `/home/google/Sources/LucaSacchiNet/mockupAWS/src/` -4. **Produrre** `kanban.md` con: - - Task breakdown per Fase 1 (MVP) - - Stima complessitΓ  +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** `progress.md` con: - - Feature corrente: "Fase 1 - MVP" +5. **Inizializzare** `/home/google/Sources/LucaSacchiNet/mockupAWS/export/progress.md` con: + - Feature corrente: "Fase 1 - Database e Backend API" - Stato: "πŸ”΄ Pianificazione" - - Percentuale: 0% + - Percentuale: 10% -### Criteri di Accettazione +#### 2. @db-engineer - Schema Database -- [ ] Architecture.md completo con tutte le sezioni -- [ ] Kanban.md con task pronti per @tdd-developer -- [ ] Progress.md inizializzato -- [ ] Tutti i path usano `[ROOT_PROGETTO]/` +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) -### FunzionalitΓ  MVP (Fase 1) +### PrioritΓ  Alta (MVP v0.2.0) -[DA PERSONALIZZARE - Inserire le funzionalitΓ  principali del progetto] +1. **Database & Persistenza** + - PostgreSQL con tabelle scenarios, logs, metrics, pricing + - Alembic migrations + - Seed dati prezzi AWS reali -1. **[Feature 1]** - - [Dettaglio 1] - - [Dettaglio 2] +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 -2. **[Feature 2]** - - [Dettaglio 1] - - [Dettaglio 2] +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) -### Stack Tecnologico (Esempio) +4. **Testing** + - Test coverage > 80% + - Unit tests per services + - Integration tests per API -- **Backend:** [Linguaggio/Framework] -- **Database:** [Tipo database] -- **Frontend:** [Tecnologia frontend] -- **Auth:** [Metodo autenticazione] -- **Task Background:** [Scheduler] +### 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) -- [Requisito sicurezza 1] -- [Requisito sicurezza 2] -- SQL injection prevention -- XSS prevention +- SQL injection prevention (SQLAlchemy ORM) +- XSS prevention (React escaping) - CSRF protection -- Rate limiting +- Rate limiting (slowapi) +- Hashing messaggi per privacy +- No PII in logs persistenti ### QualitΓ  -- Test coverage β‰₯ 90% -- TDD obbligatorio +- Test coverage β‰₯ 80% +- TDD obbligatorio per backend +- Type hints obbligatori (Python + TypeScript) - Conventional commits - Commit atomici @@ -143,38 +218,62 @@ Sviluppare **[NOME_PROGETTO]**, [descrizione breve del progetto - da personalizz - Task "little often" (< 2 ore) - Documentazione in `/export/` - Bug complessi in `/docs/bug_ledger.md` +- PR con code review --- -## πŸ“ Struttura Progetto Attesa +## πŸ“ Struttura Progetto Finale ``` -[ROOT_PROGETTO]/ -β”œβ”€β”€ prd.md # Product Requirements +/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 -β”‚ └── skills/ # Skill condivise -β”œβ”€β”€ export/ # Output spec-driven (da creare) -β”‚ β”œβ”€β”€ prd.md -β”‚ β”œβ”€β”€ architecture.md -β”‚ β”œβ”€β”€ kanban.md -β”‚ └── progress.md -β”œβ”€β”€ docs/ # Documentazione (da creare) -β”‚ β”œβ”€β”€ bug_ledger.md -β”‚ └── architecture.md -β”œβ”€β”€ src/ # Codice sorgente (da creare) -β”‚ └── [nome_package]/ -β”‚ β”œβ”€β”€ __init__.py -β”‚ β”œβ”€β”€ main.py -β”‚ β”œβ”€β”€ config.py -β”‚ └── ... -β”œβ”€β”€ tests/ # Test suite (da creare) -β”‚ β”œβ”€β”€ unit/ -β”‚ β”œβ”€β”€ integration/ -β”‚ └── conftest.py -β”œβ”€β”€ requirements.txt / package.json +β”‚ └── 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 ``` @@ -182,43 +281,55 @@ Sviluppare **[NOME_PROGETTO]**, [descrizione breve del progetto - da personalizz ## βœ… Checklist Pre-Sviluppo -- [ ] @spec-architect ha letto questo prompt -- [ ] Cartella `export/` creata -- [ ] `architecture.md` creato con schema DB -- [ ] `kanban.md` creato con task Fase 1 -- [ ] `progress.md` inizializzato +- [ ] @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 in `export/prd.md` e crea le specifiche tecniche in `export/`. +**@spec-architect**: Inizia analizzando il PRD e il codice esistente, poi aggiorna `architecture.md` e `kanban.md`. -**NON iniziare l'implementazione** finchΓ© le specifiche non sono approvate. +**@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 +- **Task troppo grandi?** Spezza in task piΓΉ piccoli seguendo "little often" --- -**Data Creazione:** YYYY-MM-DD -**Versione:** 1.0 -**Stato:** Pronto per kickoff +**Data Creazione:** 2026-04-07 +**Versione:** 2.0 +**Stato:** Pronto per kickoff - Fase 1: Architettura e Database --- -## πŸ“ Note per l'Utente +## πŸ“ Note sullo Stato Attuale -Questo Γ¨ un template. Per usarlo: +Il progetto ha giΓ  una base solida con: +- API FastAPI funzionante con metriche base +- Test suite completa (pytest) +- Documentazione PRD dettagliata -1. **Sostituisci** `[NOME_PROGETTO]` con il nome reale -2. **Descrivi** il progetto nella sezione Missione -3. **Personalizza** la sezione "Requisiti Chiave" con i tuoi requisiti -4. **Aggiorna** lo stack tecnologico -5. **Definisci** gli scope dei commit pertinenti al tuo progetto +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