Multi-tenant SaaS Platform · Architettura a 4 livelli · AI-native

Una piattaforma.
Quattro livelli di scala.

Joshua Cloud è una piattaforma SaaS multi-tenant costruita su una gerarchia a quattro livelli, isolamento dati nativo a livello database, e un gateway AI integrato che porta modelli di linguaggio dentro ogni flusso operativo.

Contattaci Esplora l'architettura

Livelli gerarchia

L4 → L1

Isolamento dati

RLS

postgresql nativo

Provider AI

via forge_ai gateway

Disponibilità target

99,9%

SLA infrastruttura

Architettura a livelli · 01 / 05

Quattro livelli gerarchici

La piattaforma è organizzata in quattro livelli concentrici. Ogni livello eredita capacità dal superiore e mantiene autonomia operativa sui propri sotto-livelli, con isolamento dati garantito a livello database.

L4Centrale

Forge Central

Operatore piattaforma

Controllo globale dell'infrastruttura, provisioning dei reseller, configurazione delle policy, monitoraggio e tracking dei costi AI.

L3Reseller

Reseller / Gruppo

Distributore

Gestisce un parco di studi L2, applica il proprio branding e listini, definisce limiti operativi e accesso alle funzionalità AI.

L2Studio

Studio / Professionista

Utente principale

Lavora quotidianamente sulla piattaforma per i propri clienti L1, gestisce utenti dello studio, configura template e knowledge base interna.

L1Cliente

Cliente finale

Accesso autoservizio

L'azienda o entità servita dallo studio L2. Vede solo i propri dati, con permessi configurabili dal proprio L2 di riferimento.

Gerarchia di provisioning

Ogni livello superiore istanzia e configura i livelli inferiori. La visibilità dei dati segue rigorosamente questa gerarchia.

