| name | siae-architecture |
| description | Use when evaluating, choosing, or analyzing architectural patterns for an existing or new system. Analizza architettura di sistemi software: C4 model, HLD, bounded context, CQRS, event-driven, microservizi vs monolite, resilienza, accoppiamento tra servizi. Trigger: VALUTARE, SCEGLIERE, ANALIZZARE pattern architetturali. **Best after**: siae-brainstorming Step 4 (options proposed) — questa skill è specialistica per deepen architectural choice già scoperto. Examples: "valutiamo CQRS", "microservizi o monolite?", "crea il C4", "definisci i bounded context", "HLD per il sistema X".
|
╔══════════════════════════════════════════════════════════════════╗
║ ███████╗██╗ █████╗ ███████╗ ██████╗ ███████╗██╗ ██╗ ║
║ ██╔════╝██║██╔══██╗██╔════╝ ██╔══██╗██╔════╝██║ ██║ ║
║ ███████╗██║███████║█████╗ ██║ ██║█████╗ ██║ ██║ ║
║ ╚════██║██║██╔══██║██╔══╝ ██║ ██║██╔══╝ ╚██╗ ██╔╝ ║
║ ███████║██║██║ ██║███████╗ ██████╔╝███████╗ ╚████╔╝ ║
║ ╚══════╝╚═╝╚═╝ ╚═╝╚══════╝ ╚═════╝ ╚══════╝ ╚═══╝ ║
║ 🔨 DevForge · Architecture ║
╚══════════════════════════════════════════════════════════════════╝
Tipo: Flexible | Fase SDLC: 2. Design
📊 Dai repo itsiae: I servizi progettati senza C4 diagram hanno 2.3x piu' richieste di chiarimento durante l'onboarding di nuovi developer.
Fonte: analisi dei repository GitHub dell'org itsiae.
1. Modello C4
Il modello C4 (Context, Container, Component, Code) e' lo standard per documentare architetture in SIAE.
Ogni livello aggiunge dettaglio progressivo; usa il livello minimo necessario per la decisione in corso.
| Livello | Nome | Cosa mostra | Quando usarlo |
|---|
| 1 | Context | Sistema + attori esterni + sistemi adiacenti | Kickoff progetto, allineamento stakeholder |
| 2 | Container | Applicazioni, DB, message broker, deployment unit | Design di alto livello (HLD), review architetturale |
| 3 | Component | Moduli interni di un singolo container | Design dettagliato, code review di modulo |
| 4 | Code | Classi, interfacce, strutture dati | Documentazione tecnica, onboarding sviluppatori |
Riferimento template PlantUML: reference/c4-template.md
2. Pattern Architetturali SIAE
Tutti i pattern seguenti sono estratti da repo reali dell'organizzazione itsiae.
Non proporre pattern non presenti in questo catalogo.
2.1 Microservizi Java
| Aspetto | Dettaglio |
|---|
| Runtime | Spring Boot 3.x su OpenShift (container OCI) |
| Build | Maven con parent POM custom SIAE (siae-parent) |
| Packaging | Helm chart per deploy su OpenShift |
| API | REST (OpenAPI 3.0), versionamento via URL path (/v1/) |
| Persistenza | PostgreSQL (RDS) o Oracle, JPA/Hibernate |
| Osservabilita' | Micrometer + Prometheus, log JSON strutturato |
| CI/CD | GitHub Actions -> build Maven -> push image -> Helm upgrade |
Quando sceglierlo: servizi con logica di dominio complessa, requisiti di transazionalita', integrazione con sistemi legacy SIAE.
2.2 Serverless TypeScript
| Aspetto | Dettaglio |
|---|
| Runtime | Node.js 20.x su AWS Lambda |
| Framework | Express.js + serverless-http adapter |
| Build | esbuild (bundle + minify + tree-shaking) |
| API | API Gateway (REST o HTTP API) + Lambda proxy |
| Persistenza | Drizzle ORM + PostgreSQL (RDS) oppure DynamoDB |
| IaC | Terragrunt (vedi pattern 2.4) |
| CI/CD | GitHub Actions -> esbuild -> zip -> deploy Lambda |
Quando sceglierlo: API leggere, webhook handler, BFF per frontend, servizi event-driven con carico variabile.
2.3 Data Pipeline Python
| Aspetto | Dettaglio |
|---|
| Architettura | Medallion Architecture (bronze -> silver) |
| Runtime | AWS Glue 4.0 (PySpark), Python 3.11 |
| Orchestrazione | AWS Step Functions (state machine JSON/ASL) |
| Trigger | Amazon EventBridge (schedule o event pattern) |
| Storage | S3 (datalake con prefissi bronze/ silver/), Parquet |
| Catalogo | AWS Glue Data Catalog + Athena per query ad-hoc |
| CI/CD | GitHub Actions -> upload script S3 -> update Glue job |
Quando sceglierlo: ingestione dati da sorgenti esterne, trasformazioni batch, alimentazione datawarehouse, reportistica.
2.4 IaC Pattern (Terragrunt)
| Aspetto | Dettaglio |
|---|
| Tool | Terragrunt + Terraform |
| Struttura | live/ (ambienti) + modules/ (moduli riusabili), mirror |
| Configurazione | config.yaml per ambiente, iniettato via read_terragrunt_config() |
| State | S3 bucket + DynamoDB table per locking |
| Ambienti | live/dev/, live/uat/, live/prod/ |
| CI/CD | GitHub Actions con OIDC federation (no secret statiche) |
Quando sceglierlo: qualsiasi infrastruttura AWS nuova. Sempre. Non usare CloudFormation o CDK.
2.5 Frontend SPA
| Aspetto | Dettaglio |
|---|
| Framework | Vue.js 3 (Composition API) + Pinia (state management) |
| UI Library | PrimeVue (componenti + tema SIAE custom) |
| Build | Vite |
| Hosting | S3 (static) + CloudFront (CDN + HTTPS) |
| Config | Firebase Remote Config (feature flags, parametri runtime) |
| Auth | Amazon Cognito (OAuth2/OIDC) |
| CI/CD | GitHub Actions -> npm build -> sync S3 -> invalidate CF |
Quando sceglierlo: applicazioni web interne SIAE, portali, dashboard, backoffice.
3. AWS Service Map SIAE
Servizi AWS approvati e in uso nei repository SIAE.
| Categoria | Servizi |
|---|
| Compute | Lambda, Glue (PySpark), OpenShift (self-managed su EC2) |
| Storage | S3, DynamoDB, PostgreSQL (RDS), Oracle (RDS) |
| Messaging | SNS, SQS, EventBridge |
| Security | Cognito, KMS, Secrets Manager, IAM OIDC (GitHub Actions) |
| CDN | CloudFront |
| Monitoring | CloudWatch (Logs, Metrics, Alarms) |
| Data | Glue Data Catalog, Athena |
Riferimento dettagliato con diagrammi: reference/aws-patterns.md
4. Vincoli
| 🔴 ALTO (difficile da annullare) — 🔨 DevForge · siae-architecture |
|---|
| ⚠️ WARNING |
🏗️ Contesto: Modifica architettura sistema esistente in produzione SIAE |
| ▼ Azione |
1. ⚠️ Modifica architettura → sistema esistente |
| 💡 Perche': Modificare architettura esistente impatta sistemi dipendenti, integrations e contratti API. |
| 🚫 Se NO: La modifica non viene applicata. Documentare la decisione come ADR con stato Rejected. |
⏸️ ATTENDI CONFERMA ESPLICITA — mostra la card e NON eseguire finché l'utente
risponde esplicitamente ("sì, procedi" / "no, annulla"). Silenzio ≠ consenso.
- Solo pattern reali — non proporre architetture non presenti nel catalogo (sezione 2).
Ogni design deve mappare su uno o piu' dei 5 pattern documentati.
- IaC obbligatoria — ogni risorsa AWS va gestita con Terragrunt (pattern 2.4).
- C4 obbligatorio — ogni HLD deve includere almeno Livello 1 (Context) e Livello 2 (Container).
- Servizi approvati — usare solo i servizi nella AWS Service Map (sezione 3).
Per servizi non in lista, richiedere approvazione esplicita.
| 🟡 MEDIO (reversibile) — 🔨 DevForge · siae-architecture |
|---|
🏗️ Contesto: Selezione libreria o dipendenza esterna per progetto SIAE |
| ▼ Azione |
1. 📦 Aggiunta dipendenza → pom.xml / package.json / requirements.txt |
| 💡 Perche': Librerie esterne introducono rischi di licenza, CVE e debito tecnico. |
| 🚫 Se NO: Non aggiungere la dipendenza. Rivalutare se esiste un servizio AWS o modulo interno equivalente. |
- Diagrammi in PlantUML — tutti i diagrammi architetturali devono essere in sintassi PlantUML.
Nei documenti Markdown: blocchi
```plantuml inline. Per rendering standalone: file .puml in docs/diagrams/.
MAI usare Mermaid. MAI usare ASCII art.
| 🟡 MEDIO (reversibile) — 🔨 DevForge · siae-architecture |
|---|
🏗️ Contesto: Pubblicazione ADR su Confluence per decisione architetturale SIAE |
| ▼ Azione |
1. 📄 Pubblicazione ADR → Confluence / docs/architecture/ |
| 💡 Perche': Un ADR pubblicato e' un artefatto ufficiale che impatta tutti i team. |
| 🚫 Se NO: L ADR rimane in stato Draft locale. Richiedere revisione al tech lead prima di procedere. |
Limiti Operativi
| Vincolo | Limite | Se superato |
|---|
| Tentativi fix per errore | 2 | Fermati. Diagnosi diversa necessaria. |
| File modificati per singolo step | 5 | Se devi toccare piu' file, decomponi in sub-task. |
| Output max per raccomandazione | 200 righe | Prioritizza. Top 5 issue, non lista esaustiva. |
REQUIRED SUB-SKILL: siae-verification
Invoca siae-verification prima di dichiarare il design architetturale completo.
Tabella Anti-Razionalizzazione
| Pensiero | Realta' |
|---|
| "Abbiamo gia' un pattern uguale altrove" | Il contesto cambia. Il pattern va validato per questo caso. |
| "E' solo un CRUD, non serve architettura" | I CRUD diventano complessi. L'ADR previene il debito tecnico. |
| "Lo decidiamo durante l'implementazione" | Le decisioni architetturali in corso d'opera costano di piu'. |
| "Il team conosce gia' il sistema" | La conoscenza tacita non scala. Documentala. |
| "Aggiorniamo l'ADR dopo il rilascio" | Dopo il rilascio non si aggiorna mai. |
| "Non abbiamo tempo per HLD" | Il tempo risparmiato ora viene perso nel refactoring. |
| "L'architettura e' ovvia" | Ovvia per te. Non per chi entra nel team dopo. |
Classificazione Rischio Operazioni
| Operazione | Livello | Card |
|---|
| Analisi requisiti non funzionali | 🟢 Sicuro | No |
| Proposta pattern architetturale | 🟢 Sicuro | No |
| Confronto trade-off tra opzioni | 🟢 Sicuro | No |
| Scrittura ADR in docs/architecture/ | 🟢 Sicuro | No |
| Scelta librerie/dipendenze esterne | 🟡 Medio | Si |
| Pubblicazione ADR su Confluence | 🟡 Medio | Si |
| Modifica architettura di sistema esistente | 🔴 Alto | Si |
