# ThothII — Portable Deployment Architecture Design **Data:** 2026-07-11 **Stato:** design di massima approvato; piano implementativo dettagliato non ancora elaborato ## 1. Obiettivo Riorganizzare ThothII affinché possa essere distribuito con due immagini applicative invarianti: 1. `thothii-core`, contenente backend Fastify, harness Python, Pi, CLI `tht` e job di preprocessing; 2. `thothii-frontend`, contenente la build React e il reverse proxy verso il backend. Lo stesso software deve funzionare in tre contesti: - sul server che ospita già DWH e vectordb; - su un server autonomo con DWH esterno e vectordb locale; - su PC o Mac con DWH esterno e vectordb locale o remoto. La portabilità deve essere ottenuta tramite adapter, configurazione e profili di deployment, non tramite varianti del workflow o immagini applicative diverse. ## 2. Situazione attuale rilevante L'architettura corrente è `frontend → backend → Pi RPC → tht/harness → DWH`. Il backend è un bridge senza database applicativo; l'harness possiede workflow e persistenza delle sessioni. Esistono già due trasporti DWH, PostgreSQL diretto e REST, ma il supporto diretto è legato al dialetto e ai cataloghi PostgreSQL. Il vectordb dispone di accesso diretto e di un client PostgREST/RPC, con percorsi di lettura e scrittura separati. Le Evidence e gli indici dipendono invece in modo significativo da directory configurate nel workspace, oggi anche assolute e collocate in repository cliente esterni. Non sono presenti Dockerfile o file Compose. Il processo di sviluppo assume Pi e `tht` sul `PATH`, dipendenze installate nei tre layer e configurazioni/segreti locali in `harness/.env`. ## 3. Principi architetturali 1. **Due immagini applicative, infrastruttura opzionale separata.** Un pgvector locale è un terzo container infrastrutturale basato su un'immagine standard, non una terza immagine ThothII. 2. **Monolite modulare.** Backend e harness restano insieme nel runtime core, ma dipendono da contratti espliciti anziché da trasporti concreti. 3. **Workflow invariato.** I profili selezionano adapter e servizi; non modificano il significato delle otto fasi. 4. **Persistenza esterna ai container.** Sessioni, corpus, indici, configurazione e dati vettoriali vivono su volumi o servizi esterni. 5. **Runtime e preprocessing separati.** Usano la stessa immagine core, ma processi, lifecycle e criteri di successo distinti. 6. **Configurazione dichiarativa e validata.** I workspace contengono riferimenti logici e configurazioni non segrete; i segreti sono in environment variables o secret store. 7. **Capability esplicite.** Un adapter dichiara ciò che supporta. Le funzioni mancanti producono degradazione o blocco comprensibile, non emulazioni implicite. 8. **Read-only by construction sul DWH.** Credenziali, API e guard client-side mantengono la separazione dall'autorità di scrittura. 9. **Esposizione sicura per default.** La porta applicativa pubblicata è vincolata a loopback. Un'esposizione pubblica richiede un reverse proxy autenticante esterno e `AUTH_MODE=upstream`; la combinazione pubblico + `none` viene rifiutata all'avvio. OIDC interno non fa parte di questa fase. ## 4. Packaging e runtime ### 4.1 Immagine `thothii-core` Contiene: - backend Node/Fastify compilato; - harness Python installato con CLI `tht`; - estensione e skill Pi richieste dal workflow; - runtime Pi e dipendenze necessarie; - strumenti di preprocessing e diagnostica. L'immagine espone entrypoint logici distinti: - servizio backend; - job documentale; - job metadata/LSH DWH; - migrazioni e diagnostica. I job non vengono eseguiti nel processo web e non consumano richieste applicative. ### 4.2 Immagine `thothii-frontend` È una build statica React servita da un web server leggero. L'indirizzo del backend deve essere configurabile al runtime tramite reverse proxy o configurazione caricata all'avvio, senza ricompilare Vite per ogni installazione. ### 4.3 Volumi e root logiche Il core usa root interne stabili, per esempio: - `/data/workspaces` per configurazioni e dati per cliente; - `/data/sessions` per sessioni e artefatti; - `/data/corpus` per Evidence normalizzate e manifest; - `/data/indexes` per indici locali e cache; - `/run/secrets` o environment variables per i segreti. I workspace non devono richiedere path assoluti dell'host. I path relativi vengono risolti rispetto alle root montate. ## 5. Contratti degli adapter ### 5.1 DWH Il contratto `DwhAdapter` copre le capacità effettivamente necessarie al workflow: - health check; - elenco e introspezione di schemi, tabelle e colonne; - esecuzione read-only; - `EXPLAIN` o validazione equivalente; - sampling; - estrazione dei valori distinti per il preprocessing LSH. Adapter iniziali: - `postgres_direct`, evoluzione del percorso SQLAlchemy/PostgreSQL attuale; - `thoth_rest`, evoluzione del contratto REST attuale. Oracle, SQL Server, Snowflake e API proprietarie sono estensioni future. Non fanno parte del primo rilascio portabile. L'interfaccia deve renderli aggiungibili, ma non deve fingere che cataloghi, dialetti ed `EXPLAIN` siano uniformi. ### 5.2 Vectordb Il contratto `VectorStore` fornisce: - health check distinto per lettura e scrittura; - similarity search filtrata per tipo; - upsert e sincronizzazione incrementale; - gestione o verifica delle collezioni necessarie; - informazioni su dimensione e compatibilità degli embedding. Adapter iniziali: - `pgvector_direct`, per PostgreSQL/pgvector locale o remoto; - `thoth_vector_http`, basato sulle RPC HTTP attuali. Le credenziali reader e writer restano separate. Il runtime può funzionare in sola lettura; i job di indicizzazione devono fallire prima di elaborare dati se manca l'autorità di scrittura. ### 5.3 Sorgenti Evidence Il contratto `EvidenceSource` fornisce: - discovery degli oggetti; - lettura a stream o contenuto; - URI canonico; - fingerprint, data di modifica e metadati; - classificazione degli errori come transitori o permanenti. Adapter iniziali: - `filesystem` per directory e volumi montati; - `http` per risorse HTTPS esplicite o manifest remoti. L'adapter `s3`/S3-compatible è il successivo prioritario. Altri protocolli possono essere aggiunti senza cambiare normalizzazione e indicizzazione. ### 5.4 Composizione Una factory costruisce gli adapter dal workspace validato e li inietta nei comandi applicativi. URL, driver, chiavi e controlli sul tipo non devono essere sparsi nel workflow o nei singoli comandi CLI. ## 6. Configurazione e segreti Ogni risorsa del workspace dichiara un `type` e una sezione specifica. La configurazione viene validata all'avvio e supporta riferimenti a environment variables o file secret. La configurazione si divide in: - **immagine:** default non sensibili; - **deployment:** profilo, hostname, porte, mount e servizi opzionali; - **workspace:** lingua, adapter, namespace, collezioni e policy di preprocessing; - **segreti:** password, token, certificati e chiavi reader/writer. Nel profilo locale i segreti possono provenire da un env-file non versionato. In produzione sono file read-only sotto `/run/secrets`, leggibili dall'UID 10001. Il reverse proxy autenticante è un confine fidato: rimuove header identità forniti dal client e inserisce `X-Authenticated-User` soltanto dopo autenticazione. Deve esistere un comando di diagnostica che produca sia output umano sia JSON pristino, rispettando il contratto CLI corrente. ## 7. Pipeline di preprocessing ### 7.1 Pipeline documentale La pipeline è idempotente e comprende: 1. **Discover:** enumerazione di URI, fingerprint e metadati. 2. **Acquire:** lettura o download con timeout, retry e limiti. 3. **Normalize:** conversione in testo canonico UTF-8 e metadati comuni. 4. **Chunk/enrich:** segmentazione deterministica e collegamento alla sorgente. 5. **Embed/index:** embedding e sync incrementale nel vectordb selezionato. 6. **Publish:** attivazione atomica della nuova versione logica del corpus. 7. **Report:** manifest machine-readable di nuovi, modificati, invariati, rimossi e falliti. Il corpus canonico conserva testo normalizzato, URI sorgente, hash, metadati, versione pipeline, strategia di chunking, modello embedding e stato di indicizzazione. Le sorgenti originali possono quindi essere indisponibili durante il runtime interattivo. Un cambio di contenuto rielabora solo gli elementi interessati. Un cambio di modello embedding o regole di chunking invalida esplicitamente gli artefatti compatibili e abilita una ricostruzione controllata. ### 7.2 Pipeline DWH Introspezione schema, annotazioni e costruzione LSH utilizzano la stessa infrastruttura operativa di job, lock, manifest e report, ma costituiscono una pipeline distinta. Evidence e metadata DWH possono così avere frequenze, permessi e prerequisiti diversi. ### 7.3 Esecuzione Nell'MVP non viene introdotto un orchestratore interno. I job sono CLI idempotenti con: - lock per workspace; - exit code affidabili; - report JSON; - resume o retry selettivo; - modalità dry-run; - logging strutturato. La schedulazione è responsabilità di Docker Compose, cron, Kubernetes Job o CI. ## 8. Profili di deployment ### 8.1 Profilo A — server co-locato - `thothii-core` e `thothii-frontend`; - DWH e vectordb esistenti su rete locale o Docker network; - adapter diretti preferiti; - Evidence da volume, share o sorgente remota; - nessun database aggiunto automaticamente. ### 8.2 Profilo B — server autonomo - i due container applicativi; - DWH esterno via PostgreSQL o REST; - profilo `local-vector` con PostgreSQL+pgvector e volume persistente; - preprocessing locale schedulato; - corpus Evidence materializzato sul server. ### 8.3 Profilo C — PC o Mac - i due container applicativi in Docker Desktop; - DWH remoto via REST o PostgreSQL/tunnel autorizzato; - pgvector locale opzionale oppure vectordb HTTP remoto; - mount controllati per sorgenti locali; - configurazione in una directory utente, senza path host nei workspace. ### 8.4 Profili Compose Un Compose di base avvia le due immagini applicative. Profili e override aggiungono: - `external` per dipendenze dati interamente remote; - `local-vector` per pgvector e relativo volume; - `preprocess` per job one-shot; - impostazioni specifiche co-located, server e desktop senza duplicare la definizione dei servizi. ## 9. Resilienza e osservabilità I controlli distinguono: - processo backend; - validità configurazione e accesso ai volumi; - DWH; - vector read; - vector write; - embeddings; - sorgenti Evidence. La disponibilità del frontend e del backend non deve dipendere dal successo immediato di tutte le integrazioni. Le singole operazioni applicano una matrice esplicita di dipendenze obbligatorie e opzionali. Esempi: - DWH non raggiungibile blocca introspezione, validazione ed esecuzione SQL; - vectordb non raggiungibile consente le fasi che possono degradare senza retrieval; - sorgenti Evidence non raggiungibili non interrompono il runtime se esiste una versione pubblicata del corpus; - errori di preprocessing non sostituiscono l'ultima versione valida. Log strutturati e correlation id devono collegare richiesta backend, processo Pi, comando `tht`, adapter e job. ## 10. Strategia di verifica - contract test comuni per ogni implementazione di `DwhAdapter`, `VectorStore` ed `EvidenceSource`; - test delle due immagini e dei relativi health check; - integrazione Compose con pgvector locale; - test dei profili A, B e C con dipendenze reali o simulate; - test di compatibilità e migrazione dei workspace esistenti; - test di interruzione, resume, idempotenza e publish atomico del preprocessing; - smoke test Linux amd64, Linux arm64 e macOS Docker Desktop; - build multi-arch condizionata alla disponibilità di Pi e delle dipendenze native su entrambe le architetture; - gate L2 sui DWH e vectordb reali per i trasporti già in produzione. ## 11. Piano di massima Il lavoro va suddiviso in workstream verificabili separatamente. ### Fase 0 — baseline e decisioni operative - inventario completo di dipendenze runtime e licenze/distribuibilità di Pi; - definizione dei target architetturali supportati; - schema della configurazione target e politica di migrazione; - matrice delle capability e delle degradazioni. ### Fase 1 — contratti e compatibilità - introdurre i contratti DWH, vector ed Evidence; - adattare le implementazioni esistenti senza cambiarne il comportamento; - centralizzare factory e validazione; - aggiungere contract test e conservare la suite corrente verde. ### Fase 2 — immagini e storage portabile - costruire `thothii-core` e `thothii-frontend`; - rendere runtime-configurabile il proxy frontend; - sostituire i path host assoluti con root logiche e mount; - aggiungere Compose base, health check e smoke test. ### Fase 3 — vectordb locale opzionale - completare l'adapter `pgvector_direct` dietro il contratto comune; - definire schema, inizializzazione, migrazioni, backup e restore; - aggiungere il profilo `local-vector`; - verificare parità funzionale tra accesso diretto e HTTP. ### Fase 4 — Evidence multi-sorgente - introdurre corpus canonico e manifest; - implementare adapter filesystem e HTTP; - migrare le Evidence correnti; - aggiungere in seguito S3-compatible sulla stessa interfaccia. ### Fase 5 — preprocessing robusto - realizzare pipeline documentale incrementale e publish atomico; - uniformare job DWH/LSH a lock, report e retry comuni; - predisporre entrypoint Compose/Kubernetes/cron; - verificare recovery e ricostruzione per cambio embedding. ### Fase 6 — profili e hardening operativo - validare i tre profili A/B/C; - completare diagnostica, logging, backup e documentazione; - produrre immagini multi-arch se supportate; - eseguire gate L2 e definire procedure di upgrade/rollback. Ogni fase richiede un piano implementativo dedicato. In particolare adapter, containerizzazione, vectordb locale ed Evidence/preprocessing sono workstream distinti: accorparli in un unico piano file-per-file renderebbe difficile ottenere incrementi funzionanti e revisionabili. ## 12. Fuori perimetro iniziale - supporto immediato per ogni dialetto SQL; - orchestratore proprietario dei job; - microservizi separati per DWH, vector ed Evidence; - copia integrale obbligatoria dei file binari originali, oltre al testo normalizzato e ai metadati necessari; - alta disponibilità del pgvector locale gestita da ThothII; - modifica del workflow NL→SQL o del modello di persistenza delle sessioni. ## 13. Criteri di successo del programma Il programma è completato quando: - le stesse due immagini applicative funzionano nei profili A, B e C; - un workspace sceglie trasporti e sorgenti senza modifiche al codice; - il vectordb può essere remoto via HTTP, diretto o locale come servizio opzionale; - le Evidence possono provenire da sorgenti eterogenee e il runtime usa un corpus versionato già pubblicato; - il preprocessing è idempotente, osservabile, riprendibile e separato dal servizio web; - i workspace esistenti sono migrabili con comportamento compatibile; - indisponibilità e permessi insufficienti producono diagnosi esplicite e degradazioni documentate.