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:

Dónde	Usuario	Contraseña
Panel del local (/login)	[email protected]	bar-demo-123
Plataforma (/admin/login)	[email protected]	plataforma-123

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

1. Núcleo multi-tenant + motor de asignación + panel de staff + reservas manuales.
2. Web pública de reservas + widget embebible + vista visual del salón con reasignación.
3. Lista de espera + recordatorios + motor de notificaciones + bot de WhatsApp.
4. Analítica, onboarding autoguiado, preparación para planes y suscripciones.