Integrazioni e sistemi esterni¶

La piattaforma non vive isolata. Coordina sistemi esterni che producono decisioni, firme, contenuti AI e pacchetti verificabili.

Mappa integrazioni¶

Sistema	Ruolo
Marble	decisioning KYT e casi crypto
GoeSign	ceremony di firma, receipts, pacchetti firmati
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 unica di dominio, evidenze e control plane

Principio di progettazione¶

Ogni integrazione è utile solo se lascia traccia interna sufficiente per:

capire cosa è stato chiesto;
leggere cosa è tornato;
vedere chi ha approvato;
dimostrare l’effetto finale.

Sequence diagram¶

sequenceDiagram
    participant DWH as AML Platform
    participant LLM as OpenCode / LLM
    participant Marble as Marble
    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->>Sign: avvia ceremony o complete signing
        Sign-->>DWH: receipt o bundle
    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;
completamento firma;
receipt verificabile.

Touchpoint principali:

/api/v1/goesign/ceremony/*
/goesign/ceremony/:id
/goesign/receipt/:id

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	signing incompleto	pending signature, retry o revoke
LLM	output non affidabile o incompleto	human gate, 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.