01. Visión General del Sistema

Mockups visuales de Vision General

¿Qué es ZEUMAX?

ZEUMAX —también conocido comercialmente como ZEUMAX o ZEUMAX— es una plataforma integral de gestión para el sector de la restauración, la hostelería y el comercio de alimentación. Ha sido diseñado para cubrir todo el ciclo de vida de un pedido, desde que un cliente descubre un producto en la web o escanea un QR en su mesa, hasta que el cocinero prepara el plato, el repartidor lo entrega o el cajero cierra la caja al final del día. El sistema nace de la necesidad de unificar en una sola arquitectura coherente múltiples puntos de contacto que tradicionalmente funcionan de forma aislada: la web de pedidos online, la app de escaneo de mesas, el punto de venta físico (TPV), la gestión de repartidores, la cocina, la administración de sucursales y el panel de control corporativo.

La plataforma no es una simple tienda online ni un TPV desconectado. Es un ecosistema conectado donde cada actor —cliente, mesonero, cajero, cocinero, manager, repartidor y administrador— interactúa con la misma fuente de verdad: un backend central que orquesta productos, precios, stock, pedidos, pagos, impresiones, notificaciones y reportes en tiempo real. Esto significa que cuando un cliente añade un producto al carrito desde su móvil, el cocinero puede ver ese pedido en la Kitchen App segundos después; cuando el cajero cobra una mesa en el TPV, el administrador puede consultar esa venta en el panel web minutos después; y cuando el manager asigna un repartidor desde el Orden Receiver, el conductor recibe la notificación en su app de delivery sin intermediarios manuales.

Este documento es la puerta de entrada al manual de usuario. Su objetivo es ofrecer una visión de pájaro del sistema completo: qué piezas lo componen, quién usa cada pieza, y cómo se relacionan entre sí. Si es la primera vez que interactúas con ZEUMAX, te recomendamos leer esta sección antes de adentrarte en los manuales específicos de cada módulo.

Arquitectura del Sistema

ZEUMAX está construido sobre una arquitectura monolítica moderna con frontends especializados. Un backend/API central actúa como cerebro único, mientras que cada rol o canal de interacción tiene una interfaz optimizada para su contexto de uso: una web pública para pedidos online, una app QR ultraligera para comensales en mesa, una app móvil para recepcionistas, una tablet para cajeros, una app para mesoneros, y paneles web para administradores.

A continuación se presenta un diagrama de componentes que ilustra cómo se conectan todas las partes del ecosistema:

graph TB
    subgraph Clientes
        CW[Web Cliente<br/>Next.js + React 19]
        QR[App QR Mesas<br/>Vite + React 19]
    end

    subgraph Staff
        OR[Orden Receiver<br/>React Native + Expo]
        TPV[TPV Terminal<br/>React Native + Expo]
        AM[App Mesonero<br/>React Native + Expo]
        KA[Cocina / Kitchen App]
    end

    subgraph Administración
        AW[Panel Admin Web]
        BW[Panel Branch Web]
    end

    subgraph Backend
        API[API REST v1<br/>Backend del sistema]
        DB[(Base de Datos<br/>MySQL + MongoDB)]
    end

    subgraph Externo
        PAY[Webhooks de Pago<br/>Stripe / PayPal / MONEI]
        INT[Integraciones<br/>Sinqro / Shipday / AEAT]
        DEL[App Delivery<br/>hotpack_rider]
    end

    CW -->|Axios + TanStack Query| API
    QR -->|fetch nativo| API
    OR -->|Axios + TanStack Query| API
    TPV -->|Axios + Zustand| API
    AM -->|API v1| API
    KA -->|API Kitchen| API
    AW -->|Rutas Admin| API
    BW -->|Rutas Branch| API
    API --> DB
    API <-->|Webhooks| PAY
    API <-->|API / Webhooks| INT
    API -->|Asignación de pedidos| DEL

