Fill Good

Fill Good es una app web instalable para llevar la casa entre varias personas: qué hay en la despensa y cuándo caduca, qué falta en la lista de la compra, cuánto costó cada cosa en cada súper y qué se come esta semana. La foto del ticket al salir del súper pone al día la despensa y el historial de precios de una vez.

Está en producción desde julio de 2026. La interfaz está en español y se diseñó primero para el móvil; en escritorio, la barra inferior pasa a ser un panel lateral y las hojas que suben desde abajo, diálogos centrados.

Qué hace

• Haces una foto del ticket (o subes el PDF, o lo compartes desde otra app) y Gemini lo convierte en productos con cantidad y precio. Lo revisas, lo confirmas y entra en la despensa y en el historial de precios. Los nombres que corriges se recuerdan para el siguiente ticket.
• La despensa marca con un semáforo lo que caduca y, si activas las notificaciones, avisa cada mañana. Una vez por semana pregunta por un máximo de ocho productos que llevan tiempo sin tocarse, porque fuera de los tickets y del modo cocinado nadie apunta el yogur que se come.
• La lista de la compra se comparte con toda la casa y los cambios llegan al momento a todos los móviles. Tiene modo compra y sugiere lo que se está acabando.
• Cada compra queda en el historial del producto, súper a súper, y la app señala dónde sale más barato. El perfil enseña el gasto del mes frente al presupuesto del hogar, y el día 1 un aviso lleva al resumen del mes que acaba de cerrarse.
• Gemini propone el menú de la semana con el recetario del hogar, lo que hay en casa y lo que ya está en la lista, y respeta reglas del tipo «lentejas al menos una vez por semana». La app calcula lo que cuesta la semana y apunta en la lista lo que falta.
• Las recetas tienen modo cocinado: paso a paso, con temporizadores sacados del propio texto, y al terminar propone qué descontar de la despensa. La IA rellena las cantidades y los pasos que falten.
• Un hogar se comparte con un código de invitación, y una misma persona puede estar en varios.
• La skill de Alexa, de momento en modo desarrollo, lleva la despensa sin tocar el móvil: «Alexa, dile a mi despensa que reste dos yogures».
• Antes de mandar nada a Gemini, la app pide consentimiento, porque en el plan gratuito Google puede revisar lo que recibe y entrenar con ello. De las fotos se quitan antes los metadatos, ubicación incluida. Los datos se pueden exportar y la cuenta se borra desde los ajustes.

Capturas de la portada pública, con datos de ejemplo. El resto de la app necesita cuenta.

Stack

• Next.js 16 con App Router, Server Components y Server Actions, sobre React 19 y TypeScript.
• Tailwind CSS 4 y shadcn/ui, con tokens semánticos para los dos temas.
• Supabase: Postgres con Row Level Security por hogar, y Realtime para la lista.
• Clerk para la autenticación, conectado a Supabase con su integración nativa: las políticas de RLS evalúan el propio token de Clerk.
• Vercel AI SDK con Gemini en el plan gratuito: 3.5 Flash para menús y recetas, 3.5 Flash-Lite para tickets. El modelo de cada tarea se cambia con una variable de entorno.
• Serwist para la PWA (instalación, página sin conexión y compartir tickets desde otras apps) y Web Push para los avisos.
• Vercel y Supabase en Fráncfort, con Vercel Cron para los avisos de caducidad y el resumen mensual.

Las lecturas van en Server Components y las escrituras en Server Actions. Toda consulta a una tabla con household_id filtra además por el hogar activo: la RLS solo comprueba que eres miembro, y quien está en dos hogares vería las filas de los dos mezcladas.

Algunas decisiones

El calendario es el de España, corra donde corra el código. El servidor está en UTC y el móvil en Madrid. Mientras cada uno leyó su propio reloj, entre las 00:00 y las 02:00 las pantallas se contradecían: la interfaz ofrecía «Lo cocinamos» y la acción respondía que ese día todavía no había pasado. Ahora todas las fechas salen de src/lib/dates.ts, y npm run check:fechas lo comprueba en UTC, Madrid y Nueva York, porque en un portátil español el fallo no existe. Rompiendo la función a propósito, salen 0 fallos en Madrid y 11 en UTC.

Un export type tumbó toda la IA en producción. En un módulo "use server", Next.js trata cada exportación como una acción, y un export type { X }; sin from apunta a algo que TypeScript ya ha borrado. El módulo muere al evaluarse y se lleva por delante todas las acciones de las páginas que lo importan. tsc, el lint y next build lo dieron por bueno, porque el módulo no se evalúa hasta que alguien pulsa un botón. Desde entonces npm run check:acciones va en el CI.

La lista de la compra es del cliente. Con dos personas cambiándola a la vez, recargar la ruta en cada cambio daba tirones y resucitaba cosas, como la respuesta tardía del servidor que devolvía lo que acababas de quitar. El servidor manda cambios de una fila, las instantáneas completas se funden con las reglas de list-sync.ts y npm run check:lista reproduce las carreras que rompían la lista.

