Gaia: assistente virtuale AI per Spapperi

Progettazione, hardening e messa in produzione di un assistente conversazionale AI integrato nel sito istituzionale di un produttore di macchine agricole — oltre alla riprogettazione del sito stesso.

Il cliente

SPAPPERI NT S.r.l. — azienda italiana di Città di Castello (PG) specializzata nella produzione di macchine agricole (trapiantatrici, rimorchi, stendifilm, baulatrici, raccoglitrici, sarchiatrici, ecc.), con un catalogo ampio organizzato per linee di business (Orticole, Tabacco, Officinali, Arboree) e dati agronomici strutturati (tipi di trapianto, sesti di impianto, tipi di pianta).

Sito multilingua (IT, EN, FR, DE, ES, PT, ZH) basato su Next.js + Payload CMS, in produzione su VPS con stack Docker (PostgreSQL, Caddy, layer di cache).

Prima e dopo

Abbiamo riprogettato il sito istituzionale e le schede prodotto, modernizzando l'esperienza desktop e mobile.

Homepage — prima

Homepage — dopo

Scheda prodotto — prima

Scheda prodotto — dopo

La sfida

Il cliente voleva un assistente virtuale capace di:

• rispondere su tutto il catalogo prodotti e i dati agronomici senza che l'utente debba navigare il sito;
• indirizzare in modo corretto a contatti, ricambi, candidature e servizi;
• funzionare in 7 lingue;
• essere conforme agli obblighi legali (trasparenza AI, GDPR);
• offrire una UX mobile all'altezza di una chat moderna.

Un primo rilascio aveva raccolto un feedback dettagliato dal cliente (9 punti, con screenshot delle conversazioni) che evidenziava problemi di tono, struttura delle risposte, link errati e mancanza di identità/disclosure dell'AI. In parallelo, l'infrastruttura presentava limiti di scalabilità (cache assente, rate limiting in-memory) e una lacuna di compliance (le informative non menzionavano il chatbot).

La soluzione

1. Identità e qualità conversazionale

Dall'analisi del feedback cliente sono stati derivati interventi mirati sul system prompt e sui tool:

• Identità "Gaia" + disclosure AI: l'assistente si presenta esplicitamente come assistente virtuale AI (obbligo di trasparenza), con nome, avatar dedicato e greeting localizzato in tutte le lingue.
• "Linee di business prima": le risposte sui prodotti vengono inquadrate partendo dalle linee di attività, poi scendono nel dettaglio di serie e modelli.
• Gestione link rigorosa: niente link proattivi se non richiesti; URL sempre relativi e validi (eliminati percorsi che generavano 404); rimossi riferimenti a pagine non più esistenti.
• Ricambi: instradamento diretto alla piattaforma ricambi ufficiale invece della generica sezione servizi.
• Recupero multi-modello: il tool di dettaglio macchina accetta più modelli in un'unica richiesta, così domande come "scheda tecnica di AS PT e AS AT" restituiscono tutti i modelli con i rispettivi cataloghi.
• Niente leakage tecnico: eliminata la comparsa di marcatori interni ([slug:...]) nel testo mostrato all'utente.

2. Performance: caching su Redis

Ogni messaggio ricostruiva il contesto con ~11 query al CMS. È stato introdotto un servizio Redis nell'infrastruttura Docker e un caching a due livelli:

• System prompt cacheato per lingua;
• Risposte FAQ (primo turno) servite dalla cache, saltando del tutto il modello;
• Invalidazione automatica: hook sulle collection/globals sorgente del chatbot azzerano la cache a ogni modifica dei contenuti nel CMS;
• Fallback graceful: se Redis è irraggiungibile, l'app continua a funzionare senza cache (mai un errore in faccia all'utente).

3. Sicurezza: rate limiting distribuito

Il rate limiting in-memory (che si azzerava a ogni deploy e non reggeva più istanze) è stato migrato su Redis con script Lua atomico, condiviso tra processi e persistente, con fallback in-memory. Copre ~17 endpoint API (contatti, ricerca, login area riservata, candidature, GDPR, ecc.).

4. Compliance GDPR

Le informative legali non menzionavano il trattamento via chatbot. Sono state inserite, nei punti corretti dei documenti (non in coda) e in tutte e 7 le lingue:

• Privacy Policy: nuova sotto-sezione sui dati trattati dall'assistente, riga nelle tabelle "Finalità" e "Conservazione", OpenAI tra i responsabili e nei trasferimenti extra-UE;
• Cookie Policy: righe nella tabella delle tecnologie tecniche per il localStorage del widget;
• Termini di Servizio: clausola dedicata all'assistente AI (carattere informativo, non vincolante).

L'inserimento è avvenuto tramite uno script idempotente che individua sezioni e tabelle in modo robusto su tutte le lingue, con backup preventivo dei contenuti.

5. UX/UI mobile

Esperienza ridisegnata in stile chat moderna:

• pannello fullscreen su mobile;
• niente zoom indesiderato all'apertura della tastiera (input a 16px);
• layout stabile con tastiera aperta (altezza ancorata al viewport visibile);
• animazione di apertura/chiusura;
• avatar dedicato di Gaia (header + launcher).

6. Messa in produzione

Deploy controllato sul VPS: backup del database di produzione, sincronizzazione del codice (esclusi segreti e volumi runtime), allineamento dati e rebuild Docker con avvio del nuovo servizio Redis — senza perdita di dati e con verifiche end-to-end (container healthy, cache popolata, pagine legali aggiornate, chatbot operativo).

Risultati

• Identità e compliance: l'assistente si dichiara AI in tutte le lingue; colmata la lacuna GDPR su 3 documenti legali × 7 lingue (21 aggiornamenti, 0 anomalie).
• Performance: il costo per messaggio crolla sulle richieste ripetute grazie a due livelli di cache, con coerenza garantita dall'invalidazione automatica.
• Robustezza: rate limiting ora distribuito e persistente; cache e rate limiting degradano in modo sicuro se Redis non è disponibile.
• Qualità risposte: risolti i punti di feedback risolvibili lato prodotto (identità, struttura, link, ricambi, multi-modello, niente leakage tecnico).
• UX mobile: esperienza chat fluida, senza zoom e senza rotture di layout con la tastiera.
• Zero downtime percepibile e zero perdita dati in fase di rilascio.

Stack tecnologico

Ambito	Tecnologie
Frontend	Next.js (App Router), React, framer-motion
CMS / Backend	Payload CMS, PostgreSQL
AI	OpenAI (function calling / tool use)
Caching & rate limiting	Redis (ioredis, script Lua)
Infrastruttura	Docker Compose, Caddy, layer di cache, VPS
i18n	7 lingue (IT, EN, FR, DE, ES, PT, ZH)

In sintesi

Da un primo prototipo con feedback aperto a un assistente AI identificabile, conforme, performante e robusto, integrato col catalogo reale del cliente e rilasciato in produzione in sicurezza. L'architettura introdotta (Redis, hook di invalidazione, fallback graceful, rate limiting distribuito) costituisce inoltre una base riutilizzabile per ulteriori funzionalità (token monouso, anti-abuso, caching di pagine pesanti, analytics).

Chatbot "Gaia" — RayoChat by Rayo Consulting.