TravelDemo
Plataforma SaaS para Agencias de Viajes con Doble Autenticación y Control de Cupos
Sistema unificado bajo Next.js 16 (App Router) diseñado para digitalizar la operación comercial, reservas y control de cupos en agencias de turismo. Implementa dos entornos estrictamente aislados por Route Groups: un catálogo público para exploración de tours y checkout de pasajeros con Supabase Auth, y un panel administrativo para programación de salidas, control de unidades de transporte y conciliación de pagos con better-auth y Drizzle ORM.
Tecnologías clave
- Next.js 16
- React 19
- TypeScript 5
- Drizzle ORM
- PostgreSQL
- better-auth
- Supabase Auth
- Tailwind CSS v4
- Zod
- Vitest
Ingeniería & Diseño
Arquitectura del Sistema
Arquitectura modular en Next.js 16 App Router con segmentación estricta por Route Groups: '(catalogo)' para pasajeros con Supabase Auth y '(admin)' para el equipo operativo con better-auth. Ambas áreas comparten la misma base de datos relacional PostgreSQL con Drizzle ORM, manteniendo aislamiento total en middleware, cookies de sesión y layouts.
┌─ PORTAL DEL CLIENTE: (catalogo) ──────────────────────────────────────┐
│ - Landing page, directorio y buscador de tours │
│ - Checkout, selección de cupos y reporte de comprobantes │
│ - Área privada (/cuenta): Vouchers QR y estado de pagos │
│ - Auth: Supabase Auth (OAuth Google, Magic Link, OTP) │
└───────────────────────────────────┬───────────────────────────────────┘
│ Server Actions / Route Handlers
▼
┌─ SERVIDOR NEXT.JS 16 (Runtime Node + Middleware Dual) ────────────────┐
│ - Middleware: Aislamiento estricto de sesiones (catalogo vs admin) │
│ - Lógica modular en 'src/modules/*' (Domain Services + Repositories)│
│ - Validación estricta con esquemas Zod en todas las entradas │
│ - Generación de vouchers y listas de abordaje en PDF (jsPDF + QR) │
└───────────────────────────────────┬───────────────────────────────────┘
│ Drizzle ORM (Prepared Queries)
▼
┌─ BASE DE DATOS (PostgreSQL / Supabase) ───────────────────────────────┐
│ - app_tours, app_departures, app_departure_units, app_transport_units│
│ - app_bookings, app_passengers, app_payments, app_payment_methods │
│ - app_users, app_roles (RBAC granular), app_system_logs (auditoría) │
│ - Política de no eliminación física (soft-deletes) y UUID v7 │
└───────────────────────────────────▲───────────────────────────────────┘
│
┌─ PANEL ADMINISTRATIVO: (admin) ───┴───────────────────────────────────┐
│ - Dashboard de métricas, ocupación y aforos por unidad │
│ - Control de salidas, flota de transporte y manifiestos de abordaje │
│ - Conciliación de pagos fragmentados (pago móvil, divisas, Zelle) │
│ - Auth: better-auth con RBAC por rol (admin, operator, sales_agent) │
└───────────────────────────────────────────────────────────────────────┘
Puntos clave de la arquitectura
- Aislamiento Dual de Autenticación: Dos proveedores de auth completamente desacoplados bajo la misma app (Supabase Auth para clientes externos y better-auth con RBAC para personal administrativo).
- Arquitectura Modular Desacoplada: Dominio estructurado en 'src/modules/*' (tours, departures, bookings, transport-units, payments) con repositorios y servicios reutilizables.
- Control de Aforos y Cupos por Flota: Cálculo dinámico de ocupación por unidad de transporte (buses, vans, lanchas) evitando sobreventas en salidas programadas.
- Conciliación de Pagos Fragmentados: Soporte para abonos fraccionados (50% anticipo, múltiples divisas, Pago Móvil, Zelle, efectivo) y aprobación de comprobantes.
- Emisión de Documentos con QR: Generación instantánea en PDF de vouchers para pasajeros y manifiestos de abordaje para choferes y guías con jsPDF.
- Política Estricta de No Eliminación Física: Modelo de persistencia Drizzle ORM con soft-deletes y registro centralizado de logs de sistema para trazabilidad total.
Ecosistema
Stack Tecnológico Detallado
Next.js 16 (App Router) + React 19 + TypeScript 5
Núcleo de la plataforma con Server Components, Server Actions y Route Groups aislados.
Drizzle ORM + PostgreSQL (Supabase / Neon)
Modelado relacional tipado seguro, migraciones y consultas preparadas de alto rendimiento.
better-auth + Supabase Auth
Sesiones administrativas seguras por cookies HTTP-only y autenticación social/magic link para clientes.
Tailwind CSS v4 + Lucide Icons
Diseño responsivo optimizado para móviles y escritorio tanto en portal público como en backoffice.
jsPDF + jsPDF-AutoTable + qrcode
Generación en cliente/servidor de vouchers de reserva y manifiestos de abordaje oficiales.
TipTap Editor (@tiptap/react)
Editor WYSIWYG para itinerarios, descripciones de tours y recomendaciones de viaje.
Zod 4
Validación estricta de formularios, esquemas de entrada y reglas de negocio.
Vitest 5
Suite de pruebas automatizadas para aforos, conciliación de pagos y políticas de persistencia.
Capacidades
Características Principales
Catálogo público con filtros por categoría (playa, montaña, río) y fichas de destino enriquecidas con editor TipTap.
Flujo de checkout y reserva de cupos con validación de aforo disponible en tiempo real.
Área privada del pasajero con acceso a historial de reservas, vouchers digitales con código QR y estatus de abonos.
Panel administrativo integral con programación de salidas, itinerarios multi-parada y asignación de flota de transporte.
Auditoría de reservas y generación de manifiestos de pasajeros listos para impresión o descarga PDF.
Módulo de finanzas para conciliación de comprobantes, cuentas bancarias y balances pendientes de cobro.
Sistema RBAC con roles administrativos y permisos granulares por acción (tours.create, payments.reconcile, etc.).
Suite de 64 pruebas unitarias y de integración con Vitest para cálculo de aforos, conciliación y resiliencia.
Decisiones de Ingeniería
¿Cómo se creó este proyecto?
Diseñado para resolver el caos operativo habitual en agencias turísticas que gestionan reservas y pagos dispersos entre WhatsApp, hojas de cálculo y mensajes directos.
El principal desafío técnico fue orquestar dos mundos de autenticación completamente distintos (better-auth con RBAC para operadores y Supabase Auth para usuarios finales) dentro de un único proyecto Next.js sin colisión de middleware ni fugas de contexto de sesión.
La arquitectura por flota permite que cada salida combine múltiples unidades de transporte con diferentes capacidades, calculando el cupo total y la asignación de asientos de forma automática y consistente.
¿Quieres revisar el código fuente completo?
El repositorio público contiene el historial de commits, pruebas e instrucciones de ejecución.