Sistema Administrativo de Salsa Candela

Salsa Candela es una empresa de escuelas de baile que opera en 5 sucursales en la Ciudad de México. Durante los últimos dos años, construí desde cero una plataforma administrativa integral que centraliza toda su operación: inscripciones, pagos, control de asistencia, asignación de maestros, gestión de eventos y reportes de negocio.

Antes de este sistema, el negocio dependía de procesos manuales, hojas de cálculo y herramientas desconectadas para gestionar cientos de alumnos en múltiples sucursales y canales de pago. Este proyecto reemplazó todo eso con una plataforma única y unificada.

Puedes visitar el sistema administrativo en vivo, explorar el repositorio en GitHub, o ver el video demostrativo.

Descripción del Proyecto y Contexto de Negocio

Salsa Candela lleva más de 12 años enseñando salsa y bachata en 5 ubicaciones en la Ciudad de México: Xola, Valle, Satélite, Clavería y Coapa. Con 4 programas de baile, múltiples canales de pago, eventos recurrentes y decenas de maestros, la complejidad administrativa crecía más rápido de lo que el negocio podía manejar manualmente.

Diseñé y construí este sistema desde cero usando Express.js, MongoDB y EJS durante dos años de desarrollo activo, acumulando más de 1,094 commits. La plataforma funciona como la columna vertebral operativa de todo el negocio.

Valor Principal Entregado

• Para los dueños del negocio: Gestión centralizada de las 5 sucursales desde un solo panel, reportes de ventas en tiempo real, seguimiento automatizado de comisiones y asignación de maestros con prevención de conflictos
• Para los clientes: Inscripción y pago de clases en línea vía Stripe, confirmación instantánea por correo con código QR para acceso a clases, múltiples opciones de pago y auto-registro al inicio de clase
• Para las operaciones: Mantenimiento automatizado de base de datos, respaldos semanales, seguimiento del progreso curricular y reportes completos de todos los canales

El Desafío de Negocio

Administrar una escuela de baile con múltiples sucursales significa manejar muchas piezas en movimiento simultáneamente. Antes de este sistema, cada uno de estos procesos se manejaba manualmente o con herramientas desconectadas, generando ineficiencias, errores y oportunidades de ingreso perdidas.

Puntos Críticos

• Caos en inscripciones: Gestionar registros en 5 sucursales, 4 programas de baile y múltiples canales de pago sin un sistema unificado
• Puntos ciegos en asistencia: Sin forma confiable de rastrear qué alumnos realmente asistieron a clases versus los que solo se inscribieron
• Conflictos de horarios: Coordinar asignaciones de maestros entre sucursales sin duplicar accidentalmente a los instructores
• Brechas en seguimiento de ingresos: Ventas llegando por efectivo, tarjeta, transferencia bancaria, Stripe y CoDi sin reportes consolidados
• Disputas de comisiones: Calcular comisiones de referidos para socios de ventas sin un sistema automatizado de seguimiento
• Silos de datos: Registros de clientes dispersos en hojas de cálculo y formularios en papel sin una fuente única de verdad

El objetivo era claro: construir una sola plataforma que reemplace más de 5 herramientas separadas y dé al negocio visibilidad completa de cada aspecto de su operación.

Funcionalidades Principales

El sistema abarca siete áreas funcionales principales, cada una diseñada para atender una necesidad operativa específica. Juntas, forman una plataforma completa de gestión empresarial adaptada a los flujos de trabajo específicos de Salsa Candela.

1. Sistema de Ventas Multicanal

Uno de los requisitos más importantes era soportar todas las formas en que un cliente puede querer pagar. El sistema maneja 4 canales de venta distintos tanto para clases como para fiestas:

• En línea (Stripe): Los clientes compran con tarjeta de crédito o débito en la web, con confirmación instantánea
• Presencial en sucursales: El personal registra ventas en cualquiera de las 5 sucursales usando efectivo, tarjeta o transferencia bancaria
• En la puerta (fiestas): El personal vende boletos en el lugar del evento la noche de la fiesta
• Pagos móviles CoDi: El sistema de pagos en tiempo real de México con flujos de código QR y notificaciones push, con cero comisiones

Ninguna venta se pierde sin importar cómo quiera pagar el cliente. Cada canal tiene su propio flujo dedicado pero alimenta reportes unificados.

2. Gestión de Clases Grupales