El diagrama muestra claramente que todas las aplicaciones clientes convergen hacia el backend, que expone una API REST v1 unificada. No existen bases de datos locales ni sincronizaciones batch; toda la información vive en el centro y se consulta en tiempo real. Las integraciones externas —pasarelas de pago, servicios de entrega, sistemas de facturación electrónica— se comunican con el backend mediante webhooks o APIs dedicadas, manteniendo así una única fuente de verdad para pedidos, ingresos y estados.

Descripción de Componentes

Backend (API Central)

El backend es el núcleo sobre el que gira todo ZEUMAX. Expone una API REST v1 bien definida y gestiona la lógica de negocio, la autenticación, las notificaciones y las integraciones externas. La base de datos está soportada por MySQL (como sistema relacional principal) y MongoDB (para datos de notificaciones, logs y ciertos documentos de alta velocidad). El modelo de datos cubre entidades como productos, variantes, modificadores, mesas, zonas, pedidos, líneas de pedido, pagos, facturas, clientes, empleados, turnos, stock, recetas, escandallos, cupones, wallet, traducciones y configuraciones de sucursal, entre muchas otras.

La API está organizada por dominios funcionales: autenticación general (Auth), gestión del manager (Manager), operaciones del TPV (TPV), experiencia del cliente (Customer), logística de delivery (Delivery) y operaciones de cocina (Kitchen). Además, existen rutas web independientes para el panel administrativo (Admin), el panel de sucursal (Branch), la instalación inicial del sistema y los mecanismos de actualización. Las pasarelas de pago —Stripe, PayPal, MONEI y otras— se integran mediante rutas de webhook que permiten confirmar transacciones de forma asíncrona y segura. Este backend no es solo un almacén de datos; es un motor de reglas de negocio que calcula impuestos, aplica tarifas dinámicas, gestiona fraccionamientos de pago, valida stock en tiempo real y emite los eventos que activan notificaciones push, impresiones térmicas y alertas operativas.

Web Cliente (costumer-web)

