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.