Integrazioni e sistemi esterni¶

La piattaforma vive di integrazioni, ma non delega all'esterno la propria accountability.

Ogni sistema esterno è ammesso solo se:

il suo ruolo è chiaro;
il suo output è ricostruibile;
il suo effetto viene registrato localmente;
esiste una prova verificabile del collegamento tra richiesta, risposta e stato finale.

Mappa integrazioni¶

Sistema	Ruolo
Marble	decisioning KYT, trace e feedback loop
GoeSign	ceremony, step-up passkey, intent proof, notarization, archive bundle
walt.id	issuance/verifica VC, wallet managed, rail SSI
OpenCode / LLM gateway	generazione AI, assistenza task, reasoning operativo
Voice bridge	sessioni vocali AI
Storage locale / uploads	allegati, evidenze e documenti serviti dalla piattaforma
PostgreSQL	persistenza di dominio, evidenze e control plane

Principio di progettazione¶

Ogni integrazione deve lasciare traccia sufficiente per:

capire cosa è stato chiesto;
leggere cosa è tornato;
vedere chi ha approvato;
ricostruire l'effetto di business;
verificare la prova finale senza “fidarsi” del solo sistema esterno.

Sequence diagram¶

sequenceDiagram
    participant DWH as AML Platform
    participant LLM as OpenCode / LLM
    participant Marble as Marble
    participant SSI as walt.id
    participant Sign as GoeSign
    participant Reviewer as Reviewer umano
    participant Ledger as Evidence Ledger

    DWH->>LLM: genera proposta o action plan
    LLM-->>DWH: output AI
    DWH->>Reviewer: richiede approvazione
    alt KYT case
        DWH->>Marble: ingest / decision / reconcile
        Marble-->>DWH: outcome e trace
    end
    alt signing required
        DWH->>SSI: verify signing identity / VC
        SSI-->>DWH: verification result
        DWH->>Sign: avvia e completa ceremony
        Sign-->>DWH: receipt, bundle, proof
    end
    DWH->>Ledger: registra decisione, output, effect e receipt

Marble¶

Usato per:

ingest eventi KYT;
decision trace;
alert/escalation;
sync e replay;
reconciliation e release gates specifici.

Touchpoint principali:

/api/kyt/*
/api/marble/*
/kyt/*

GoeSign¶

Usato per:

avvio ceremony;
presentazione documento;
accettazione termini;
challenge passkey quando richiesta;
completamento firma;
receipt verificabile;
bundle e verifica post-firma.

Touchpoint principali:

/api/v1/goesign/ceremony/*
/goesign/ceremony/:id
/goesign/receipt/:id
/profilo/identita-firma

walt.id¶

Usato per:

issuance delle credential minime;
verifica credenziale di firma;
wallet managed;
stato / revoca credenziali.

Touchpoint principali:

provisioning da Admin > Organizzazione > Identità e firma
inventario personale in /profilo/credenziali
verifica runtime durante la ceremony di firma

OpenCode / LLM¶

Usato per:

AI Assist su checklist;
chat workspace;
role twins e prompt packs;
approvazioni AI-driven;
eventuali canali MCP.

Touchpoint principali:

/api/checklist/:id/ai-assist
/api/ai-runs/*
/api/ai-approvals/*
/api/mcp

Failure mode da presidiare¶

Sistema	Failure mode	Reazione attesa
Marble	sync fallita o trace mancante	queue, replay, dead-letter, gate rosso
GoeSign	ceremony o bundle incompleti	pending signature, fail-closed, retry o revoke
walt.id	issuer/verifier indisponibili	issuance pending o block in ceremony, mai green finto
LLM	output non affidabile o incompleto	review formale, reject, nuova run
Storage	allegato mancante	task bloccato o evidence issue

Evidenze minime attese¶

request/response semanticamente ricostruibili;
stato locale coerente;
reviewer e approvatore umano;
receipt o trace esterna collegata;
ledger entry finale;
per le firme: collegamento esplicito tra VC, step-up, bundle e sig_record.