From 586180eaa1889b1db50430bbd38665d73052aa97 Mon Sep 17 00:00:00 2001 From: mptyl Date: Sat, 11 Jul 2026 19:39:43 +0200 Subject: [PATCH] docs: define portable deployment architecture --- ...portable-deployment-architecture-design.md | 327 ++++++++++++++++++ 1 file changed, 327 insertions(+) create mode 100644 docs/superpowers/specs/2026-07-11-portable-deployment-architecture-design.md diff --git a/docs/superpowers/specs/2026-07-11-portable-deployment-architecture-design.md b/docs/superpowers/specs/2026-07-11-portable-deployment-architecture-design.md new file mode 100644 index 00000000..4bd21ce5 --- /dev/null +++ b/docs/superpowers/specs/2026-07-11-portable-deployment-architecture-design.md @@ -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.