De 125 documentos a una app en TestFlight en ~300 horas: plataforma de lealtad para un bar

Un bar de Manzanillo llevaba años con la misma relación con su clientela: buena, cercana y anónima. No tenía sitio web, la tarjeta de lealtad era de cartón y el negocio no tenía forma de saber quién volvía, qué pedía ni cuándo dejaba de ir. Lo que pedía no era «una app»: quería conocer a sus clientes y tener un motivo para que regresaran.

Este artículo cuenta cómo esa necesidad se volvió una plataforma completa: monedero electrónico, promociones, carta digital, mesas con QR, un panel administrativo y una app para iOS y Android. Pero el tema principal no es la lista de funciones, sino el método: primero se escribió y después se construyó, y cada pieza del sistema remite a un documento que explica por qué existe.

¿Por qué empezar por la documentación?

El primer commit del proyecto no tiene código. Es del 28 de abril de 2026 y dice docs: scaffold inicial de documentación. El segundo ya es una decisión de arquitectura. El código llegó después.

No fue por burocracia. Un producto con dinero de por medio, varios tipos de usuario y la intención de venderse a otros negocios no aguanta que las reglas vivan en la cabeza de una persona. Escribirlas primero obliga a resolver las contradicciones cuando cuestan una conversación y no una migración.

Hoy el repositorio de documentación tiene 125 documentos y unas 17,500 líneas, organizados en diez secciones numeradas:

• Visión y alcance: qué es el producto y, con la misma claridad, qué no es. El documento lo dice textual: no es un e-commerce ni reemplaza a las apps de reparto; no es una caja registradora ni un punto de venta. Esa línea evitó más de una desviación de alcance.
• Producto: personas, historias de usuario, 15 requisitos funcionales numerados y 56 reglas de negocio identificadas, del tipo «un saldo nunca puede quedar negativo» o «una promoción que quita el canje se impone, no se elige».
• Roadmap: un Gantt y una ficha por cada una de las cinco fases, con sus criterios de aceptación.
• Arquitectura, diseño, seguridad, calidad, operaciones y gestión: modelo de datos con diagramas entidad-relación, sistema de diseño, política PCI, definición de hecho, ambientes, cronograma y riesgos.

Las decisiones también se escriben: 58 ADRs

Cada decisión técnica con consecuencias se registra en un ADR (Architecture Decision Record): el contexto, las opciones, la elegida y lo que cuesta. El proyecto lleva 58, con un índice que marca cuáles están aceptados, cuáles propuestos y cuál sustituyó a cuál. Los propuestos declaran qué les falta exactamente para aceptarse.

Tres ejemplos de por qué vale la pena:

• La app móvil cambió de motor de WebView (ADR-0026). La librería original no garantizaba inyectar el puente nativo antes de que arrancara la app web en iOS. La nueva sí. Sin el ADR, dentro de un año alguien «simplificaría» la dependencia y rompería las notificaciones sin saber por qué.
• La tarjeta nunca toca nuestro servidor (ADR-0024). El cobro usa el formulario embebido de Stripe dentro de la app. El backend solo ve la confirmación, así que queda fuera del alcance de la certificación PCI.
• Las pruebas corren contra el sistema desplegado, con datos sintéticos (ADR-0035). Hay identidades de prueba que inician sesión sin OTP, protegidas por tres candados. Sus datos quedan marcados desde el servidor e invisibles para el negocio. Así las pruebas automáticas recorren el sistema desplegado de verdad sin mandar un solo WhatsApp, y la misma estrategia seguirá sirviendo en producción.

El cliente lee su propia documentación

La documentación no se queda en el repositorio. Una parte se publica como un sitio para el cliente: visión, producto, roadmap, avances con video y una lista de pendientes que se van marcando como resueltos. El sitio mide qué secciones se leen, y eso dice qué conviene explicar mejor en la siguiente reunión.

El camino también va en sentido contrario. Las notas de voz del dueño se guardan en el proyecto como fuente de requerimiento, con fecha y tema, y al menos un ADR nació textualmente de una de ellas. Para las promociones se diseñaron diez tarjetas visuales, una por variante (precio especial en pesos o en puntos, cupo limitado, puntos dobles por día, bono de recarga…). En una reunión, el cliente aprobó las diez de un vistazo. Aprobar un requerimiento viendo una imagen es mucho más fácil que leyendo una especificación.

Qué se construyó

APIs: Laravel 12 sin servidores

Tres APIs en Laravel 12 corriendo en AWS Lambda con Bref, con unos 86 endpoints en total:

• Fidelización: registro, monedero, catálogo, carrito, mesas, invitaciones, dispositivos y pagos.
• Backoffice: todo lo que opera el negocio.
• Identidad: inicio de sesión sin contraseña, con código por WhatsApp.

El corazón es el monedero con dos bolsas, dinero y puntos, sobre un ledger de solo inserción. Ningún movimiento se edita ni se borra, cada abono es idempotente —el mismo evento no puede acreditarse dos veces— y la base de datos rechaza cualquier saldo negativo. Un error de redondeo no se «arregla» a mano: se corrige con un movimiento que queda en el registro.