El módulo de gestión de clases maneja el ciclo de vida completo de los cursos de baile en todas las sucursales, desde la inscripción hasta el control de asistencia y el progreso curricular.

• 4 programas de baile: Salsa (9 niveles), Bachata (5 niveles), combo Salsa+Bachata y Movimiento Corporal
• 5 sucursales: Cada una con diferentes horarios para tardes entre semana y mañanas de fin de semana
• Precios flexibles: Paquetes individuales y en pareja con 6 niveles de descuento (20%-50%) mediante tokens seguros
• Control de acceso por QR: Cada compra genera un código QR que se escanea en la entrada de la clase para verificar asistencia
• Auto-registro: Los alumnos pueden registrar su asistencia al inicio de la clase, sujeto a aprobación del administrador

3. Gestión de Eventos y Fiestas

Salsa Candela organiza fiestas de baile recurrentes que sirven tanto como fuente de ingresos como herramienta de construcción de comunidad. El sistema gestiona cada aspecto de estos eventos.

• Tipos de boletos: Boletos de preventa ($100 MXN) y boletos en la puerta ($150 MXN) con seguimiento separado
• Seguimiento de referidos: Ventas basadas en comisiones mediante códigos de referido, con cálculo automático de comisiones
• Gestión de barra: Sistema de pedidos de bebidas con Stripe para ventas de barra en eventos
• Pagos CoDi: Soporte de pagos QR y push para compra de boletos en eventos

4. Sistema de Asignación de Maestros

Coordinar decenas de maestros en 5 sucursales es uno de los desafíos operativos más complejos. El sistema implementa un flujo de propuesta y aprobación con detección automática de conflictos.

• Flujo de propuestas: Los gerentes de sucursal proponen asignaciones maestro-clase, el sistema valida conflictos y el CEO revisa, aprueba o rechaza
• Prevención de conflictos: La validación automática asegura que ningún maestro sea asignado dos veces al mismo horario y que los maestros permanezcan en la misma sucursal durante todo el día
• Gestión de grupos: Soporta fusión de grupos (unir grupos pequeños), división de grupos (separar por nivel) y eliminación de grupos con transferencia automática de alumnos
• Exportación CSV: Las asignaciones aprobadas pueden exportarse para distribución de horarios

5. Reportes Integrales

Con ventas llegando por múltiples canales, los reportes consolidados son esenciales para la toma de decisiones del negocio. El sistema proporciona reportes detallados en cada dimensión de la operación.

• Reportes de ventas: Reportes separados para cada canal (preventa, Stripe, CoDi, taquilla, barra, app móvil) con filtros por rango de fechas y empleado
• Totales por método de pago: Cálculo automático de totales por método de pago (efectivo, tarjeta, transferencia, check-in, OXXO)
• Reportes de comisiones: Seguimiento de comisiones de referidos tanto para clases como para fiestas
• Vistas consolidadas: Reportes combinados que agregan datos de todos los canales para una visión completa del negocio
• Exportación CSV: Todas las vistas de reportes soportan exportación CSV vía DataTables para análisis adicional

6. Confirmaciones por Correo Automatizadas

Cada compra genera un correo HTML con la marca que sirve tanto como confirmación como pase de acceso. El sistema de correos fue diseñado para reforzar la marca y promover otras ofertas.

• Confirmaciones de compra: Correos con la marca para cada compra de clase y fiesta, incluyendo detalles del curso, horario y ubicación
• Códigos de acceso QR: Cada correo incluye un código QR único que los alumnos escanean en la entrada de la clase para control de asistencia
• Promoción cruzada: Los correos de Salsa promueven clases de Bachata y viceversa; todos los correos incluyen invitaciones a fiestas
• Encuestas de satisfacción: Correos automatizados de encuesta post-curso y post-fiesta para recopilar retroalimentación de los alumnos
• Plantillas MJML: 5 plantillas de correo construidas con MJML para compatibilidad entre todos los clientes de correo

7. Mantenimiento Automatizado

Ejecutar un sistema en producción con miles de registros requiere mantenimiento continuo. Automaticé las tareas más críticas usando GitHub Actions con flujos de trabajo programados.

• Limpieza semanal de base de datos: Elimina transacciones incompletas de Stripe (carritos abandonados) cada lunes para mantener la base de datos limpia
• Respaldos semanales: Archivos comprimidos de todas las colecciones de MongoDB, conservando los 4 respaldos más recientes
• Limpieza de eliminaciones suaves: Elimina permanentemente grupos de clase que fueron borrados hace más de 14 días, permitiendo tiempo para recuperación si es necesario

