From 23bc2f655547f7607f802086ffd7444c105fb92f Mon Sep 17 00:00:00 2001 From: mptyl Date: Wed, 26 Aug 2026 10:00:50 +0200 Subject: [PATCH] docs: add Mermaid architecture diagrams --- docs/architecture/authentication.md | 14 ++++++++++++ docs/architecture/overview.md | 12 ++++++++++ .../contracts/workflow-observable-baseline.md | 22 +++++++++++++++++++ docs/contracts/workspace-evidence-v3.md | 15 +++++++++++++ docs/contracts/workspace-preprocessing-cli.md | 12 ++++++++++ docs/disambiguazione-iniziale.md | 17 ++++++++++++++ docs/gestione-memory.md | 10 +++++++++ docs/installazione-docker-4-contesti.md | 14 ++++++++++++ docs/skill-tht-sessione.md | 14 ++++++++++++ 9 files changed, 130 insertions(+) diff --git a/docs/architecture/authentication.md b/docs/architecture/authentication.md index 9e3b3e5a..e61c8c7d 100644 --- a/docs/architecture/authentication.md +++ b/docs/architecture/authentication.md @@ -5,6 +5,20 @@ surface is one CLI, `tht`; there is no separate authentication executable. The b opaque browser sessions and authorization, while `tht` owns protected configuration and local-user files. +```mermaid +flowchart TB + BROWSER["Browser"] --> BOUNDARY["Authentication boundary"] + BOUNDARY --> LOCAL["Local users\nArgon2id hashes"] + BOUNDARY --> OIDC["OIDC provider\nAuthorization Code PKCE"] + OIDC --> GROUPS["Groups claim\nexact mapping"] + LOCAL --> PRINCIPAL["Thoth principal"] + GROUPS --> PRINCIPAL + PRINCIPAL --> ROLES["Roles"] + ROLES --> PERMISSIONS["Permissions"] + PERMISSIONS --> ROUTES["Protected routes"] + SECRETS["Mounted secret bundle"] -.-> BOUNDARY +``` + ## Configuration and trust boundaries The installation descriptor points to an operator-controlled authentication directory. It contains diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md index 5a4281b5..d089887c 100644 --- a/docs/architecture/overview.md +++ b/docs/architecture/overview.md @@ -10,6 +10,18 @@ ThothII è un **datamart builder human-in-the-loop**: trasforma una domanda in l L'autenticazione di produzione usa local oppure OIDC generico; il solo CLI operatore è tht. Per sessioni, ruoli, gruppi, diagnostica e ripristino vedere la [documentazione autenticazione](authentication.md). +```mermaid +flowchart LR + USER["Reviewer"] --> FE["Frontend\nReact and SSE"] + FE --> BE["Backend\nFastify"] + BE --> PI["Pi\nRPC per sessione"] + PI --> THT["tht and harness\nworkflow and persistence"] + THT --> DWH["DWH\nread only"] + THT --> EVIDENCE["Evidence\ncurated corpus"] + EVIDENCE --> THT + THT --> FE +``` + ## I tre progetti indipendenti ``` diff --git a/docs/contracts/workflow-observable-baseline.md b/docs/contracts/workflow-observable-baseline.md index c201e64a..d31de3f3 100644 --- a/docs/contracts/workflow-observable-baseline.md +++ b/docs/contracts/workflow-observable-baseline.md @@ -8,6 +8,28 @@ Changing an expectation in this baseline is a behavior change and requires an ex decision. Moving code between Workflow core, Disambiguation, Memory, and Evidence must keep the baseline green without weakening its assertions. +```mermaid +stateDiagram-v2 + [*] --> F1 + state "F1 Clarification" as F1 + state "F2 Memory" as F2 + state "F3 Question rewrite" as F3 + state "F4 Evidence" as F4 + state "F5 Schema linking" as F5 + state "F6 SQL drafting" as F6 + state "F7 Validation" as F7 + state "F8 Promotion" as F8 + F1 --> F2 + F2 --> F3 + F3 --> F4 + F4 --> F5 + F5 --> F6 + F6 --> F7 + F7 --> F8 + F7 --> F6: correction + F8 --> [*] +``` + ## Automated seams ### Pi gate diff --git a/docs/contracts/workspace-evidence-v3.md b/docs/contracts/workspace-evidence-v3.md index 3bfa0f7d..44fb26c5 100644 --- a/docs/contracts/workspace-evidence-v3.md +++ b/docs/contracts/workspace-evidence-v3.md @@ -5,6 +5,21 @@ workspace descriptor. Evidence is optional: a valid v3 descriptor without it rem When present, `evidence` is strict: it contains `source` and a defaulted strict `policy`; every source variant and the policy reject unknown keys. +```mermaid +flowchart LR + REGISTRY["Workspace registry"] --> DESCRIPTOR["Evidence descriptor"] + DESCRIPTOR --> FILESYSTEM["Filesystem adapter"] + DESCRIPTOR --> HTTP["HTTP adapter"] + DESCRIPTOR --> S3["S3 adapter"] + FILESYSTEM --> CURATED["Curated markdown"] + HTTP --> CURATED + S3 --> CURATED + CURATED --> VALIDATE["Validate schema\nand provenance"] + VALIDATE --> PREPROCESS["Preprocess pinned\nrevision"] + PREPROCESS --> GENERATION["Versioned generation"] + GENERATION --> ACTIVE["Active corpus"] +``` + ## Filesystem source A filesystem source uses the exact URI `/evidence`. `patterns` is a nonempty list of diff --git a/docs/contracts/workspace-preprocessing-cli.md b/docs/contracts/workspace-preprocessing-cli.md index 22662a80..94a96541 100644 --- a/docs/contracts/workspace-preprocessing-cli.md +++ b/docs/contracts/workspace-preprocessing-cli.md @@ -2,6 +2,18 @@ `tht` is the only supported host entrypoint for workspace preprocessing. +```mermaid +flowchart LR + OP["Operator"] --> INVOKE["tht workspace preprocess"] + INVOKE --> VALIDATE["Validate descriptor\nand paths"] + VALIDATE --> SOURCE["Read source and\ncurated workspace"] + SOURCE --> NORMALIZE["Normalize and chunk"] + NORMALIZE --> INDEX["Update vector and\nBM25 indexes"] + INDEX --> VERIFY["Verify collection\nand generation"] + VERIFY --> READY["Generation ready"] + VALIDATE -->|"invalid"| STOP["Exit with diagnostic"] +``` + ## Invocation ```text diff --git a/docs/disambiguazione-iniziale.md b/docs/disambiguazione-iniziale.md index 3afb9332..231910e1 100644 --- a/docs/disambiguazione-iniziale.md +++ b/docs/disambiguazione-iniziale.md @@ -6,6 +6,23 @@ Il principio architetturale è **human-in-the-middle**: il modello propone inter La procedura è definita nella skill canonica [tht-sessione](../harness/.pi/skills/tht-sessione/SKILL.md), soprattutto nelle sezioni F1 e F2, ed è applicata dai widget in [tht-gate.js](../harness/.pi/extensions/tht-gate.js). +```mermaid +stateDiagram-v2 + [*] --> DETECT + state "Detect ambiguity" as DETECT + state "Build reviewer options" as PROPOSE + state "Ask with reviewer_select" as ASK + state "Multiple valid answers" as MULTI + state "Record accepted decision" as ACCEPTED + DETECT --> PROPOSE: ambiguity found + DETECT --> ASK: safe default unavailable + PROPOSE --> ASK + ASK --> ACCEPTED: one option selected + ASK --> MULTI: multiple answers valid + MULTI --> ACCEPTED + ACCEPTED --> [*] +``` + ## Dove avviene la disambiguazione La disambiguazione iniziale attraversa quattro passaggi distinti: diff --git a/docs/gestione-memory.md b/docs/gestione-memory.md index 68f8533f..5760c414 100644 --- a/docs/gestione-memory.md +++ b/docs/gestione-memory.md @@ -6,6 +6,16 @@ Questo documento descrive l'organizzazione attuale delle memory nel workflow Tho Una memory è conoscenza di dominio riutilizzabile tra domande. Non è una copia dello schema-linking di una singola domanda. +```mermaid +flowchart TB + CLARIFY["F1 concept clarified"] --> REVIEW["F8 reviewer review"] + REVIEW -->|"accepted"| REGISTRY["registry.jsonl"] + REVIEW -->|"declined"| LOCAL["Session decision only"] + REGISTRY --> VECTOR["Qdrant semantic index"] + VECTOR --> FUTURE["Future F2 retrieval"] + FUTURE --> PROPOSAL["Reviewer proposal"] +``` + ```text F1: chiarimento di un concetto │ diff --git a/docs/installazione-docker-4-contesti.md b/docs/installazione-docker-4-contesti.md index db043594..2c766a6c 100644 --- a/docs/installazione-docker-4-contesti.md +++ b/docs/installazione-docker-4-contesti.md @@ -11,6 +11,20 @@ ThothII usa una topologia Compose unica: Qdrant e Ollama embedding sono servizi interni obbligatori del progetto Compose. Restano esterni solo DWH e LLM. Il modello fissato è `qwen3-embedding:0.6b` con 1024 dimensioni e distanza coseno; `embedding-model-init` lo prepara prima dell'avvio di `core`. +```mermaid +flowchart TB + INSTALL["Installation descriptor"] --> CONTEXT{Context} + CONTEXT --> LOCAL["Local\nCompose local"] + CONTEXT --> SERVER["Server\nCompose server"] + CONTEXT --> SESSION["Session server\noperator services"] + CONTEXT --> AUTH["Auth runtime\nprojection services"] + LOCAL --> BUNDLE["Common secret bundle"] + SERVER --> BUNDLE + SESSION --> BUNDLE + AUTH --> BUNDLE + BUNDLE --> SERVICES["Frontend, core, vector, embedding"] +``` + ## Contratto sintetico di ownership | Componente | Ownership | Contratto operativo | diff --git a/docs/skill-tht-sessione.md b/docs/skill-tht-sessione.md index 9c2d70c4..18b917d6 100644 --- a/docs/skill-tht-sessione.md +++ b/docs/skill-tht-sessione.md @@ -5,4 +5,18 @@ La sorgente è [harness/.pi/skills/tht-sessione/SKILL.md](../harness/.pi/skills/ Il blocco seguente viene incluso direttamente dal file sorgente durante il build MkDocs: non è una copia manuale. +```mermaid +flowchart LR + QUESTION["New question"] --> F1["F1 clarify"] + F1 --> F2["F2 memory"] + F2 --> F3["F3 rewrite"] + F3 --> F4["F4 evidence"] + F4 --> F5["F5 schema"] + F5 --> F6["F6 SQL"] + F6 --> F7["F7 validation"] + F7 --> F8["F8 promotion"] + F7 --> F6 + F8 --> FINAL["Finalized session"] +``` + --8<-- "harness/.pi/skills/tht-sessione/SKILL.md"