feat: initial project setup with scenarios, database and web ui

Add complete mockupAWS platform for AWS cost estimation: - FastAPI backend with scenario management - PostgreSQL database schema for scenarios, metrics, logs - AWS pricing table with real pricing data - React frontend dashboard (planned) - PII detection and token counting - Report generation (PDF/CSV) - Complete test suite with pytest - Docker Compose setup - Documentation: README, PRD, Architecture - OpenCode configuration (.opencode/)
2026-04-07 12:52:18 +02:00
parent b539134280
commit 59e5cf48f0
23 changed files with 2982 additions and 29 deletions
--- a/.opencode/AGENTS.md
+++ b/.opencode/AGENTS.md
@@ -0,0 +1,165 @@
+# AGENTS.md - Istruzioni per OpenCode
+
+## Contesto Progetto
+
+**mockupAWS** è un simulatore FastAPI per profilare traffico di log e calcolare costi AWS prima del deploy in produzione. Fa parte dell'ecosistema LogWhispererAI.
+
+### Scopo Principale
+- Non analizzare i log, ma **profilare il traffico e calcolare i driver di costo** AWS
+- Simulare comportamento di SQS, Lambda e Bedrock/LLM
+- Fornire stime di fatturazione basate su traffico simulato o reale
+
+## Principi Guida (DA RISPETTARE SEMPRE)
+
+### 1. Safety First
+- Validare sempre l'integrità del payload in ingresso
+- Verificare la sanitizzazione dei dati (assenza di PII/Secreti)
+- Controllare presenza di email (@ + .com) come indicatore di data leak
+
+### 2. Little Often  
+- Processamento a piccoli batch per simulare lettura ottimizzata dalle code
+- Task piccole e verificabili in <2 ore
+- Progresso incrementale
+
+### 3. Double Check
+- Validazione finale del prompt generato prima del calcolo costi
+- Conteggio token esatto con tokenizer cl100k_base
+- Verificare sempre i risultati delle stime
+
+## Workflow di Sviluppo
+
+### TDD (Test-Driven Development)
+1. **Scrivere il test PRIMA** della logica di implementazione
+2. Il test deve fallire inizialmente (Red)
+3. Implementare la logica minima per far passare il test (Green)
+4. Refactoring (Refactor)
+
+### Convenzioni Git
+- **Conventional Commits**: `feat:`, `fix:`, `chore:`, `test:`, `docs:`
+- Commit atomici e mirati
+- Un concetto = un commit
+
+### Struttura Messaggi Commit
+```
+<type>: <descrizione breve>
+
+[opzionale: corpo con dettagli]
+
+[opzionale: footer con riferimenti]
+```
+
+Esempi:
+- `feat: add token counting for Bedrock cost estimation`
+- `test: add SQS billing block calculation tests`
+- `fix: correct payload size calculation in profiler`
+
+## Metriche AWS Simulate
+
+### SQS (Simple Queue Service)
+- Blocco fatturazione: 64KB (65536 bytes)
+- Formula: `(payload_size_bytes // 65536) + 1`
+- Metrica: `sqs_billing_blocks`
+
+### Lambda
+- Simulazione invocazioni batch
+- Metrica: `lambda_simulated_invocations`
+
+### Bedrock/LLM
+- Tokenizer: `cl100k_base` (tiktoken)
+- Conteggio: `len(encoder.encode(text))`
+- Metrica: `llm_estimated_input_tokens`
+
+## Struttura File
+
+```
+mockupAWS/
+├── src/
+│   ├── main.py           # FastAPI app con endpoint /ingest, /metrics
+│   └── profiler.py       # Logica conteggio token e blocchi SQS
+├── test/
+│   └── test_ingest.py    # Test TDD per tutte le metriche
+├── export/               # File gestiti da agente @spec-architect
+│   ├── prd.md
+│   ├── architecture.md
+│   ├── kanban.md
+│   ├── progress.md
+│   └── githistory.md
+├── docs/
+│   ├── architecture.md   # Decisioni architetturali (ADR)
+│   └── bug_ledger.md
+└── pyproject.toml        # Dipendenze e configurazione uv
+```
+
+## Comandi Principali
+
+```bash
+# Installazione dipendenze
+uv sync
+
+# Avvio server di sviluppo
+uv run uvicorn src.main:app --reload
+
+# Esecuzione test
+uv run pytest
+
+# Test specifico
+uv run pytest test/test_ingest.py::test_sqs_billing_block_calculation -v
+```
+
+## Linee Guida Codice
+
+### Import
+```python
+# 1. Standard library
+import sys
+import time
+
+# 2. Third party
+import tiktoken
+from fastapi import FastAPI
+from pydantic import BaseModel
+
+# 3. Local modules
+from src.profiler import count_tokens, calculate_sqs_blocks
+```
+
+### Naming
+- Funzioni: `snake_case` (es. `count_tokens`, `calculate_sqs_blocks`)
+- Classi: `PascalCase` (es. `LogPayload`, `Metrics`)
+- Costanti: `UPPER_CASE`
+
+### Type Hints
+- Usare sempre type hints per parametri e return type
+- Usare Pydantic BaseModel per i payload
+
+## Gestione Errori
+
+- Validazione input con Pydantic
+- Non esporre dettagli interni negli errori HTTP
+- Loggare errori per debug in ambiente sviluppo
+
+## Testing
+
+### Fixture Disponibili
+- `reset_metrics`: Resetta i contatori prima di ogni test
+
+### Test Obbligatori per Nuove Feature
+1. Test endpoint risponde correttamente (200)
+2. Test calcolo metriche specifiche
+3. Test edge cases (payload vuoto, payload molto grande)
+4. Test validazione sicurezza (PII detection)
+
+## Domande da Porsi Prima di Modificare
+
+1. "Ho scritto il test prima dell'implementazione?"
+2. "Il mio codice rispetta il principio Safety First?"
+3. "Ho fatto Double Check sulle stime costi?"
+4. "Il commit segue le convenzioni?"
+5. "Ho verificato che non esponiamo PII nei log?"
+
+## Riferimenti
+
+- FastAPI Docs: https://fastapi.tiangolo.com
+- Tiktoken: https://github.com/openai/tiktoken
+- AWS SQS Pricing: https://aws.amazon.com/sqs/pricing/
+- Conventional Commits: https://www.conventionalcommits.org
--- a/.opencode/opencode.json
+++ b/.opencode/opencode.json
@@ -0,0 +1,99 @@
+{
+  "project": {
+    "name": "mockupAWS",
+    "description": "Simulatore locale del backend AWS per LogWhispererAI - Profiler e Cost Estimator",
+    "type": "python-fastapi",
+    "version": "0.1.0"
+  },
+  "language": "it",
+  "tech_stack": {
+    "framework": "FastAPI",
+    "python_version": ">=3.11",
+    "key_dependencies": [
+      "fastapi>=0.110.0",
+      "pydantic>=2.7.0",
+      "tiktoken>=0.6.0",
+      "uvicorn>=0.29.0"
+    ],
+    "dev_dependencies": [
+      "pytest>=8.1.1",
+      "httpx>=0.27.0"
+    ],
+    "package_manager": "uv"
+  },
+  "architecture": {
+    "pattern": "layered",
+    "principles": [
+      "Safety First - Validazione integrità payload e sanitizzazione dati",
+      "Little Often - Processamento a piccoli batch",
+      "Double Check - Validazione finale prompt prima calcolo costi"
+    ],
+    "components": [
+      {
+        "name": "Ingestion API",
+        "path": "src/main.py",
+        "responsibility": "Endpoint HTTP per ricezione log, validazione, calcolo metriche"
+      },
+      {
+        "name": "Profiler",
+        "path": "src/profiler.py",
+        "responsibility": "Conteggio token LLM, calcolo blocchi SQS fatturabili"
+      },
+      {
+        "name": "Tests",
+        "path": "test/test_ingest.py",
+        "responsibility": "Test TDD per metriche, validazione payload, token count"
+      }
+    ]
+  },
+  "development": {
+    "methodology": "TDD",
+    "workflow": "Spec-Driven",
+    "commit_style": "Conventional Commits",
+    "git_strategy": "feature-branch"
+  },
+  "conventions": {
+    "code_style": "PEP8",
+    "naming": {
+      "functions": "snake_case",
+      "classes": "PascalCase",
+      "constants": "UPPER_CASE"
+    },
+    "imports": [
+      "Importare sempre prima le librerie standard",
+      "Poi le librerie di terze parti",
+      "Infine i moduli locali"
+    ]
+  },
+  "aws_simulation": {
+    "services": [
+      {
+        "name": "SQS",
+        "billing_block_size": "64KB (65536 bytes)",
+        "metric": "sqs_billing_blocks"
+      },
+      {
+        "name": "Lambda",
+        "metric": "lambda_simulated_invocations"
+      },
+      {
+        "name": "Bedrock/LLM",
+        "tokenizer": "cl100k_base",
+        "metric": "llm_estimated_input_tokens"
+      }
+    ]
+  },
+  "export_files": {
+    "prd": "export/prd.md",
+    "architecture": "export/architecture.md",
+    "kanban": "export/kanban.md",
+    "progress": "export/progress.md",
+    "githistory": "export/githistory.md"
+  },
+  "commands": {
+    "install": "uv sync",
+    "run": "uv run uvicorn src.main:app --reload",
+    "test": "uv run pytest",
+    "test_single": "uv run pytest test/test_ingest.py::test_name -v"
+  }
+}