Cómo funciona y cómo está hecho
El recetario es una aplicación web deliberadamente simple: rápida, sin dependencias y fácil de mantener. Esta página explica cómo está construida, cómo viajan los datos desde el cuadro de recetas hasta la pantalla del barista, y cómo actualizarla.
La idea: una sola página, sin servidor de aplicación
El recetario es un sitio estático: un archivo HTML, una hoja de estilos, un archivo de JavaScript y los datos de las recetas. No hay base de datos ni un programa corriendo en el servidor que «arme» las páginas. El servidor solo entrega archivos.
Esto se eligió a propósito. Para un recetario de consulta, una app estática es más rápida (no espera a ningún servidor), más confiable (no se «cae» un backend), más barata (no consume recursos) y más fácil de mantener: actualizar las recetas es regenerar un archivo y volver a publicar.
Toda la app pesa alrededor de 100 KB. Carga en un instante incluso con la peor señal de tienda.
Del Excel a la app
Las recetas nacen en un archivo Excel (el cuadro de recetas). Un script de Python lo lee y lo convierte en datos que la app entiende. Este es el recorrido completo:
El script no copia el Excel tal cual: lo interpreta. Recorre cada hoja, agrupa los ingredientes que pertenecen a la misma bebida, detecta qué columnas son tamaños (8 oz, 12 oz, 16 oz…), separa la preparación en pasos y limpia los nombres. El resultado es una lista de recetas con esta forma:
El script también corrige pequeños desórdenes del Excel original (filas traspapeladas, nombres en mayúsculas, celdas combinadas) para que el barista vea siempre la información ordenada.
El stack y por qué
La app está hecha con HTML, CSS y JavaScript puro — sin React, sin frameworks, sin paso de compilación. Los archivos que se escriben son exactamente los que corren en el navegador.
- HTML — la estructura de la página.
- CSS — el diseño: la paleta cálida café y crema, las tarjetas, la ficha que sube desde abajo, las animaciones.
- JavaScript — la lógica: la búsqueda instantánea, los filtros, abrir la ficha y cambiar de tamaño.
- Python — solo del lado de las herramientas, para convertir el Excel. No corre en el servidor ni en el navegador.
¿Por qué tan simple? Porque el problema es simple. Sin frameworks no hay nada que se desactualice, nada que recompilar y cualquiera que sepa HTML puede darle mantenimiento dentro de cinco años. Menos piezas, menos cosas que se rompen.
Cómo funcionan la búsqueda y los filtros
Como las 102 recetas ya están cargadas en el navegador, buscar es instantáneo: no se consulta a ningún servidor. Mientras el barista escribe, la app filtra la lista letra por letra.
Para cada receta se prepara de antemano un texto de búsqueda que junta el nombre, la categoría y todos los ingredientes, sin tildes y en minúsculas. Así «cafe» encuentra «Café» y «matcha» encuentra todas las bebidas que llevan matcha como ingrediente. La búsqueda y el filtro de categoría se combinan: se muestran las recetas que cumplen las dos cosas.
Las tarjetas se crean una sola vez al abrir la app; filtrar solo muestra u oculta las que ya existen. Por eso buscar se siente inmediato.
Por qué funciona sin conexión
El recetario es una PWA (Progressive Web App): una página web que se comporta como una app. Incluye dos piezas clave:
- Un Service Worker (
sw.js): un pequeño programa que el navegador guarda y que cachea los archivos de la app la primera vez que se abre. En las siguientes visitas los sirve desde el dispositivo, funcione o no el wifi. - Un manifiesto (
manifest.webmanifest): le dice al teléfono el nombre, el ícono y los colores, para poder instalar la app en la pantalla de inicio.
El Service Worker usa una estrategia llamada stale-while-revalidate: muestra al instante la versión guardada y, en segundo plano, busca si hay una más nueva. Así la app abre rápido siempre y se mantiene actualizada sola.
Dónde vive y cómo se publica
Los archivos se alojan en un servidor de Espresso Americano en Google Cloud, el mismo que ya hospeda el portal y otros dominios. El servidor web es Caddy, que sirve los archivos del recetario y gestiona el dominio recetas.espressoamericano.cloud.
El recetario se agregó como un sitio nuevo e independiente dentro de Caddy, sin alterar los demás dominios que ya estaban. Caddy emite y renueva el certificado HTTPS automáticamente, así que el sitio siempre carga de forma segura.
La publicación está automatizada con un script (deploy.sh) que
empaqueta el sitio, lo sube al servidor, lo coloca en su carpeta y le pide a
Caddy que recargue — siempre con un respaldo previo y validando la
configuración antes de aplicarla.
Cómo se actualizan las recetas
Cuando cambia el cuadro de recetas, actualizar la app son tres pasos:
Cada publicación renueva la versión del caché del Service Worker, así que las tablets de las tiendas reciben la actualización la próxima vez que abren la app con internet — sin que nadie tenga que hacer nada en cada dispositivo.
Estructura de archivos
Lo único que se genera de forma automática es data/recipes.js (a
partir del Excel) y los íconos. Todo lo demás se escribe a mano y es lo que
realmente corre en el navegador.