ThothII/docs/superpowers/specs/2026-07-11-portable-deployment-architecture-design.md

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.