docs: add Mermaid architecture diagrams

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

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
 
 ```