nis2-agile/docs/STANDARD_MULTITENANT_ARCHITECTURE.md

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_ARCHITETTURA_TECNICA.md
• NAVIGAI_ROADMAP_OPERATIVA.md
• PLAN_MULTITENANT_MASTER_REFACTOR_V11.md (920 righe production-ready)