Assistent D’en Iman
— Xatbot Integrat —

Objectiu del Projecte

L’objectiu d’aquest projecte era dissenyar, programar i integrar un xatbot basat en IA dins d’una pàgina web real. El xatbot, anomenat Assistent D’en Iman, utilitza la API de Google Gemini per generar respostes intel·ligents en temps real.

Per fer-ho possible, cal resoldre un problema tècnic fonamental: un navegador web no pot parlar directament amb una API externa sense exposar les claus secretes. La solució és crear un servidor intermediari (BackEnd) que faci de pont segur entre el widget del lloc web i la IA.

Tecnologies Utilitzades

Arquitectura i Flux de Dades

El sistema es divideix en tres capes independents que es comuniquen entre elles. Entendre aquesta separació és clau per poder argumentar la solidesa del disseny.

Flux pas a pas

1. Usuari escriu un missatge

   L’usuari introdueix una pregunta al widget de xat integrat a la web de WordPress. El JavaScript captura l’event click del botó d’enviament.

2. Fetch POST → BackEnd (via ngrok)

   El JS envia una petició POST a l’endpoint /ask del servidor Flask, amb el missatge en format JSON. La URL és el túnel públic generat per ngrok.

3. Flask rep la petició i crida Gemini

   El servidor extreu el missatge, l’envia a la API de Gemini (model gemini-1.5-flash) i espera la resposta. La clau API mai surt del servidor.

4. Resposta retorna al widget

   Flask retorna la resposta en JSON ({"reply": "..."}). El JavaScript la rep i la mostra al xat en temps real.

BackEnd: Servidor Flask a Google Colab

Pas 1 — Instal·lació de dependències

El primer pas al notebook de Colab és instal·lar les llibreries necessàries. Cada una té un rol específic i necessari:

// EVIDÈNCIA 01 · Instal·lació de dependències al Google Colab

# Instal·lació de totes les dependències necessàries
!pip install flask flask-cors google-generativeai pyngrok

Pas 2 — Codi principal del servidor

// EVIDÈNCIA 02 · Codi del servidor Flask amb Gemini i ngrok a Google Colab

import os
from flask import Flask, request, jsonify
from flask_cors import CORS
from pyngrok import ngrok
import google.generativeai as genai
from google.colab import userdata

# 1. Carreguem les claus des dels Secrets de Colab (mai hardcoded!)
GOOGLE_DATA  = userdata.get('GOOGLE_API_KEY')
NGROK_TOKEN  = userdata.get('NGROK_AUTH')

genai.configure(api_key=GOOGLE_DATA)
ngrok.set_auth_token(NGROK_TOKEN)

# 2. Creem l'aplicació Flask i habilitem CORS
app = Flask(__name__)
CORS(app)

# 3. Definim l'endpoint /ask
@app.route('/ask', methods=['POST'])
def ask_api():
    try:
        user_data   = request.json
        user_prompt = user_data.get("message")

        # 4. Cridem Gemini amb el model flash (ràpid i eficient)
        ai_model = genai.GenerativeModel('gemini-1.5-flash')
        response = ai_model.generate_content(user_prompt)

        return jsonify({"reply": response.text})
    except Exception as e:
        return jsonify({"error": str(e)}), 500

# 5. Obrim el túnel ngrok i arrenquem Flask
public_url = ngrok.connect(5000)
print(f"URL pública: {public_url}")
app.run(port=5000)

Gestió d’errors i robustesa

Un servidor de producció ha de gestionar els errors correctament. El bloc try/except garanteix que si la API de Gemini falla, el widget rebrà un missatge d’error llegible en lloc de quedar-se penjat. El codi HTTP 500 informa el FrontEnd que hi ha hagut un error al servidor.

FrontEnd: Widget de Xat

El FrontEnd és la capa visible per a l’usuari: un widget de xat flotant que apareix a la cantonada de la web i permet interactuar amb l’assistent de IA. Està fet amb HTML, CSS i JavaScript pur, sense cap framework extern.

// EVIDÈNCIA 03 · Widget visible a la web

// EVIDÈNCIA 04 · Estructura HTML del widget

Estructura HTML

<!-- Contenidor principal del widget -->
<div id="iman-chat-container">

  <!-- Finestra del xat (inicialment amagada) -->
  <div id="iman-chat-window" style="display: none;">
    <div id="iman-chat-header">
      <img src="[logo]">
      <span>Assistent d'en Iman</span>
    </div>

    <!-- Aquí apareixeran els missatges dinàmicament -->
    <div id="iman-chat-messages"></div>

    <div id="iman-chat-footer">
      <input type="text" id="iman-chat-input"
             placeholder="Escriu aquí...">
      <button id="iman-chat-send">►</button>
    </div>
  </div>

  <!-- Botó flotant per obrir/tancar el xat -->
  <button id="iman-chat-trigger">[logo]</button>
</div>

Lògica JavaScript

// EVIDÈNCIA 05 · JavaScript del widget (footer de WordPress via WPCode)

// Referència als elements del DOM
const triggerBtn    = document.getElementById('iman-chat-trigger');
const chatWin       = document.getElementById('iman-chat-window');
const chatInput     = document.getElementById('iman-chat-input');
const chatSend      = document.getElementById('iman-chat-send');
const chatMessages  = document.getElementById('iman-chat-messages');

// Obrir / tancar el widget en clicar el botó flotant
triggerBtn.onclick = (e) => {
  e.preventDefault();
  chatWin.style.display =
    (chatWin.style.display === 'none' || chatWin.style.display === '')
      ? 'flex' : 'none';
};