Estas automatizaciones se ejecutan de manera confiable sin intervención manual, asegurando que el sistema se mantenga saludable y con buen rendimiento conforme crecen los datos.

Diseño y Experiencia de Usuario

El diseño refleja la marca de Salsa Candela: oscuro, enérgico e inspirado en la vida nocturna. La identidad visual fue construida alrededor de gradientes naranja cálidos evocando "Candela" (fuego) contra fondos azul marino oscuro, con efectos de glassmorphism para una sensación moderna y pulida.

Dos Modos Visuales

El sistema opera en dos contextos visuales distintos, cada uno optimizado para su audiencia:

• Páginas públicas: Fondos oscuros, texto blanco, acentos naranja y efectos de glassmorphism que coinciden con la marca nocturna de la escuela de baile
• Páginas de administración: Navegación blanca, formularios y tablas claras, y diseños funcionales orientados a datos optimizados para uso operativo diario

Categorías por Color

El panel usa codificación por colores para ayudar al personal a navegar rápidamente entre las diferentes áreas del sistema:

• Morado: Clases grupales (Clases)
• Rosa: Eventos de fiesta (Fiesta)
• Verde azulado: Clases particulares (Particulares)
• Naranja: Cuenta y acciones predeterminadas

Recorrido del Cliente

Desde la perspectiva del cliente, el sistema proporciona una experiencia de inscripción fluida:

1. El cliente visita la página de inscripción o escanea un enlace de referido
2. Selecciona tipo de curso, sucursal, horario, nivel y paquete (individual o pareja)
3. Paga vía Stripe en línea o presencialmente en una sucursal
4. Recibe un correo de confirmación con marca y código QR
5. Escanea el QR en cada clase para control de asistencia
6. Recibe un correo de encuesta de satisfacción al terminar el curso

Stack Tecnológico

Las decisiones tecnológicas fueron impulsadas por la necesidad de confiabilidad, velocidad de desarrollo y mantenibilidad a largo plazo. Cada componente fue seleccionado para servir las necesidades específicas de una plataforma de gestión empresarial multi-sucursal.

Tecnologías Principales

• Backend: Node.js con framework Express.js
• Frontend: Plantillas EJS con JavaScript vanilla
• Base de datos: MongoDB con Mongoose ODM (16 colecciones) + Supabase para app móvil
• Pagos: Stripe para tarjetas de crédito/débito + CoDi para transferencias bancarias en tiempo real de México
• Autenticación: Passport.js con hash de contraseñas bcryptjs y control de acceso basado en roles
• Correo: Nodemailer con plantillas de correo MJML
• Analítica: PostHog + Google Tag Manager
• Hosting: Railway (nube) en admin.salsa-candela.com
• Automatización: GitHub Actions para tareas de mantenimiento programadas
• Pruebas: Jest con Supertest

Medidas de Seguridad

Manejar datos de pago e información personal de cientos de alumnos requiere seguridad robusta. El sistema implementa múltiples capas de protección:

• Autenticación: Sesiones de Passport.js con cookies de 30 días almacenadas en MongoDB
• Acceso basado en roles: Tres niveles de permisos (Admin, Gerente, Personal) que controlan lo que cada usuario puede ver y hacer
• Limitación de velocidad: express-rate-limit previene ataques de fuerza bruta
• Lista blanca CORS: Solo los dominios permitidos pueden hacer solicitudes
• Bloqueo de archivos ocultos: Las solicitudes a rutas .git, .env, node_modules y wp-admin son bloqueadas
• Validación de entrada: Validación de números telefónicos vía libphonenumber-js y sanitización integral de entradas
• Descuentos seguros: Tokens de descuento en lugar de códigos en texto plano previenen el uso no autorizado de descuentos

Desafíos y Soluciones

Construir un sistema en producción para un negocio real conlleva desafíos que van más allá de escribir código. Estos son los obstáculos más significativos que encontré y cómo los resolví.

Reconciliación de Pagos Multicanal

Desafío: Las ventas llegan por Stripe, efectivo, tarjeta, transferencia bancaria, CoDi y una app móvil. Reconciliar todo esto en una imagen coherente de los ingresos era complejo.

Solución: Creé colecciones separadas en MongoDB para cada canal de ventas, y luego construí vistas de reportes unificadas que agregan datos de todas las fuentes. Esto mantiene los datos de cada canal limpios mientras proporciona inteligencia de negocio consolidada.

