resto — plataforma SaaS de reservas multi-local
Plataforma multi-tenant de reservas para gastronomía: cada local tiene su propia página de
reservas, su plano de salón y su panel de staff, todo corriendo sobre la misma plataforma.
Asignación automática de mesas, lista de espera, notificaciones multi-canal y reservas por
WhatsApp.
Cómo correrlo
No hace falta ninguna cuenta en la nube para trabajar en la Fase 1. El esquema usa
Postgres estándar, así que lo que corre local corre igual en Supabase, Neon o Railway.
npm install
npm run db:start # levanta Postgres, crea la base y aplica migraciones
npm run db:demo # carga un local de prueba con reservas
npm run db:migrar # aplica migraciones pendientes (necesita DATABASE_URL_OWNER)
npm run dev # panel en http://localhost:3000
npm test # 304 tests
npm run test:unit # solo el motor, sin base de datos
npm run humo # recorrido de humo en navegador (requiere el server andando)
npm run humo:salon # recorrido de humo sobre la carga del salón
npm run humo:horarios # recorrido de humo sobre horarios y turnos
npm run humo:equipo # recorrido de humo sobre el equipo y los permisos
npm run humo:publico # recorrido de humo sobre la web pública y el widget
npm run humo:plano # recorrido de humo sobre el salón en vivo y la reasignación
npm run humo:google # recorrido de humo sobre lo que ve Google
npm run humo:espera # recorrido de humo sobre la lista de espera
Cada recorrido de humo deja la base cambiada (carga reservas, mueve mesas, marca
feriados). Corré npm run db:demo antes de cada uno: si no, el siguiente falla por lo
que dejó el anterior y no por un problema de verdad.
Usuarios de prueba que deja db:demo:
La página pública del local de demo queda en /r/bar-demo. No pide usuario: es la que
ve alguien de la calle.
Estado
Fase 1 completa. Un local se puede dar de alta y operar de punta a punta:
- Plataforma (
/admin): alta de locales con su dueño, suspender y reactivar.
- El salón: salones con medidas reales, mesas con capacidad, cabeceras, forma y
posición. Qué mesas se pueden unir lo deduce el sistema de dónde están, y lo muestra
en el plano mientras las acomodás — con el motivo cuando dos que parecen vecinas no
se van a unir.
- Horarios y turnos: la semana día por día, cuánto ocupa la mesa cada grupo, y días
especiales que reemplazan el horario de esa fecha: pueden abrir antes de lo
habitual, tener dos tandas, o abrir un día en que el local normalmente cierra.
- El equipo: quién entra al panel y con qué permisos. Un mozo opera el día; el salón
y los horarios son de encargado para arriba; el equipo, solo del dueño.
- El día: planilla con el historial de cada cliente, alta de reservas de mostrador,
walk-ins, llegadas y ausencias, y cambio de mesa a mano con auditoría.
Fase 2 en curso. El local ya toma reservas de la calle:
-
La página del local (/r/<local>): elegir día y cantidad, ver los horarios que
tienen lugar de verdad, y reservar dejando nombre y teléfono. Sin cuenta, sin seña.
-
El widget: una línea de <script> mete el mismo formulario adentro de la web del
local, ajustándose solo al alto que necesita.
-
La reserva del cliente (/r/<local>/reserva/<token>): vuelve a su reserva con el
link que le quedó, y cancela desde ahí. La mesa se libera en el acto.
-
Reservas web (/panel/publico): prender o apagar la página, los datos que se
muestran y los cuatro límites con los que el local acepta reservas de gente que no
conoce.
-
El salón en vivo (en la planilla del día): el plano a escala a la hora que se
mire, con cada mesa pintada según quién la tiene. Tocar una mesa ocupada y después
una libre mueve la reserva entera. Solo se ofrecen las mesas que aguantan el turno
completo: una mesa libre a las 21:00 pero tomada a las 21:15 no sirve, y ofrecerla
sería mandar al mozo a un rechazo con el cliente esperando.
-
Para que la encuentren: la página de cada local se declara como restaurante, con su
dirección, su teléfono, su horario y su acción de reservar, más sitemap.xml y
robots.txt. El objetivo es aparecer cuando alguien busca ese local por su nombre;
competir por "restaurante" no es alcanzable (D18).
Fase 3 en curso. Avisos y lista de espera andando:
- Avisos al cliente: confirmación al reservar y recordatorio el día de la reserva, por
el canal que haya. El módulo no sabe qué es una reserva y las features no saben qué es
WhatsApp; entre medio hay un solo contrato (04).
- Lista de espera: los horarios sin lugar se pueden tocar para anotarse. Cuando alguien
cancela, el sistema le ofrece la mesa al primero de la lista que entre de verdad, con
vencimiento, y esa persona la acepta desde su link.
Falta de la Fase 3: el bot de WhatsApp, que necesita una cuenta de Meta y plata.
Cómo está organizado
src/
dominio/ lógica pura, sin I/O: motor, turnos, combinaciones, identidad, passwords
datos/ esquema SQL, migraciones, repositorios, conexiones por rol
servicios/ casos de uso: reservas, auth, panel, administración
web/ helpers del panel: sesión, formato de fecha y hora
app/ pantallas (Next.js App Router)
Todo lo que vive en dominio/ es función pura: recibe datos, devuelve decisiones. No
toca la base, no conoce transacciones, no sabe qué es un tenant. Es lo que permite
testear el motor sin levantar un servidor.
Documentos de decisión
Leer en orden:
| Doc | Contenido |
|---|
| 00 — Decisiones tomadas | lo que ya está definido y por qué |
| 01 — Viabilidad y riesgos | qué es viable, los cinco puntos caros del brief |
| 02 — Stack y arquitectura | stack recomendado con alternativas, multi-tenancy, hosting, proveedores y costos |
| 03 — Modelo de datos y asignación | tablas, el motor de mesas, concurrencia, auditoría |
| 04 — Notificaciones | motor multi-canal, resolución de canal, consentimiento, outbox |
| 05 — Preguntas abiertas | lo que falta definir antes de la Fase 1 |
| 06 — Cómo desplegar | pasar de la máquina a internet: base, hosting y qué falta para producción |
Resumen de decisiones propuestas
- Stack: TypeScript + Next.js (App Router) + PostgreSQL + Drizzle + pg-boss.
- Multi-tenancy: tabla compartida con
tenant_id + Row Level Security de Postgres.
- Doble booking: imposible por constraint
EXCLUDE USING gist sobre (mesa, periodo).
- Concurrencia: advisory lock por (tenant, fecha) + la constraint como red de seguridad.
- Asignación: mesa concreta al reservar, pero re-optimizable hasta 4hs antes mientras
no esté fijada a mano por el staff. La confirmación al cliente no lleva número de mesa.
- Turnos: duración variable por tamaño de grupo y por franja horaria.
- Notificaciones: módulo agnóstico de canal, patrón outbox, un único resolutor de canal.
- WhatsApp: Cloud API directo detrás de una interfaz de proveedor. Número propio por
local como destino; compartido con deep link para las pruebas de Fase 3.
- Escala objetivo del primer año: 5–20 locales, hasta ~50 mesas cada uno.
Fases
- Núcleo multi-tenant + motor de asignación + panel de staff + reservas manuales.
- Web pública de reservas + widget embebible + vista visual del salón con reasignación.
- Lista de espera + recordatorios + motor de notificaciones + bot de WhatsApp.
- Analítica, onboarding autoguiado, preparación para planes y suscripciones.
