c0bf7b6c15
- CLAUDE.md: TZ, SSO, vault-steward, versioning, persona v2.0, multitenant, KB RAG - docs/standards: persona-conversational-rules v2.0 - docs/STANDARD_*: installer-integration, email-relay, AI-prodotto, marketing-tenant, multitenant - AGENT_CHANGES.md + OPEN_TICKETS.md (registri agent automatico) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
161 lines
6.7 KiB
Markdown
161 lines
6.7 KiB
Markdown
# STANDARD AgileHub: multitenant-architecture v1.0
|
||
|
||
> **Codename progetto**: NAVIGAI (Navigare nell'AI)
|
||
> **Status**: `proposed`
|
||
> **Applies to**: `*` (tutta la suite — 11 prodotti)
|
||
> **Owner**: REGENT (coordinamento) + TITAN (backend) + VIGILE (audit) + Agile AI (KB master) + PRISMA (UI master/tenant)
|
||
> **Date**: 2026-05-17
|
||
> **Public facing**: AgileHub (NAVIGAI è il codename interno, invisibile al cliente)
|
||
|
||
---
|
||
|
||
## 1. Scopo
|
||
|
||
Definire l'architettura multitenant esplicita di AgileHub con un livello master condiviso, tenant client isolati, catalogo cross-tenant condivisibile, billing per-tenant e governance centralizzata.
|
||
|
||
## 2. Tassonomia tenant
|
||
|
||
| Tipo | Esempio | id | is_master | tier | parent_tenant_id |
|
||
|---|---|---|---|---|---|
|
||
| **Master** | AgileHub | 1 | TRUE | `master` | NULL |
|
||
| Client enterprise | Work Group s.r.l. | N | FALSE | `enterprise` | 1 |
|
||
| Client professional | Studio Tremolada | N | FALSE | `professional` | 1 |
|
||
| Client trial | sandbox | N | FALSE | `trial` | 1 |
|
||
| Sandbox interno | Agile Technology test | N | FALSE | `trial` | 1 |
|
||
|
||
## 3. Visibility ENUM cross-tabella
|
||
|
||
Ogni record sensibile (KB articles, personas, workflow templates, routing rules, RAG repositories) ha colonna `visibility ENUM('global','shared','tenant','team','private')`.
|
||
|
||
| Valore | Significato | Lettura da |
|
||
|---|---|---|
|
||
| `global` | Master AgileHub catalog, riusabile read-only da tutti i tenant | tutti |
|
||
| `shared` | Visibile a tenant + i suoi sotto-tenant | tenant + figli |
|
||
| `tenant` | Solo tenant proprietario | tenant |
|
||
| `team` | Team specifico dentro un tenant | team members |
|
||
| `private` | Singolo utente | owner_user_id |
|
||
|
||
## 4. Opt-out granulare
|
||
|
||
Tabella `nexus_tenant_db.tenant_global_exclusions(tenant_id, resource_type, resource_id, exclusion_reason)` permette al client di dichiarare "non voglio usare quell'articolo KB master/quella persona master/quella regola routing master".
|
||
|
||
## 5. JWT additivi (no breaking)
|
||
|
||
Claims aggiunti (additive, retro-compat):
|
||
- `tenant_id BIGINT`
|
||
- `tenant_slug VARCHAR(64)`
|
||
- `is_master TINYINT(1)`
|
||
- `permitted_tenant_ids INT[]` (per is_master users che possono switchare contesto)
|
||
|
||
Vecchi JWT senza nuovi claim restano validi → tenant_id desunto via fallback `tenants.email → user → tenant_membership`.
|
||
|
||
## 6. Shared library
|
||
|
||
Pacchetto npm interno `@agile/tenant-auth` (Node) + `agile_tenant_auth` (Python) fornisce:
|
||
- `extractTenantContext(req)` → `{ tenant_id, tenant_slug, is_master, user_id }`
|
||
- `requireSameTenant(req, resourceTenantId)` → throws 403 se mismatch
|
||
- `requireMaster(req)` → throws 403 se !is_master
|
||
- `withTenantFilter(query)` → injects `WHERE (tenant_id = X OR visibility = 'global')`
|
||
|
||
## 7. Vault namespace tenant-aware
|
||
|
||
Pattern: `tier1__<ms>__<tenant_slug>__<feature>`
|
||
|
||
Esempi:
|
||
- `tier1__nexus-marketing-ms__work_group_001__mailgun_api_key`
|
||
- `tier1__nexus-presenter-ms__agilehub_master__tavus_api_key`
|
||
|
||
Compatibility: namespace senza `<tenant_slug>` restano validi per master.
|
||
|
||
## 8. Audit log HMAC chain
|
||
|
||
JSONL append-only in `docs/multitenant-audit/YYYY-MM-WNN.jsonl` con catena HMAC-SHA256 (ogni entry contiene SHA del precedente). Genesis entry firmata da TITAN al kickoff SG-0.
|
||
|
||
## 9. Distributed tracing
|
||
|
||
Header `X-Trace-Id` propagato cross-MS in tutti i call HTTP/Redis Streams. Generato in API gateway Apache se assente. Pino structured log + Loki backend.
|
||
|
||
## 10. Status page tenant-aware
|
||
|
||
`/status` Next.js mostra SLA + uptime + latency p99 **per-tenant** (con auth). SLA differenziato per tier:
|
||
- master: 99.99%
|
||
- enterprise: 99.95%
|
||
- professional: 99.9%
|
||
- trial: 99%
|
||
|
||
## 11. Canary deploy
|
||
|
||
Apache `mod_proxy_balancer` rolling 5% → 50% → 100% con auto-rollback se error rate > 2% per 5 min.
|
||
|
||
## 12. Billing per-tenant
|
||
|
||
Tabella `nexus_hub.hub_cost_events(tenant_id, ms, event_type, cost_eur_micros, ts)` con 8 hook nei MS:
|
||
- nexus-ai-ms (tokens LLM Anthropic + Voyage embedding)
|
||
- nexus-marketing-ms (email sends via Mailgun)
|
||
- nexus-call-ms (Twilio minutes)
|
||
- nexus-presenter-ms (Tavus session-minutes + LiveKit)
|
||
- nexus-voice-ms (Deepgram STT + ElevenLabs TTS)
|
||
- nexus-rag-ms (Voyage embed/rerank + storage GB)
|
||
- nexus-hub-ms (server time)
|
||
- agilehub-workflow-engine (Haiku suggester tokens)
|
||
|
||
Export mensile CSV/PDF (showback) per cliente.
|
||
|
||
## 13. Compliance
|
||
|
||
- **GDPR Art.32**: encryption at rest+transit, access controls, audit trail, business continuity, periodic testing — tutti documentati in `docs/COMPLIANCE_GDPR_ART32.md`
|
||
- **ISO A.18.1.5** readiness: gap analysis NON certificazione formale
|
||
- **Retention fiscale IT**: 10 anni per `hub_cost_events` (NON 7)
|
||
- **GDPR Art.17 erasure**: cascade già implementato in nexus-rag-ms (estendere ai 13 MS)
|
||
|
||
## 14. Pen test esterno
|
||
|
||
STRIDE 13×6 matrix (13 MS × 6 categorie) eseguita da vendor EU certificato durante SG-5. Budget €15K una tantum. Vendor RFP da VIGILE.
|
||
|
||
## 15. Roadmap distribution
|
||
|
||
| Wave | Prodotti | Trigger |
|
||
|---|---|---|
|
||
| **Reference** | AGILEHUB | SG-0 in progress |
|
||
| **Wave 1 (P1)** | TRPG, SUSTAINAI, NIS2, DFM | SG-4 GREEN |
|
||
| **Wave 2 (P2)** | TAXAI, LG231, MKTG, ALLRISK, WMS, MADEBYCLOUD, CERTISOURCE | post smoke Wave 1 |
|
||
|
||
Distribution via INSTALLATORE pattern: docs_file scp + claude_md append + claude memory write nei 11 container DevEnv prodotto + `hub_standards_adoption` row per ogni prodotto (status `pending → acknowledged → implemented`).
|
||
|
||
## 16. NESSUN out-of-scope (v1.0)
|
||
|
||
Documentato esplicitamente FUORI da v1.0:
|
||
- Multi-region failover (Hetzner Helsinki + EU secondary)
|
||
- Self-service tenant signup pubblico con CC payment
|
||
- Multi-currency (solo EUR)
|
||
- SAML/OIDC federation
|
||
- Tenant white-label dominio custom (solo subdomain `{slug}.agilehub.it`)
|
||
- Audit log immutabile blockchain
|
||
- ISO 27001 / SOC 2 certification formale
|
||
|
||
---
|
||
|
||
## Adoption tracker (status iniziale)
|
||
|
||
| Prodotto | docs_file | claude_md | claude_memory | adoption_status |
|
||
|---|---|---|---|---|
|
||
| AGILEHUB | ✓ pending SG-0 | pending | pending | `proposed` |
|
||
| TRPG | pending | pending | pending | `pending` |
|
||
| SUSTAINAI | pending | pending | pending | `pending` |
|
||
| NIS2 | pending | pending | pending | `pending` |
|
||
| TAXAI | pending | pending | pending | `pending` |
|
||
| LG231 | pending | pending | pending | `pending` |
|
||
| DFM | pending | pending | pending | `pending` |
|
||
| MKTG | pending | pending | pending | `pending` |
|
||
| ALLRISK | pending | pending | pending | `pending` |
|
||
| WMS | pending | pending | pending | `pending` |
|
||
| MADEBYCLOUD | pending | pending | pending | `pending` |
|
||
| CERTISOURCE | pending | pending | pending | `pending` |
|
||
|
||
## Riferimenti
|
||
|
||
- [NAVIGAI_EXECUTIVE_BRIEF.md](NAVIGAI_EXECUTIVE_BRIEF.md)
|
||
- [NAVIGAI_ARCHITETTURA_TECNICA.md](NAVIGAI_ARCHITETTURA_TECNICA.md)
|
||
- [NAVIGAI_ROADMAP_OPERATIVA.md](NAVIGAI_ROADMAP_OPERATIVA.md)
|
||
- [PLAN_MULTITENANT_MASTER_REFACTOR_V11.md](PLAN_MULTITENANT_MASTER_REFACTOR_V11.md) (920 righe production-ready)
|