Backoffice: el panel del negocio

Una PWA en Quasar y Vue 3 con 11 módulos:

• Operación: clientes con su monedero e historial, carta (secciones, productos, presentaciones y fotos, con precio en pesos y en puntos), promociones con recurrencia, sucursales y mesas.
• Control: indicadores y bitácora de auditoría.

Los accesos se controlan con 4 roles y 17 permisos, y el panel le pregunta al backend qué puede hacer cada usuario en vez de adivinarlo.

La pantalla del mesero es la más operativa: abre una mesa, muestra su QR y un código de cuatro dígitos, imprime el ticket en papel de 58 u 80 mm y la cierra.

App del socio

Una app web de 18 pantallas pensada para el pulgar:

• Registro en seis pasos, con rueda de fecha y validación de mayoría de edad.
• Carnet de socio con saldo en dinero y en puntos.
• Carta con búsqueda, doble precio, banda de promoción y un aviso de «te alcanza».
• Recarga con tarjeta y historial de movimientos.
• Invitaciones con código para compartir.
• Unirse a una mesa, escaneando el QR o tecleando el código.

App para iOS y Android

Una sola base de código en Flutter envuelve la app web y le da lo que un navegador no puede: notificaciones push, escáner de QR nativo, vibración, el menú de compartir del sistema y el botón «atrás» de Android. La comunicación va por un puente nativo documentado, método por método.

Hay tres variantes de compilación: desarrollo, pruebas y producción, cada una con su nombre e icono. La versión de iOS ya está en TestFlight y la de Android en prueba interna de Google Play.

Infraestructura en la nube

• Cómputo: AWS Lambda detrás de API Gateway, con colas SQS para el trabajo en segundo plano y un bus de EventBridge para los eventos del negocio.
• Datos: PostgreSQL con un schema por negocio y Redis para la configuración cifrada.
• Aplicaciones web: S3 + CloudFront.
• Secretos: gestor de parámetros.
• Despliegue: GitLab CI lanza los trabajos desde Google Cloud Run. Cada ambiente se despliega con un clic deliberado, nunca solo por hacer push.

Una plataforma, no una app a la medida

Desde el primer documento, la meta fue que el sistema se pudiera replicar para otros negocios. Por eso nació multi-tenant: un solo despliegue atiende a varios negocios y resuelve a cuál pertenece cada petición. La multi-tenencia ya está encendida en las cuatro APIs, y la de identidad atiende hoy a dos negocios reales desde el mismo despliegue.

En el camino, lo que servía para cualquier negocio se fue separando en librerías Laravel reutilizables: multi-tenencia, autorización, pagos con pasarela intercambiable, identidades sintéticas, archivos, dispositivos. Esas horas no son un costo exclusivo de este cliente. Son la base con la que el siguiente proyecto arranca con identidad, pagos y pruebas ya resueltos.

Estándares: lo que hace que la velocidad se repita

La documentación del proyecto dice qué construir. Cómo construirlo lo definen los estándares de Mango Binario: 16 documentos, unas 6,000 líneas, que aplican a todos los proyectos y no solo a este:

• Contratos de API: la misma forma de respuesta JSON, el mismo filtrado de listados, la misma autenticación entre servicios y una colección de Postman ejecutable por API, con piezas de OpenAPI y plantillas listas para copiar.
• Código: una guía para APIs en Laravel y otra para apps en Quasar, con la estructura de carpetas, los nombres y los patrones que se esperan.
• Pruebas: cuándo una prueba bloquea un despliegue y cómo se prueba contra el sistema desplegado con datos sintéticos.
• Operación: colas o eventos, bitácoras, entrega de archivos, seguridad de agentes de IA, interfaz por capacidades y hasta cómo se graban los videos de avance para el cliente.

El efecto se nota cada día. Con un estándar escrito, una decisión se toma una vez y no en cada repositorio. La tercera API se parece a la primera, un endpoint nuevo ya sabe cómo responder y cómo paginar, y el pipeline de despliegue ni siquiera se escribe a mano: se genera desde una especificación.

El camino también va al revés: este proyecto mejoró los estándares. Sus pruebas E2E, su control de accesos por capacidades y sus videos de avance quedaron como implementación de referencia para los siguientes proyectos. Lo que aquí se resolvió bien dejó de ser una solución local y se volvió regla.

Los estándares también hacen que el desarrollo asistido por IA rinda. Un asistente que lee reglas explícitas produce código consistente; uno que tiene que adivinar las convenciones produce doce estilos distintos.

Automatizar lo que siempre debe salir igual

Un estándar escrito todavía depende de que alguien lo aplique bien cada vez. Por eso, lo que tiene una sola respuesta correcta no se deja ni a la mano ni a la improvisación de una IA: se vuelve una herramienta determinista. Mismo insumo, mismo resultado, siempre.

El scaffolder: de una especificación a un servicio desplegable

En Mango Binario tenemos nuestro propio scaffolder, una herramienta de línea de comandos que ya va en su versión 1.16. A partir de un YAML pequeño que describe una API o una app —nombre, negocios que atiende, colas, dominios—, genera lo que antes se escribía a mano en cada proyecto:

