ThothII/docs/architecture/thothii-core.sequence.json

{
  "schema_version": 1,
  "diagram_type": "sequence",
  "meta": {
    "title": "Sequenza runtime del core ThothII",
    "output": "thothii-core-sequence.html",
    "quality_profile": "showcase",
    "column_fit": "spread",
    "viewBox": [1080, 540]
  },
  "participants": [
    {
      "id": "reviewer",
      "type": "external",
      "label": "Revisore",
      "sublabel": "browser"
    },
    {
      "id": "frontend",
      "type": "frontend",
      "label": "Frontend",
      "sublabel": "React + SSE"
    },
    {
      "id": "api",
      "type": "backend",
      "label": "Core API",
      "sublabel": "Fastify + SseHub"
    },
    {
      "id": "runtime",
      "type": "backend",
      "label": "Runtime",
      "sublabel": "manager + bridge"
    },
    {
      "id": "pi",
      "type": "backend",
      "label": "Pi + tht-gate",
      "sublabel": "RPC per sessione"
    },
    {
      "id": "model",
      "type": "external",
      "label": "Modello AI",
      "sublabel": "provider configurato"
    },
    {
      "id": "tht",
      "type": "backend",
      "label": "tht CLI",
      "sublabel": "workflow persistito"
    },
    {
      "id": "state",
      "type": "database",
      "label": "Stato e dati",
      "sublabel": "workspace + dati"
    }
  ],
  "segments": [
    {
      "from": 150,
      "to": 300,
      "label": "Avvio o ripresa"
    },
    {
      "from": 305,
      "to": 395,
      "label": "Turno Pi e workflow persistito"
    },
    {
      "from": 400,
      "to": 475,
      "label": "Evento SSE e gate umano"
    }
  ],
  "messages": [
    {
      "id": "askQuestion",
      "from": "reviewer",
      "to": "frontend",
      "y": 160,
      "label": "domanda o decisione gate",
      "variant": "emphasis"
    },
    {
      "id": "createSession",
      "from": "frontend",
      "to": "api",
      "y": 185,
      "label": "POST /sessions o /response",
      "variant": "emphasis"
    },
    {
      "id": "newManifest",
      "from": "api",
      "to": "tht",
      "y": 210,
      "label": "sessionNew o sessionShow/reopen"
    },
    {
      "id": "persistQuestion",
      "from": "tht",
      "to": "state",
      "y": 235,
      "label": "manifest, artifact e ledger"
    },
    {
      "id": "createRuntime",
      "from": "api",
      "to": "runtime",
      "y": 260,
      "label": "createFor + bind; configure + searchPack",
      "note": "configure(...) e searchPack(...) terminano in parallelo prima dell’avvio del modello."
    },
    {
      "id": "startPi",
      "from": "runtime",
      "to": "pi",
      "y": 285,
      "label": "/nuova-domanda o /riprendi-sessione",
      "variant": "emphasis",
      "note": "In ripresa usa /riprendi-sessione <id> dopo aver riletto provider, modello e thinking dal manifest."
    },
    {
      "id": "modelRequest",
      "from": "pi",
      "to": "model",
      "y": 315,
      "label": "turno modello; token e tool call"
    },
    {
      "id": "phaseCommand",
      "from": "pi",
      "to": "tht",
      "y": 345,
      "label": "comandi phase / session / evidence",
      "variant": "emphasis"
    },
    {
      "id": "readWriteTruth",
      "from": "tht",
      "to": "state",
      "y": 375,
      "label": "legge/scrive artifact e ledger",
      "note": "Il workspace persistito è la verità; DWH è read-only e Qdrant serve il retrieval."
    },
    {
      "id": "rpcEvents",
      "from": "pi",
      "to": "runtime",
      "y": 405,
      "label": "text_delta / ui_request"
    },
    {
      "id": "sseEvent",
      "from": "runtime",
      "to": "frontend",
      "y": 430,
      "label": "SSE via SseHub: text · info · widget",
      "variant": "return"
    },
    {
      "id": "showResult",
      "from": "frontend",
      "to": "reviewer",
      "y": 455,
      "label": "testo o widget di revisione",
      "variant": "return"
    }
  ],
  "activations": [
    {
      "participant": "frontend",
      "from": 155,
      "to": 460,
      "type": "frontend"
    },
    {
      "participant": "api",
      "from": 180,
      "to": 290,
      "type": "backend"
    },
    {
      "participant": "runtime",
      "from": 255,
      "to": 440,
      "type": "backend"
    },
    {
      "participant": "pi",
      "from": 280,
      "to": 415,
      "type": "backend"
    },
    {
      "participant": "model",
      "from": 310,
      "to": 335,
      "type": "external"
    },
    {
      "participant": "tht",
      "from": 205,
      "to": 390,
      "type": "backend"
    },
    {
      "participant": "state",
      "from": 230,
      "to": 390,
      "type": "database"
    }
  ],
  "cards": [
    {
      "dot": "cyan",
      "title": "Bootstrap",
      "items": [
        "La sessione viene persistita prima dell’avvio di Pi; configurazione e retrieval terminano prima del primo prompt.",
        "La ripresa rifiuta sessioni finalizzate o archiviate e usa sempre /riprendi-sessione <id>.",
        "Il modello propone; il revisore decide tramite reviewer_select, reviewer_decide o reviewer_confirm.",
        "La risposta percorre POST /sessions/:id/response → bridge.respond → extension_ui_response; stale/duplicate ricevono 409.",
        "La fase avanza solo dopo append della decisione esplicita e fold del ledger persistito."
      ]
    }
  ]
}