ADR-0022: Documentazione e stack RAG¶
Stato: Accettato Ultimo aggiornamento: 2026-03-12
Sintesi della decisione¶
Jorvis impiega uno stack di documentazione costruito attorno a:
- MkDocs per il rendering della documentazione
- Open WebUI + pgvector per la RAG e il recupero in chat
- Pipeline ProcessorFactory per l'acquisizione di documenti aziendali nell'indice RAG
Fonti di acquisizione supportate¶
- Connettori Cloud: Google Docs (sola lettura), Google Drive (sola lettura), Google Sheets (sola lettura)
- Documenti d'ufficio: PDF, DOCX, XLSX, PPTX
- Formati strutturati/web: JSON, HTML, CSV, testo semplice, Markdown
- Embedding: i documenti vengono suddivisi in frammenti, trasformati in vettori tramite un modello di embedding Gemini e memorizzati in pgvector per la ricerca semantica.
Perché è stato scelto¶
- Si integra con l'attuale stack auto-ospitato (self-hosted).
- Mantiene basso l'overhead del runtime.
- Supporta i diagrammi Mermaid e la pubblicazione statica.
- Evita di aggiungere un secondo ambiente pesante dedicato ai documenti, considerando che lo stack corrente supporta già le procedure di ricerca (retrieval).
- Il pattern ProcessorFactory si estende facilmente a nuovi formati senza richiedere modifiche architetturali.
Risultato del Riferimento Pubblico¶
Le visualizzazioni pubbliche offrono ora collegamenti a una build mkdocs-public.yml dedicata situata sotto /reference-it/, consentendo agli utenti del browser di visualizzare pagine HTML renderizzate invece che il solo formato Markdown grezzo o le rotte di gestione interna.