Documentazione viva · mappa tecnica

Come è costruita LIA, livello per livello

I livelli del sistema, dallo schermo al database, cosa fa ogni blocco, con quali tecnologie, dove vive nel repository, e i percorsi che segue una richiesta.

  • 59blocchi tecnici
  • 10livelli
  • 7percorsi commentati
  • 57moduli di infrastruttura
  • 63domini di business serviti

Versione 4.6.010 novembre 2026aggiornata a ogni commit, dai dati del repository

Panoramica

I livelli del sistema

Dallo schermo al database. Passa sopra un blocco per tracciarne i legami, clicca per le sue tecnologie, i suoi file e le sue decisioni.

si appoggia ausato da

Client

Ciò che la persona tocca: l'applicazione web, la sua modalità offline, i gusci per mobile e i canali di messaggistica.

Perimetro

Ciò che sta tra Internet e l'applicazione: tunnel, politica dei contenuti, rate limiting, sessioni.

API e base applicativa

L'API FastAPI suddivisa in domini di business, il suo flusso SSE, il suo avvio ordinato e la sua configurazione.

Orchestrazione degli agenti

Il grafo LangGraph: instradamento, pianificazione o ciclo ReAct, validazione umana, strumenti e risposta.

Modelli e costi

L'accesso ai modelli di ogni fornitore, il ragionamento, gli output strutturati, gli embedding, e la contabilità di ogni chiamata.

Integrazioni

I client dei servizi esterni, i protocolli aperti, la sandbox e i canali vocali.

Job in background

Ciò che gira senza richieste: scheduler a leader unico, motore proattivo, job durevoli, autodiagnosi.

Dati

Dove vive lo stato: PostgreSQL e pgvector, Redis, file, e i registri di ciò che LIA ha fatto, letto e deciso.

Osservabilità

Misurare, vedere, allertare, rileggere: metriche, dashboard, allarmi, log, tracce.

Consegna

Come il codice diventa un servizio: immagini, integrazione continua e le sue guardie, release qualificata, installer, demo.

Percorsi

Scegli uno scenario: i suoi passi si accendono uno a uno sulla mappa.

Livelli

Clicca un livello per isolarlo.

I percorsi

Il percorso di una richiesta, di una chiamata, di una consegna

Ogni passo nomina il blocco che agisce e ciò che garantisce.

Il percorso di un messaggio di chat

Dalla tastiera allo schermo, passando per il grafo: una richiesta, un flusso, nessun token esposto.

  1. Applicazione web
    Il browser invia il messaggio all'API della sua stessa origine.
  2. Tunnel, CSP e rate limiting
    Il tunnel lo instrada; viene controllato il traffico del chiamante.
  3. Sessioni e autenticazione
    Il cookie di sessione viene convalidato lato server.
  4. API FastAPI per domini
    La rotta della chat apre un flusso e avvia il grafo.
  5. Grafo LangGraph
    Lo stato della conversazione viene ricaricato dal suo checkpoint.
  6. Router
    La richiesta viene classificata, gli strumenti valutati.
  7. Pianificatore ed esecutore
    Un piano viene scritto, validato, eseguito in parallelo.
  8. Strumenti e manifest
    Ogni strumento passa dalla porta di autorità e viene annotato nel registro.
  9. Client dei connettori
    Il fornitore viene chiamato, senza transazioni di database aperte.
  10. Sintesi della risposta
    La risposta viene sintetizzata a partire dai risultati.
  11. Streaming SSE
    Arriva parola per parola, con il suo costo, sullo stesso flusso.

Una chiamata al modello, da cima a fondo

Limitata prima, tradotta per il fornitore, tariffata al suo istante, tracciata dopo.

  1. Prompt versionati
    Il prompt viene assemblato: prima la parte stabile, un solo confine di cache.
  2. Contabilità e tetti di spesa
    I due tetti — account e istanza — vengono interrogati prima della spesa.
  3. Ragionamento
    L'intenzione di ragionamento viene tradotta per quel modello preciso.
  4. Factory dei modelli
    Il client nativo del fornitore invia la richiesta.
  5. Output strutturati
    Un output tagliato dal limite di token diventa un rifiuto esplicito.
  6. Contabilità e tetti di spesa
    L'utilizzo viene letto una sola volta e tariffato secondo la fascia oraria della chiamata.
  7. Registri tracciabili
    I parametri effettivamente inviati entrano nel registro della chiamata.
  8. Metriche
    Token, latenza e costo diventano metriche.

