Technical infrastructure

Layered architecture · 01 / 05

Quattro livelli gerarchici

The platform is organised into four concentric levels. Each level inherits capabilities from the one above and retains operational autonomy over its sub-levels, with data isolation guaranteed at the database layer.

L4Central

Forge Central

Platform operator

Global infrastructure control, reseller provisioning, policy configuration, monitoring and AI cost tracking.

L3Reseller

Reseller / Group

Distributor

Manages a portfolio of L2 studios, applies its own branding and price lists, defines operational limits and AI feature access.

L2Studio

Studio / Professional

Primary user

Works daily on the platform for its L1 clients, manages studio users, configures templates and internal knowledge base.

L1Client

End client

Self-service access

The company or entity served by the L2 studio. Sees only its own data, with permissions configurable by its L2 of reference.

Provisioning hierarchy

Each upper level instantiates and configures the lower ones. Data visibility strictly follows this hierarchy.

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

Top-down provisioning · data isolation orthogonal to hierarchy · single sign-on with per-level scope.

Inter-level communication · 02 / 05

Come scorronoHow data flows

All requests go through a single FastAPI backend that enforces authentication, per-level scope and isolation policies before touching the database. No service bypasses the gateway.

01

Authentication & scope

Login issues a token with level (L1-L4) and hierarchy ID. Every request carries the scope. The backend rejects anything outside the declared scope.

02

DB session setup

At request start, the backend sets PostgreSQL session variables (level, studio, role). RLS policies read them and filter automatically.

03

Isolated queries

Every SELECT/INSERT/UPDATE goes through Row-Level Security. An L2 never sees another L2's data, even on application bugs.

04

Reverse proxy

Cloudflare Tunnel + internal Nginx terminate TLS, apply rate limiting and route to the backend. No port exposed in plaintext.

05

Controlled bypass

For system tasks (logging, batch) a dedicated role temporarily activates bypass policies; never accessible from frontend or real users.

06

Audit trail

Every operation leaves a trace in dedicated tables with user, level, IP, timestamp. Traces are not modifiable from the application.

Request flow

From user to database, through authentication, scope, RLS and 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)

AI integration · 03 / 05

AI nativaNative AI, not bolt-on

Joshua Cloud embeds an AI gateway (forge_ai) that unifies access to five providers and offers each level natural-language operations, structured output and a knowledge base with per-studio isolation.

CHAT

Contextual conversation

Each level talks to an assistant that knows its scope. L2 sees only its own studios, L1 only its own reality.

RAG

Per-studio knowledge base

Documents uploaded by an L2 are indexed in a private KB, with pgvector embeddings and automatic re-indexing.

STRUCT

Structured output

Data extraction from documents with guaranteed schema (Pydantic). Gemini and OpenAI models reply directly in validated JSON.

ROUTE

Smart routing

Simple tasks are routed to cheap models, complex reasoning to frontier models. Average cost reduced by 60–80%.

LOCAL

On-premise mode

For highly sensitive data, local Ollama is available: no byte leaves the infrastructure, GDPR-friendly by default.

TRACK

Per-level cost tracking

Every AI call is tracked by level, studio and model. Costs can be passed through or capped by commercial plan.

AI gateway · logical architecture

forge_ai sits between the application and providers, enforcing scope, routing and 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

Scope context injected on every call · KB partitioned per studio · cache invalidated on KB updates.

Security & isolation · 04 / 05

Isolamento a livello database

Tenant separation is not just application-level: it is enforced by PostgreSQL Row-Level Security with FORCE policies that hold even against code bugs. Combined with encrypted backups, audit trail and perimeter protection.

Forced PostgreSQL RLS

Database

Row-Level Security policies applied with FORCE on every multi-tenant table. Even a query with no WHERE filters automatically by scope. No bypass possible from the standard application.

Least-privilege roles

Auth

The backend connects with a limited application role. Privileged operations require explicit escalation to a dedicated, tracked, narrow-scope role.

Edge protection

Network

Cloudflare in front: WAF, rate limiting, DDoS mitigation, managed certificates. Origin reachable only via authenticated tunnel; no port exposed to the Internet.

Encrypted versioned backups

Recovery

Hourly incremental backups on encrypted offsite storage (Hetzner Borg) with 30-day retention, plus a local copy on a dedicated disk. Automatic integrity verification.

Immutable audit log

Compliance

Every significant change is recorded in append-only tables with user, level, IP, timestamp and diff. Exportable for external audits.

AI segregation

AI scope

AI calls inherit the caller's scope. A studio's knowledge base is not queryable by another, not even by manually forging IDs.

Isolation matrix

Who sees what, enforced by the database.

Visible resource	L4	L3	L2	L1
Whole platform	●	—	—	—
Own reseller only	●	●	—	—
Own studio only	●	●	●	—
Own data only	●	●	●	●
Global audit log	●	—	—	—
Own-scope audit log	●	●	●	—

Tech stack · 05 / 05

Stack tecnologico

Technologies chosen for long-term stability, scalability and maintainability. No exotic frameworks, no dependency on a single vendor's proprietary services.

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

Observability & backup

Hetzner Borg Audit log SQL Telegram alerts USB local backup

Architectural principles

The non-negotiable rules guiding every technical choice.

Principle	Implementation
Data isolation	PostgreSQL RLS with FORCE on every multi-tenant table
Stateless backend	User session in JWT, immediate horizontal scaling
AI as library, not SaaS	forge_ai embedded, no dependency on external gateways
Verified backups	Encrypted Borg + automated weekly restore test
Reversible migrations	Alembic with up/down tested before every deploy
Self-hosted by default	No cloud lock-in; on-prem deployment possible

Contact us

To evaluate a reseller partnership, discuss technical requirements or request a deeper look at the architecture.

Contact us →