flowchart TB L4["L4 · Forge Central
Operatore piattaforma"] L3a["L3 · Reseller A"] L3b["L3 · Reseller B"] L2a["L2 · Studio A1"] L2b["L2 · Studio A2"] L2c["L2 · Studio B1"] L1a["L1 · Cliente A1.1"] L1b["L1 · Cliente A1.2"] L1c["L1 · Cliente A2.1"] L1d["L1 · Cliente B1.1"] L1e["L1 · Cliente B1.2"] L4 --> L3a L4 --> L3b L3a --> L2a L3a --> L2b L3b --> L2c L2a --> L1a L2a --> L1b L2b --> L1c L2c --> L1d L2c --> L1e

Provisioning dall'alto verso il basso · isolamento dati ortogonale alla gerarchia · single sign-on con scope per livello.

Comunicazione tra livelli · 02 / 05

Come scorrono i dati

Tutte le richieste passano attraverso un singolo backend FastAPI che applica autenticazione, scope per livello e policy di isolamento prima di toccare il database. Nessun servizio aggira il gateway.

Autenticazione & scope

Login emette un token con livello (L1-L4) e ID gerarchia. Ogni richiesta porta lo scope. Il backend rifiuta tutto ciò che esce dallo scope dichiarato.

Set di sessione DB

All'inizio della richiesta il backend imposta le variabili di sessione PostgreSQL (livello, studio, ruolo). Le policy RLS le leggono e filtrano automaticamente.

Query con isolamento

Ogni SELECT/INSERT/UPDATE passa attraverso Row-Level Security. Un L2 non vede mai dati di un altro L2, nemmeno per bug applicativo.

Reverse proxy

Cloudflare Tunnel + Nginx interno terminano TLS, applicano rate limit e instradano verso il backend. Nessuna porta esposta in chiaro.

Bypass controllato

Per task di sistema (logging, batch) un ruolo dedicato attiva temporaneamente policy di bypass; mai accessibile dal frontend o da utenti reali.

Audit trail

Ogni operazione lascia traccia su tabelle dedicate con utente, livello, IP, timestamp. Le tracce non sono modificabili dall'applicazione.

Flusso di una richiesta

Dall'utente al database, attraverso autenticazione, scope, RLS e audit.

sequenceDiagram autonumber participant U as Utente L2 participant CF as Cloudflare participant NG as Nginx participant API as Backend FastAPI participant DB as PostgreSQL + RLS participant AU as Audit Log U->>CF: HTTPS request + JWT CF->>NG: forward (mTLS) NG->>API: route + rate limit API->>API: validate JWT (livello, scope) API->>DB: SET LOCAL session vars API->>DB: SELECT ... (con RLS attivo) DB-->>API: solo dati nello scope API->>AU: log operazione API-->>U: response (JSON)

Integrazione AI · 03 / 05

AI nativa, non bolt-on

Joshua Cloud incorpora un gateway AI (forge_ai) che unifica accesso a cinque provider e mette a disposizione di ogni livello operazioni di linguaggio naturale, output strutturato e knowledge base con isolamento per studio.

CHAT

Conversazione contestuale

Ogni livello dialoga con un assistente che conosce il proprio scope. L2 vede solo i propri studi, L1 solo la propria realtà.

RAG

Knowledge base per studio

Documenti caricati da un L2 vengono indicizzati in una KB privata, con embeddings pgvector e re-indicizzazione automatica.

STRUCT

Output strutturato

Estrazione di dati da documenti con schema garantito (Pydantic). I modelli Gemini e OpenAI rispondono direttamente in JSON validato.

ROUTE

Routing intelligente

Task semplici vengono instradati su modelli economici, ragionamenti complessi su modelli frontier. Costo medio ridotto del 60–80%.

LOCAL

Modalità on-premise

Per dati ad alta sensibilità è disponibile Ollama locale: nessun byte lascia l'infrastruttura, GDPR-friendly per default.

TRACK

Tracking costi per livello

Ogni chiamata AI è tracciata per livello, studio e modello. I costi possono essere ribaltati o limitati per piano commerciale.

Gateway AI · architettura logica

forge_ai siede tra l'applicazione e i provider, applicando scope, routing e tracking.

flowchart LR subgraph APP["Joshua Cloud · Backend"] BE["FastAPI app"] end subgraph FORGE["forge_ai · Gateway"] ROUTE["Router
per task & costo"] CTX["Scope context
livello + studio"] CACHE["Cache
semantic + exact"] KB["Knowledge Base
pgvector"] TRACK["Cost tracking
per livello"] end subgraph PROV["LLM Providers"] P1["OpenAI"] P2["Anthropic"] P3["Gemini"] P4["Vertex"] P5["Ollama on-prem"] end BE --> CTX CTX --> ROUTE ROUTE --> CACHE CACHE --> P1 CACHE --> P2 CACHE --> P3 CACHE --> P4 CACHE --> P5 BE -.-> KB ROUTE --> TRACK

Il context di scope è iniettato a ogni chiamata · KB partizionata per studio · cache invalidata su update KB.

Sicurezza & isolamento · 04 / 05

Isolamento a livello database

La separazione fra tenant non è solo applicativa: è imposta da PostgreSQL Row-Level Security con policy FORCE che resistono anche a bug del codice. Combinata con backup cifrati, audit trail e protezione perimetrale.

PostgreSQL RLS forzato

Database

Policy di Row-Level Security applicate con FORCE su tutte le tabelle multi-tenant. Anche una query senza WHERE filtra automaticamente per scope. Nessun bypass possibile dall'applicazione standard.

Ruoli con privilegi minimi

Auth

Il backend si connette con un ruolo applicativo limitato. Operazioni privilegiate richiedono escalation esplicita verso un ruolo dedicato, tracciato e con scope ristretto.

Edge protection

Network

Cloudflare in front: WAF, rate limiting, mitigazione DDoS, certificati gestiti. Origin raggiungibile solo via tunnel autenticato; nessuna porta esposta su Internet.

Backup cifrati e versionati

Recovery

Backup orari incrementali su storage offsite cifrato (Hetzner Borg) con ritenzione 30 giorni, più copia locale su disco dedicato. Verifica integrità automatica.

Audit log immutabile

Compliance

Ogni modifica significativa viene registrata su tabelle solo-append con utente, livello, IP, timestamp e diff. Esportabile per audit esterni.

Segregazione AI

AI scope

Le chiamate AI ereditano lo scope del chiamante. Una knowledge base di uno studio non è interrogabile da un altro, neppure forgiando manualmente l'ID.

Matrice di isolamento

Cosa è visibile a chi, garantito dal database.

Risorsa visibile	L4	L3	L2	L1
Tutta la piattaforma	●	—	—	—
Solo il proprio reseller	●	●	—	—
Solo il proprio studio	●	●	●	—
Solo i propri dati	●	●	●	●
Audit log globale	●	—	—	—
Audit log proprio scope	●	●	●	—

Stack tecnologico · 05 / 05

Stack tecnologico

Tecnologie scelte per stabilità, scalabilità e mantenibilità a lungo termine. Niente framework esotici, nessuna dipendenza da servizi proprietari di un singolo vendor.

Backend

Python 3.12 FastAPI SQLAlchemy 2 async Pydantic v2 Alembic httpx

Frontend

Vue 3 Vite TypeScript Tailwind CSS Pinia

Database

PostgreSQL 16 RLS + FORCE pgvector PgBouncer

AI gateway

forge_ai OpenAI Anthropic Gemini Vertex AI Ollama

Edge & deploy

Cloudflare Tunnel Nginx systemd Docker

Osservabilità & backup

Hetzner Borg Audit log SQL Telegram alerts USB local backup

Principi architetturali

Le regole non negoziabili che guidano ogni scelta tecnica.

Principio	Implementazione
Isolamento dati	PostgreSQL RLS con FORCE su ogni tabella multi-tenant
Stateless backend	Sessione utente in JWT, scaling orizzontale immediato
AI come libreria, non SaaS	forge_ai integrato, nessuna dipendenza da gateway esterni
Backup verificati	Borg cifrato + restore test settimanale automatico
Migrazioni reversibili	Alembic con up/down testati prima di ogni deploy
Self-hosted by default	Nessun lock-in cloud; deploy on-prem possibile

Contattaci

Per valutare un partnership reseller, discutere requisiti tecnici o richiedere un approfondimento sull'architettura.

Contattaci →