Un job proattivo in background

Un solo leader, un jitter, una rivendicazione, un invio liquidato in base al suo risultato.

  1. Scheduler a leader unico
    Il leader avvia la scansione, sfasata dal suo jitter.
  2. Motore proattivo
    Gli account idonei vengono selezionati secondo tutte le regole.
  3. Client dei connettori
    Le fonti vengono lette, ciascuna in una transazione breve.
  4. Factory dei modelli
    Il messaggio viene redatto entro i tetti di spesa.
  5. Registri tracciabili
    L'invio viene rivendicato prima di partire.
  6. Notifiche push
    La notifica parte verso il browser o il telefono.
  7. Registri tracciabili
    L'effetto viene liquidato in base al risultato reale dell'invio.

Una sessione Live delegata

Il percorso delegato: il browser parla con il fornitore e ogni richiesta torna al grafo.

  1. Applicazione web
    La persona apre una sessione Live.
  2. Trasporti Live
    L'API emette un identificativo monouso e compone il mandato della voce.
  3. Trasporti Live
    Il browser apre il trasporto del fornitore (WebSocket o WebRTC).
  4. API FastAPI per domini
    Una richiesta delegata diventa un turno di chat ordinario.
  5. Grafo LangGraph
    Il grafo la esegue con le sue validazioni e i suoi registri.
  6. Trasporti Live
    La risposta, limitata e appiattita, viene restituita alla voce.
  7. Job durevoli
    Alla fine, un'unica chiusura archivia, quantifica e inoltra.

Dal commit alla produzione

Ogni guardia gira prima del push; nulla viene pubblicato senza qualifica.

  1. Integrazione continua e guardie
    L'hook e la CI eseguono gli stessi comandi Task: lint, ratchet, test.
  2. Integrazione continua e guardie
    Sul tag, le immagini candidate vengono costruite ed etichettate per impronta.
  3. Release, deployment e installer
    Un'installazione usa e getta qualifica il candidato.
  4. Release, deployment e installer
    La release verifica le prove e pubblica i tag di versione.
  5. Immagini e composizione
    Le immagini fissate vengono scaricate sul server.
  6. Release, deployment e installer
    Il deployment distaccato scrive il suo verdetto in un file che viene riletto.
  7. Demo pubblica
    La demo viene ridistribuita e verificata.

Vedere, allertare, diagnosticarsi

Ogni segnale ha un lettore; un allarme ha un runbook; LIA legge le proprie prove.

  1. Metriche
    I processi pubblicano le loro metriche, memoria compresa.
  2. Log
    I log strutturati, senza dati personali, arrivano a Loki.
  3. Dashboard
    Grafana mostra ogni sottosistema.
  4. Allarmi
    Un allarme parte con il suo runbook.
  5. Autodiagnosi
    LIA raccoglie le prove dell'incidente e lo diagnostica.

Eseguire un comando applicativo

Identità durevole e precondizioni attuali; una prosecuzione aperta resta in attesa.

  1. Applicazione web
    Il client usa il catalogo di operazioni offerto a questo account.
  2. Strumenti e manifest
    La dichiarazione fissa operazione, schema, ambito e capacità richieste.
  3. Comandi applicativi durevoli
    La preparazione lega valori prima/dopo, digest, attore, origine e scadenza in un comando cifrato.
  4. Validazione e bozze
    Il gate degli effetti verifica l'approvazione esatta quando l'operazione la richiede.
  5. Comandi applicativi durevoli
    L'esecuzione rilegge permessi e capacità; claim vincolato da token e compare-and-set del servizio sorgente proteggono le rispettive frontiere.
  6. Sessioni e autenticazione
    Una prosecuzione privata è legata alla sessione e, se necessario, al dispositivo destinatario; i segreti restano fuori dal modello.
  7. Comandi applicativi durevoli
    Committed, waiting, conflitto, errore e annullamento restano distinti; una risposta persa non viene rieseguita automaticamente.
  8. Applicazione web
    Un segnale indirizzato invalida le risorse interessate; il client rilegge le relative query autenticate.