// Enviar missatge al BackEnd i mostrar la resposta
chatSend.onclick = async () => {
  const msg = chatInput.value.trim();
  if (!msg) return;

  addMessage(msg, 'user');
  chatInput.value = '';

  const res = await fetch('[URL_NGROK]/ask', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ message: msg })
  });
  const data = await res.json();
  addMessage(data.reply, 'bot');
};

// Helper per afegir un missatge al xat
function addMessage(text, sender) {
  const div = document.createElement('div');
  div.className = `msg ${sender}`;
  div.textContent = text;
  chatMessages.appendChild(div);
  chatMessages.scrollTop = chatMessages.scrollHeight;
}

Seguretat de les Claus API

La seguretat és un dels punts crítics del projecte. Una clau API exposada pot generar costos econòmics importants i comprometre el compte de Google. Per això, es van implementar dos nivells de protecció:

// EVIDÈNCIA 06 · Claus guardades als Secrets de Colab

Nivell 1 — Secrets de Google Colab

Les claus API es guarden al gestor de Secrets de Colab (icona del cadenat) i s’accedeix a elles amb userdata.get('NOM_SECRET'). Això significa que:

• Les claus mai apareixen al codi font del notebook.
• Si es comparteix el notebook, les claus no es comparteixen.
• El codi font és llegible sense risc de seguretat.

# ✅ Correcte: carregant des de Secrets
GOOGLE_DATA = userdata.get('GOOGLE_API_KEY')
NGROK_TOKEN = userdata.get('NGROK_AUTH')

# ❌ Incorrecte (mai fer això!): clau hardcoded al codi
# GOOGLE_DATA = "AIzaSy..."  ← RISC DE SEGURETAT GREU

Nivell 2 — Arquitectura BackEnd com a escud

El disseny de separar FrontEnd i BackEnd garanteix que la clau API de Gemini mai arribi al navegador de l’usuari. Si s’hagués cridat la API de Gemini directament des del JavaScript del widget, qualsevol persona podria obrir les DevTools del navegador i robar la clau.

Integració a WordPress via WPCode

// WPCode — Plugin utilitzat per injectar el codi del widget

// EVIDÈNCIA 07 · HTML del widget inserit via WPCode (Header/Footer)

Per què WPCode i no editar el tema?

WordPress permet afegir codi directament als fitxers del tema (functions.php, header.php…), però aquesta pràctica té desavantatges importants:

• Si actualitzes el tema, perds els canvis — els temes s’actualitzen i sobreescriuen els fitxers modificats.
• Dificultat de manteniment — barrejar codi propi amb el del tema fa difícil depurar errors.

WPCode soluciona tots dos problemes: permet afegir snippets de codi que sobreviuen a les actualitzacions del tema i estan organitzats de manera independent.

Estructura d’injecció

Reflexió i Justificació Tècnica

Per què aquesta arquitectura?

La separació en tres capes (Widget ↔ Flask ↔ Gemini) no és una elecció arbitrària — és el patró arquitectònic estàndard de qualsevol aplicació web moderna. Cada capa té una responsabilitat única i ben definida:

• ✓
  Widget (FrontEnd): Presentació i experiència d’usuari. No sap res de com funciona la IA — només sap enviar missatges i mostrar respostes.
• ✓
  Flask (BackEnd): Lògica de negoci i seguretat. Valida les peticions, protegeix les claus, gestiona errors. Actua com a “guarda de seguretat”.
• ✓
  Gemini (API externa): Servei especialitzat. Fa la part computacionalment costosa (la IA) sense que el nostre codi n’hagi de tenir res.

Funció d’ngrok i la seva importància

ngrok no és un “hack” ni una solució temporal — és una eina professional àmpliament utilitzada en el món del desenvolupament per a prototipatge, demos i proves. La seva funció en aquest projecte és clara: Google Colab proporciona potència computacional gratuïta però en un entorn aïllat sense IP pública. ngrok connecta aquest entorn aïllat amb el món exterior de manera segura.

Limitacions actuals i millores futures

Resum d’Evidències

A continuació es presenta un resum organitzat de totes les captures de pantalla incloses en aquesta documentació, amb la seva localització dins del document.

E01 · Instal·lació dependències (Colab)

E02 · Servidor Flask + Gemini + ngrok

E03 · Widget del xatbot actiu a la web

E04 · Estructura HTML del widget (WPCode)

E05 · JavaScript del widget (footer WP)

E06 · Integració WPCode a WordPress

E07 · Plugin WPCode (eina d’integració)

E08 · Rúbrica del repte (referència PRO+)

Criteris PRO+ assolits

// Rúbrica oficial del repte — tots els criteris PRO+ documentats

• ✓
  Arquitectura justificada: Cada component (Widget, Flask, JSON) ha estat explicat com a part d’un ecosistema, no com a element aïllat.
• ✓
  Connexió robusta i estable: L’endpoint de Flask rep les dades i les retorna correctament via el túnel ngrok.
• ✓
  Integració perfecta a WordPress: El xatbot s’insereix via WPCode sense conflictes ni errors.
• ✓
  Claus API protegides: Les claus de Gemini i ngrok estan als Secrets de Colab, invisibles al JS del client.
• ✓
  Gestió d’errors: El servidor retorna errors HTTP estàndard i el FrontEnd els gestiona adequadament.
• ✓
  Reflexió i responsabilitat ètica: S’ha argumentat la importància de la seguretat de les claus API com a responsabilitat professional.
• ✓
  Documentació completa: Captures de pantalla, codi comentat, explicacions de cada decisió tècnica.