docs: define portable deployment architecture
This commit is contained in:
@@ -0,0 +1,327 @@
|
||||
# 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.
|
||||
|
||||
## 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.
|
||||
|
||||
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.
|
||||
Reference in New Issue
Block a user