• el pipeline de integración y despliegue;
• la configuración serverless;
• los parámetros de cada negocio en la nube;
• las ramas de cada ambiente, con su protección;
• el dominio de cada app web.

Además trae comandos de verificación. Antes de desplegar revisa que la especificación sea válida y que existan los secretos y los parámetros; después, que lo desplegado corresponda a lo declarado. Es idempotente: se puede correr de nuevo sin romper nada y retoma donde se quedó si algo falla.

Los pipelines de las APIs y de las apps web del proyecto empiezan con la misma advertencia: generado desde la especificación, no editar a mano. Nadie los escribió. Una API nueva no hereda los errores de copiar y pegar la anterior, y una corrección en la plantilla llega a todos los servicios la próxima vez que se generan.

Las skills de entrega: el último paso también está escrito

Entregar un cambio tiene muchos pasos fáciles de hacer mal: crear la rama desde donde toca, escribir el commit con la convención, abrir el MR, integrarlo en un solo commit, calcular la siguiente versión y etiquetarla. Esos pasos viven en cuatro skills —procedimientos escritos que el asistente de IA ejecuta al pie de la letra—, una por cada forma de entregar:

La versión no se elige a ojo: sale del tipo de commit. Una función nueva sube la versión menor, una corrección sube el parche y un cambio incompatible sube la mayor. Las skills también protegen lo que no se ve. Por ejemplo, nunca integran una rama de ambiente con un MR, porque eso borraría la rama y cerraría en silencio el MR hacia producción. Y antes de cualquier acción que no se puede deshacer, presentan el plan y esperan confirmación.

El resultado es medible: los repositorios del cliente suman 260 versiones etiquetadas, y cada una remite a un commit que dice qué cambió y por qué.

La división del trabajo queda clara: la IA pone el criterio donde hace falta criterio, y las herramientas deterministas se encargan de lo que tiene que salir idéntico.

Calidad: pruebas y errores contados con honestidad

• 145 archivos de pruebas en PHP (Pest) entre las dos APIs principales.
• 39 specs de Cypress entre el panel y la app, algunos contra el ambiente vivo.
• 146 aserciones en la colección de Postman del backoffice, que corre en cada integración.

La bitácora del proyecto también registra lo que las pruebas no vieron, con su corrección y la razón:

• Un seeder que resucitaba productos dados de baja.
• Dos de las diez promociones que, en silencio, no repartían puntos.
• La zona horaria que se tomaba del reloj del teléfono y no del negocio, que llegó a la rama principal porque las pruebas de la app todavía no corren en integración continua.

Esa deuda está anotada como tal, con nombre y apellido. Documentar un error es la única forma de que no se repita.

El proyecto en números

Cinco meses de calendario, ~300 horas de trabajo

Visto por calendario, el proyecto lleva 20 semanas: del 28 de abril al 15 de septiembre. Pero no fue un trabajo de tiempo completo. Se construyó en tiempos libres: dos de cada tres commits caen fuera del horario laboral de lunes a viernes, más de 350 se hicieron entre las seis de la tarde y la medianoche, y el sábado es el segundo día con más actividad de la semana.

Para medir el esfuerzo real, reunimos en una sola línea de tiempo los commits de los 25 repositorios del proyecto (los del cliente, las APIs de plataforma y las librerías) y los agrupamos en sesiones de trabajo:

Unas 300 horas son unas 15 horas a la semana y equivalen a siete u ocho semanas de jornada completa. De ellas, alrededor de 250 corresponden a los repositorios propios del cliente, y el resto a la base de plataforma que se queda para los próximos proyectos.

Esa velocidad sale de cuatro cosas juntas:

1. Experiencia: saber qué problemas vienen antes de toparse con ellos.
2. Documentación previa: nunca se programó sin saber qué se estaba construyendo.
3. Estándares escritos y automatizados: cada decisión repetible se tomó una sola vez, y el scaffolder y las skills de entrega la aplican igual en todos los repositorios.
4. Desarrollo asistido por IA, declarado abiertamente: más de la mitad de los commits llevan coautoría de Claude. La IA acelera la escritura, pero las decisiones —y los 58 ADRs que las explican— siguen siendo del desarrollador.

¿Dónde está hoy?

• Fases 0, 1 y 2 cerradas: descubrimiento, registro y monedero.
• Fase 3 en curso: promociones y backoffice. Ya operan accesos, clientes, carta, promociones, sucursales y mesas; faltan campañas y cobro en mesa.
• Fase 4 pendiente: sitio público y publicación en tiendas, aunque la app ya está en TestFlight y en prueba interna de Android.

Por eso este caso de estudio no tiene liga en vivo. Todo corre en los ambientes de desarrollo y de pruebas. El sitio público y las apps en tienda dependen de trámites externos —dominio, cuentas productivas de pagos y de mensajería— que están en curso.

Preguntas Frecuentes

¿Tienes la idea pero todavía no el documento?

Es el mejor momento para hablar. Revisamos juntos qué quieres construir, lo bajamos a un alcance escrito y te decimos con franqueza cuánto cuesta y cuánto tarda.

Agenda 30 minutos, sin costo