Diagrama de Arquitectura

Componentes del diagrama

App de Telegram (cliente): es la interfaz del cliente del restaurante. Ahí pide el menú, elige los productos, da sus datos de entrega y confirma el pedido. También recibe las respuestas del bot y los avisos de estado del pedido. Es de terceros.

Telegram Bot API: reenvía cada mensaje del cliente al webhook del backend y entrega en el chat los mensajes del bot. Es de terceros.

TelegramRouter: expone POST /api/v1/telegram/webhook, que es por donde llegan los mensajes de Telegram. Verifica el token secreto del webhook (TELEGRAM_WEBHOOK_SECRET) y deja el mensaje procesándose en segundo plano, para responderle enseguida a Telegram.

TelegramService: coordina la respuesta a cada mensaje. Muestra "escribiendo…" en el chat mientras espera, le pide la respuesta al ChatService y la envía con sendMessage. Si algo falla, le manda al cliente un mensaje de disculpa.

ChatService: es el agente de IA, armado con LangChain. Arma el prompt con las instrucciones del bot, el menú vigente y la memoria de la conversación, y se lo manda a Gemini. Si Gemini pide usar una herramienta, la ejecuta y le devuelve el resultado, hasta tener la respuesta final para el cliente.

SesionChat: guarda la memoria de cada conversación, identificada por el chat_id de Telegram. Recuerda los datos del cliente, el pedido en curso, el último pedido registrado y los 12 mensajes más recientes. Después de 2 horas sin actividad olvida la charla y el pedido a medio armar, pero conserva los datos del cliente.

Herramientas (tools del agente): son las funciones que Gemini puede pedir que se ejecuten:

• calcular_y_preparar_pedido: calcula los precios y el total con los valores de la base y valida el horario programado. Con eso arma el resumen que se le muestra al cliente.
• confirmar_y_guardar_pedido: cuando el cliente confirma el resumen, registra el pedido en la base con estado "Pendiente". obtener_menu_actual: lee los productos activos con su precio y categoría.

OrderNotificationService: avisa al cliente por Telegram cuando el local cambia el estado de su pedido: aceptado (con la demora estimada o el horario programado), rechazado, en camino o listo para retirar.

Panel de Comandas (empleado del local): es el tablero web donde el empleado ve los pedidos pendientes y los acepta o rechaza con PATCH /orders/{id}/status. Ese cambio de estado dispara la notificación al cliente.

Google Gemini API: interpreta los mensajes del cliente y decide qué responder o qué herramienta usar (gemini-3.5-flash-lite). Es de terceros.

PostgreSQL: es la base de datos del sistema. Guarda el menú (products, categories), los pedidos (orders) y los productos de cada pedido (order_items).