Conflictos de Horarios de Maestros

Desafío: Con decenas de maestros en 5 sucursales, prevenir doble asignaciones era crítico. Un maestro asignado accidentalmente a dos clases al mismo tiempo dejaría a los alumnos sin instructor.

Solución: Implementé reglas de validación automáticas que verifican conflictos de horario y de sucursal antes de finalizar cualquier asignación. Combinado con un flujo de propuesta/aprobación, esto asegura que el CEO tenga la decisión final mientras el sistema detecta conflictos potenciales.

Gestión de Períodos de Cursos

Desafío: Los cursos de baile se ejecutan en períodos rotativos de 5 semanas con ventanas de inscripción superpuestas. Gestionar qué período es el "actual" y cuándo comienza el siguiente era propenso a errores cuando se hacía manualmente.

Solución: Un archivo de configuración de calendario de cursos centralizado abarca 2024-2026 con detección automática del período actual, siguiente y futuro. El sistema siempre sabe qué período está activo sin actualizaciones manuales.

Limpieza de Carritos Abandonados

Desafío: Los clientes que inician un pago en Stripe pero nunca lo completan dejan registros de transacciones incompletas que inflan la base de datos y sesgan los reportes.

Solución: Un flujo de trabajo semanal de GitHub Actions identifica y elimina automáticamente transacciones incompletas de Stripe cada lunes, manteniendo la base de datos limpia sin intervención manual.

Integración de CoDi

Desafío: Integrar el sistema de pagos en tiempo real de México (CoDi) requería soportar flujos de código QR y notificaciones push, con validación y confirmación adecuada de pagos.

Solución: Construí rutas y controladores dedicados para generación de QR CoDi, notificaciones push y validación de pagos. Esto fue posible gracias al API de CoDi que ya había desarrollado como un proyecto de código abierto independiente.

Escala y Alcance

A lo largo de dos años de desarrollo, este proyecto creció hasta convertirse en una base de código sustancial que refleja la complejidad de gestionar un negocio multi-sucursal. Estos son los números clave:

• 5 sucursales en la Ciudad de México
• 4 programas de baile con hasta 9 niveles
• 4 canales de pago por tipo de producto
• 16+ colecciones de MongoDB rastreando todas las transacciones y operaciones
• 62 plantillas EJS (vistas de página) para el frontend
• 37+ archivos JavaScript de frontend manejando interacciones del lado del cliente
• 34 hojas de estilo CSS definiendo el diseño visual
• 14 archivos de rutas organizando el API del backend
• 18 archivos de modelos definiendo la arquitectura de datos
• 5 plantillas de correo MJML para comunicaciones automatizadas
• 3 flujos de trabajo de GitHub Actions para mantenimiento automatizado
• 1,094 commits en 2 años de desarrollo activo

Planes a Futuro

El sistema continúa evolucionando conforme crece el negocio. Estas son las áreas clave de desarrollo en curso y planificado:

Aplicación Móvil

Una aplicación móvil complementaria está actualmente en beta, construida sobre Supabase. Expandirá las funcionalidades orientadas al alumno como inscripción, visualización de horarios y notificaciones en tiempo real directamente en sus teléfonos.

Expansión del Sistema de Retroalimentación

El esquema de Supabase ya soporta retroalimentación de cursos con calificaciones de 5 estrellas y reseñas escritas. La siguiente fase mostrará estos datos en el panel administrativo para monitoreo de calidad y evaluación de instructores.

Cumplimiento de Eliminación de Cuentas

El seguimiento de eliminación de cuentas estilo GDPR ya está incorporado en el esquema de Supabase, preparando la plataforma para el cumplimiento de regulaciones de privacidad conforme escala.

Enlaces y Recursos del Proyecto

Servicios en Vivo

• Sistema Administrativo - La plataforma administrativa en vivo
• Sitio Web Principal - El sitio web público de la academia de baile
• Sitio de Barra - El sistema de pedidos de barra para eventos

Código y Recursos

• Repositorio en GitHub - Código fuente y README
• Video Demostrativo - Demo completo del sistema administrativo

Proyectos Relacionados

• Sitio Web de Salsa Candela - Artículo sobre el sitio web público
• Barra de Salsa Candela - Artículo sobre el sistema de pedidos de barra
• API de CoDi - Artículo sobre el API de pagos utilizado en este proyecto