Un cambio de modelo se mide antes de hacerlo. npm run compare:menu genera semanas reales con varios modelos, con el mismo prompt y el schema de producción, y las puntúa con el código del repo, sin que ningún modelo juzgue a otro. En agosto de 2026, Gemini 3.6 Flash empató con 3.5 en todo lo que se podía contar, pero tardó entre 35 y 105 segundos por menú frente a 31–38, y la Server Action corta a los 60. Se quedó 3.5. De paso salieron tres fallos del prompt, dos de ellos tapados por un rescate silencioso.

El nombre de una línea de ticket es la clave con la que se reconoce el producto. Con el peso y el importe dentro, 119 de los 125 nombres aprendidos de un hogar no podían volver a coincidir nunca. src/lib/receipt-label.ts recorta lo que añade la báscula y deja el gramaje del nombre comercial (ESPIRALES 500G se queda, 0,990 kg x 2,29 €/kg se va), y npm run check:rotulos lo fija con líneas reales de Mercadona, Alipende y tickets en catalán.

AGENTS.md cuenta el porqué de estas y del resto de reglas, con los fallos que las motivaron.

Calidad

Cada push a main y cada pull request pasan por tres trabajos de CI: lint y tipos, comprobaciones de reglas, y build de producción con presupuesto de bundle.

El lint lleva jsx-a11y en modo estricto y no admite ni un aviso, así que una regresión de accesibilidad rompe el CI. Lo que el lint no ve de WCAG 2.2 AA (el foco, el contraste real en los dos temas, los objetivos táctiles de 44 px) se revisa a mano.

Las comprobaciones check:* ejecutan el TypeScript del repo con Supabase y Clerk falseados, sin base de datos ni credenciales, y tardan segundos. Cada una defiende una regla que ni el compilador ni el lint pueden ver:

Comprobación	Qué defiende
check:fechas	El calendario español, ejecutado en tres zonas horarias
check:lista	La lista compartida frente a respuestas tardías y cambios cruzados
check:guardas	Server Actions reales: no pisan lo ya cocinado ni dan por hecha una escritura que no tocó nada
check:menu	Lo que sabe la IA antes de planificar y las reglas que reescriben la semana
check:cocinado	Cuánto se descuenta de la despensa al cocinar, y en qué unidad
check:cocina	El modo cocinado: por dónde se retoma, qué ofrece al terminar y qué tiempos detecta
check:repaso	Por qué productos pregunta el repaso semanal de despensa
check:motivos	El texto que explica por qué se sugiere algo en la lista
check:rotulos	La clave con la que se reconocen los nombres de los tickets
check:receta-ia	Que la IA complete cantidades sin renombrar los ingredientes
check:alexa	El estado de la conversación con Alexa
check:acciones	Que un módulo "use server" solo exporte acciones

check:bundle compara con un presupuesto el JavaScript que comparten todas las rutas y el de cada layout, y check:legal impide desplegar los textos legales sin los datos del responsable.

Antes de cualquier git push que lance Claude Code, un hook ejecuta el build de producción con esas comprobaciones y bloquea la subida si falla, porque main despliega directo a producción.

Estructura

src/app/                  Rutas (App Router); (app)/ es la parte con sesión
src/features/<feature>/   components/, actions.ts, queries.ts y schemas.ts
src/components/           UI compartida; ui/ son los componentes de shadcn
src/lib/                  Clientes de Supabase, IA, fechas, medición de uso…
supabase/migrations/      Esquema, políticas de RLS y funciones
scripts/                  Las comprobaciones check:* y utilidades
docs/                     Skill de Alexa, especificaciones y planes ya cerrados

Ejecutarlo en local

El repo está publicado para enseñarlo, pero se puede arrancar. Hace falta Node 24 y cuentas gratuitas en Supabase, Clerk y Google AI Studio.

npm ci
cp .env.example .env.local        # cada variable lleva su explicación
npx supabase login
npx supabase link --project-ref <tu-proyecto>
npx supabase db push              # aplica las migraciones
npm run dev

Clerk se conecta a Supabase como proveedor externo de autenticación (guía de Supabase). Las notificaciones y Alexa son opcionales: sin sus variables quedan apagadas. La skill tiene su propia guía en docs/alexa.

Documentación

AGENTS.md es la documentación técnica: convenciones, reglas del sistema de diseño y qué vigila cada comprobación. Es también la guía que lee Claude Code, con el que se desarrolla el proyecto. En docs/historico/ quedan los planes ya ejecutados, como registro de cómo se decidió cada cosa.

Licencia

El repositorio es público para que se pueda leer, pero no tiene licencia de uso: todos los derechos reservados (LICENSE). Sí puedes clonarlo y arrancarlo en tu equipo para evaluarlo o proponer cambios, sin desplegarlo para otros ni redistribuirlo.

Los iconos de producto son de Fluent Emoji, de Microsoft, con licencia MIT, salvo 19 dibujados para la app en assets/product-icons/. Sus avisos de licencia, y los de los componentes de shadcn/ui, están en THIRD-PARTY-NOTICES.md.