Arquitectura de un sistema de reservas en tiempo real: integrando Angular, FastAPI, PostgreSQL y n8n

Cuando diseñamos la arquitectura del sistema de reservas detrás de Omega Libera, el requisito principal no era simplemente pintar un calendario en una interfaz web. El verdadero reto de ingeniería consistía en permitir que dos canales completamente distintos —un panel de administración en Angular operado por el dueño del local y un agente conversacional en WhatsApp orquestado con n8n— consultaran y modificaran la misma agenda en tiempo real sin provocar solapamientos ni datos desactualizados.

1. El problema de las agendas desconectadas

En muchos pequeños negocios que intentan automatizar sus reservas con flujos simples, es habitual encontrar hojas de cálculo o calendarios externos sincronizados mediante tareas programadas (polling). Ese enfoque falla en cuanto ocurren dos eventos habituales en el mundo real:

• Un estilista o empleado cambia su turno o añade un bloqueo de descanso desde el panel de control mientras un cliente está preguntando por WhatsApp qué huecos quedan libres esa misma tarde.
• Un cliente solicita una combinación de servicios con duraciones distintas (por ejemplo, 45 minutos frente a 90 minutos) y el sistema debe calcular si cabe entre dos citas ya existentes sin invadir el descanso del profesional.

2. FastAPI + PostgreSQL como única fuente de verdad

Para evitar inconsistencias, centralizamos toda la lógica de negocio en un servicio backend construido con Python y FastAPI sobre una base de datos relacional PostgreSQL, empaquetado en contenedores Docker:

[Cliente en WhatsApp / Web] ---> [Flujo n8n + Agente IA] 
                                           |
                                           v (HTTP REST / JSON)
[Panel Admin en Angular] ------> [API Core en FastAPI] <---> [PostgreSQL]

En lugar de que el flujo de n8n intente calcular por su cuenta qué horas están libres, el agente conversacional invoca un endpoint específico de disponibilidad en FastAPI. Este endpoint cruza cuatro entidades relacionales en PostgreSQL:

1. Duración y reglas del servicio solicitado.
2. Cuadrante horario base del empleado asignado.
3. Descansos y excepciones puntuales (ausencias, cierres festivos o bloqueos manuales).
4. Reservas confirmadas o pendientes en esa franja.

3. Contratos tipados entre Angular y FastAPI

En el lado del panel administrativo, utilizamos Angular y TypeScript dividiendo la aplicación en 7 módulos funcionales (Empleados, Clientes, Servicios, Métricas, Tablas IA, Documentos y Empresa).

Gracias a los esquemas de validación de Pydantic en FastAPI y las interfaces estrictas en TypeScript, cualquier cambio que el administrador guarda en el módulo de Servicios o Empleados actualiza de inmediato las restricciones que consume el motor de disponibilidad.

4. Aprendizajes clave

• Lógica determinista en el backend, lenguaje natural en el borde: Los modelos de lenguaje son excelentes para entender la intención del usuario en WhatsApp («¿tenéis hueco mañana después de comer?»), pero el cálculo de intervalos horarios y la reserva transaccional deben recaer siempre sobre código determinista en el backend y transacciones en PostgreSQL.
• Docker desde el inicio: Contenerizar la API, la base de datos y las herramientas de automatización reduce drásticamente la fricción al desplegar nuevas instancias personalizadas para cada negocio.