La Web Cliente es la cara pública del negocio. Está desarrollada con Next.js 16, React 19 y Tailwind CSS, lo que garantiza un rendimiento optimizado, un diseño responsive y una experiencia de usuario moderna. Es aquí donde los clientes finales descubren el restaurante, navegan por el menú, añaden productos al carrito, aplican cupones, eligen método de entrega (recogida o delivery), realizan el pago y hacen seguimiento de su orden en tiempo real. La paleta visual se basa en un naranja de marca (#F5A623) y un azul marino (#2C3E50), transmitiendo calidez y profesionalidad.

El estado global se gestiona con Redux Toolkit con persistencia, lo que permite que el carrito y las preferencias del usuario sobrevivan a recargas de página. Las llamadas a la API se realizan con Axios combinado con TanStack Query (React Query), lo que ofrece cacheo inteligente, reintentos automáticos y sincronización de datos en segundo plano. Entre sus páginas principales se encuentran: Home, inicio de sesión y registro con verificación OTP, carrito de compras, checkout, historial de órdenes con tracking en vivo, perfil de usuario, monedero digital (wallet), gestión de cupones, lista de favoritos (wishlist), chat con el restaurante, localizador de sucursales, búsqueda inteligente, menú del día y escaneo de QR para pedidos en mesa. Esta aplicación está diseñada para convertir visitantes en comensales con el menor fricción posible.

App QR para Mesas (app-qr)

La App QR para Mesas es una aplicación web progresiva (PWA) ultraligera diseñada específicamente para el contexto de comedor físico. Está construida con Vite, React 19 y Tailwind CSS, y su propósito es simple pero crítico: permitir que un cliente, sentado en una mesa del restaurante, escanee un código QR, acceda instantáneamente al menú digital y realice su pedido sin descargar aplicaciones ni interactuar con el personal. La experiencia está reducida a lo esencial para eliminar fricción: tres pantallas que resuelven todo el flujo.

La primera pantalla es el Splash, que activa la cámara del dispositivo para leer el QR de la mesa; este código contiene la información de la sucursal, la zona y el número de mesa, vinculando automáticamente el pedido al punto físico correcto. La segunda pantalla es el Menú, donde el cliente explora categorías, visualiza productos con imágenes, precios y modificadores, y añade artículos a su cuenta. La tercera pantalla es el Checkout, que muestra un resumen de la cuenta de mesa, permite revisar los artículos pedidos y finalizar la orden. El estado se maneja con Zustand con persistencia local, y las comunicaciones con el backend se hacen mediante fetch nativo, manteniendo el bundle de la aplicación mínimo y los tiempos de carga instantáneos incluso en redes móviles de baja calidad.

Orden Receiver (orden-receiver)

El Orden Receiver es la aplicación móvil del manager o recepcionista del restaurante. Desarrollada en React Native con Expo SDK 55, su función es ser el centro de mando operativo de la sucursal: recibir pedidos entrantes, gestionarlos, coordinar con cocina, asignar repartidores, imprimir tickets y comunicarse con clientes. La app no depende de notificaciones push para recibir pedidos; en su lugar, implementa un sistema de polling nativo cada 10 segundos que consulta el backend activamente, acompañado de alertas sonoras y vibración para garantizar que ninguna orden pase desapercibida en entornos ruidosos.

La interfaz está organizada en pantallas especializadas: un login con PIN rápido para cambios de turno, un dashboard de pedidos con contadores visuales, una lista de pedidos segmentada por pestañas (Nuevos, Activos, Delivery, Completados), una vista detallada de cada pedido con acciones contextuales (aceptar, rechazar, preparar, listo, asignar), un explorador del menú del restaurante, configuración de impresoras térmicas (para tickets de cocina y facturas), estadísticas de ventas en tiempo real, gestión de empleados, un chat integrado para resolver incidencias con clientes y una pantalla de ajustes generales. El estado de la aplicación se gestiona con Zustand persistido en MMKV, lo que asegura que los datos críticos —como la configuración de impresoras o el token de sesión— persistan rápidamente entre reinicios de la app.

TPV (Terminal Punto de Venta)

El TPV es la aplicación de caja del sistema, desarrollada en React Native con Expo, y está pensada para funcionar en tablets o terminales táctiles ubicadas en el mostrador del restaurante. Es la herramienta principal del cajero y está diseñada para operar con velocidad, precisión y trazabilidad. Sus funciones abarcan todo el flujo de venta presencial: apertura y cierre de sesiones de caja con control de fondo, creación de pedidos personalizados, gestión visual de mesas y zonas del restaurante, envío de comandas a cocina, checkout avanzado con soporte para split bill (dividir la cuenta entre varios comensales) y pagos parciales (permitir que un cliente pague una parte y otro la diferencia), gestión de órdenes en espera (hold orders), control de almacén y stock, registro de clientes frecuentes desde el TPV, configuración de impresoras térmicas, emisión de tickets y facturas conforme a normativa, gestión de escandallos y recetas de cocina, tarifas especiales, configuración del menú del día, creación de ofertas y promociones, grupos de modificadores, gestión de turnos laborales, festivos, fichaje de entrada y salida (clock-in/out), integración con CashDro (cajón automático) y un sistema de alertas operativas.

El estado del TPV se gestiona con Zustand y se persiste en MMKV, lo que permite que una caja abierta o un pedido en curso sobreviva a cierres accidentales de la aplicación. Esta robustez es esencial en entornos de alta presión donde la pérdida de un pedido activo puede traducirse en una mala experiencia para el cliente.

App Mesonero (app-mesonero-react)

La App Mesonero es una aplicación móvil desarrollada en React Native con Expo, orientada a los camareros o mesoneros que atienden las mesas en el salón del restaurante. Su objetivo es digitalizar la toma de comandas, eliminando los errores de transcripción manual y acelerando el flujo entre el salón y la cocina. Desde la app, el mesonero puede ver el mapa de mesas y zonas, seleccionar una mesa ocupada, tomar el pedido directamente en el dispositivo seleccionando productos y modificadores, enviar la comanda a cocina en tiempo real, y consultar el estado de los pedidos activos de su zona. Al compartir backend con el TPV y el Orden Receiver, cualquier pedido registrado desde la app del mesonero aparece instantáneamente en los demás puntos del sistema, manteniendo la sincronización total del restaurante.

Panel Admin Web

El Panel Admin Web es la interfaz de gestión corporativa para superadministradores y equipos de dirección. No es una aplicación separada con su propio repositorio; reside en el backend del sistema y se sirve mediante las rutas y vistas web del panel de administración. Desde este panel se configura todo el sistema a nivel global: catálogo de productos con variantes, modificadores y recetas; creación y gestión de sucursales (branches) con horarios, zonas, mesas y configuraciones locales; registro de repartidores y vehículos; gestión de empleados, roles y permisos; supervisión de pedidos en tiempo real; control de la cocina; base de datos de clientes; administración del monedero digital (wallet) y transacciones; creación y seguimiento de cupones; envío de notificaciones push y campañas; configuración de pasarelas de pago (Stripe, PayPal, MONEI y otras); integraciones externas como Sinqro (sincronización de menús), Shipday (logística de entrega) y AEAT (facturación electrónica española); generación de reportes financieros y operativos; gestión de usuarios del TPV y del Manager; traducciones multilenguaje; y herramientas de mantenimiento y limpieza de la base de datos.

Este panel es el pilar de la operación multisede: un superadmin puede gestionar diez sucursales desde una única pantalla, actualizar precios en todos los puntos de venta simultáneamente, y auditar las ventas del día sin necesidad de acceder físicamente a ninguna de ellas.

Panel Branch Web

El Panel Branch Web es la versión reducida y contextualizada del panel administrativo, también alojada dentro del backend del sistema. A diferencia del Panel Admin, que tiene visión global, este panel está limitado a una única sucursal y está pensado para el propietario o encargado local que necesita gestionar su punto de venta sin ver datos de otras ubicaciones. Sus funciones incluyen: un dashboard con métricas de la sucursal, un POS simplificado para ventas rápidas desde el navegador, gestión de órdenes entrantes, control de mesas y ocupación, seguimiento de cocina, y administración de productos disponibles exclusivamente en esa sucursal. Es la herramienta perfecta para franquicias o cadenas donde el encargado local necesita autonomía operativa dentro de los límites definidos por la central.

Roles del Sistema y Aplicaciones que Utilizan

La siguiente tabla resume qué aplicación utiliza cada rol dentro del ecosistema ZEUMAX. Esta relación no es exclusiva: un empleado puede tener múltiples roles asignados (por ejemplo, un manager puede también tener acceso de cajero) y, por tanto, usar varias aplicaciones según su turno o función del día.

Como se observa, cada rol tiene una interfaz adaptada a sus necesidades. El cliente no necesita ver el dashboard de ventas; el cajero no necesita configurar cupones corporativos; y el superadmin no necesita escanear un QR para pedir. Esta segmentación es clave para mantener la usabilidad y reducir la curva de aprendizaje de cada aplicación.

Matriz de Características Principales

La siguiente tabla ofrece una visión comparativa de las funcionalidades más relevantes del sistema y en qué componentes están disponibles. No pretende ser exhaustiva, sino una guía rápida para entender el alcance de cada módulo.

Esta matriz evidencia que ZEUMAX no es un conjunto de aplicaciones aisladas, sino un sistema donde la funcionalidad fluye de forma contextual. Por ejemplo, la impresión de tickets no es necesaria en la web del cliente, pero es crítica en el TPV y el Orden Receiver; la configuración de pasarelas de pago es responsabilidad exclusiva del panel administrativo, pero su efecto se siente en la web y en la app QR. El diseño modular garantiza que cada usuario vea solo lo que necesita, sin distracciones ni opciones irrelevantes.

El Backend: El Corazón que Conecta Todo

Si hay un elemento que define la arquitectura de ZEUMAX, es la decisión de centralizar toda la lógica de negocio, toda la persistencia de datos y toda la comunicación entre actores en un único backend que expone una API REST v1. Esta elección no es técnica por capricho; es una decisión de producto que asegura consistencia, seguridad y escalabilidad operativa.

Cuando un cliente finaliza un pedido desde la Web Cliente, la solicitud llega al backend como una petición POST al endpoint de creación de pedidos. El backend valida el stock, calcula impuestos y descuentos, registra la transacción, genera los eventos de impresión para la cocina, envía la notificación al Orden Receiver mediante el mecanismo de polling, y responde al cliente con un identificador de seguimiento. Si el mismo pedido requiere un repartidor, el manager lo verá en el Orden Receiver, lo aceptará y, desde la misma app, asignará un conductor; esa acción actualiza el estado del pedido en el backend, y la app de delivery (hotpack_rider) recibirá la asignación en su siguiente sincronización. Si el pedido es para consumir en mesa, el QR del cliente se vincula a la mesa, y la cuenta puede ser pagada parcialmente o dividida entre amigos desde el TPV, con cada transacción registrada en el mismo backend que ya conoce el pedido original.

Esta centralización tiene beneficios prácticos inmediatos para los usuarios del manual. Primero, los datos no se duplican ni desfasan: un precio cambiado en el Panel Admin se refleja instantáneamente en la web, en la app QR, en el TPV y en el Orden Receiver. Segundo, la seguridad es unificada: la autenticación, los roles y los permisos se gestionan en un solo punto, lo que facilita auditar quién hizo qué y cuándo. Tercero, la trazabilidad es total: desde el Panel Admin se puede reconstruir el historial completo de un pedido, desde que el cliente lo añadió al carrito hasta que el cajero cerró la caja, pasando por cada cambio de estado en cocina y cada intento de impresión fallido. Cuarto, las integraciones externas se conectan una sola vez: configurar Stripe o AEAT en el backend es suficiente para que todos los frontends puedan beneficiarse de ello sin necesidad de configuraciones adicionales.

Cómo Usar este Manual

Este documento de visión general es el punto de partida, pero no el destino. Cada componente descrito aquí tiene su propio capítulo en el manual de usuario, con instrucciones detalladas, capturas de pantalla, flujos paso a paso y resolución de problemas comunes. Te recomendamos seguir esta ruta de lectura según tu rol:

• Si eres Cliente: Lee el capítulo de la Web Cliente y la App QR para conocer cómo hacer pedidos, aplicar cupones y consultar el estado de tu orden.
• Si eres Manager o Recepcionista: Dirígete al manual del Orden Receiver para dominar la recepción de pedidos, la asignación de repartidores y la gestión de incidencias.
• Si eres Cajero: El manual del TPV es tu guía esencial para sesiones de caja, gestión de mesas, cobros, split bill e impresión de tickets.
• Si eres Mesonero: Consulta el manual de la App Mesonero para aprender a tomar comandas digitales y enviarlas a cocina sin errores.
• Si eres Cocinero: El manual de la Kitchen App te explicará cómo filtrar pedidos por estado y marcar platos como listos.
• Si eres Admin o Superadmin: Los manuales del Panel Admin Web y el Panel Branch Web te enseñarán a configurar productos, sucursales, empleados, pasarelas de pago e integraciones externas.

ZEUMAX es un sistema amplio, pero está diseñado para que cada persona interactúe únicamente con las partes que necesita. No hace falta entenderlo todo para usarlo con eficacia. Comienza con tu rol, domina tu aplicación, y vuelve a esta visión general cada vez que necesites entender cómo tu trabajo se conecta con el resto del equipo.

Documento generado para el manual de usuario de ZEUMAX (ZEUMAX).