README.md

May 12, 2026 · View on GitHub

flAIghts

Planificador inteligente de vuelos optimizado mediante algoritmos de grafos e IA.

Node.js React TypeScript MongoDB Ollama Three.js Tailwind CSS

✈️ Sobre el Proyecto

flAIghts es una plataforma avanzada para la planificación de rutas aéreas que combina la potencia de algoritmos clásicos de optimización con datos en tiempo real. El sistema no solo busca vuelos, sino que diseña la trayectoria más eficiente (en coste o tiempo) permitiendo la inclusión de escalas intermedias obligatorias.

Características Principales

  • 🔍 Búsqueda Inteligente: Encuentra rutas óptimas basadas en múltiples criterios.
  • 🤖 IA Local: Integración con Ollama para el procesamiento inteligente de consultas mediante LLMs (Qwen 2.5).
  • 🌐 Visualización 3D: Experiencia inmersiva con un globo terráqueo interactivo desarrollado en Three.js.
  • 📍 Escalas Personalizadas: Soporte para paradas obligatorias durante el trayecto.
  • ⚡ Optimización de Grafos: Implementación del algoritmo Dijkstra para garantizar la eficiencia y encontrar la ruta óptima en el grafo de vuelos.
  • 💾 Caché Persistente: Uso de MongoDB para minimizar latencias y costes de API.
  • 🌍 Datos Reales: Integración con SerpAPI (Google Flights).

🛠️ Stack Tecnológico

ComponenteTecnología
Inteligencia ArtificialOllama (Local LLMs), OpenAI SDK
Visualización 3DThree.js (Globo interactivo)
FrontendReact 19, Vite, Tailwind CSS v4, GSAP, TanStack Query
BackendNode.js 22, Express, TSOA, Mongoose, Zod
Base de DatosMongoDB 8
InfraestructuraDocker, Docker Compose, MinIO (S3), Mailpit
API ExternaSerpAPI (Google Flights)

🚀 Guía de Inicio Rápido

Prerrequisitos

  • Node.js (v18 o superior)
  • Docker & Docker Compose
  • Una API Key de SerpAPI

Configuración del Entorno

  1. Clona el repositorio:

    git clone https://github.com/tu-usuario/flAIghts.git
cd flAIghts

  2. Configura las variables de entorno: Crea un archivo .env en la raíz del proyecto.

    Obligatorio:

    SERPAPI_API_KEY=tu_api_key_aqui  # Necesaria para obtener precios de vuelos reales

    Opcional (para habilitar Google Login):

    VITE_GOOGLE_CLIENT_ID=tu_google_client_id
GOOGLE_CLIENT_ID=tu_google_client_id

Nota: El servidor está diseñado para ser interactivo; si falta alguna variable de entorno crítica durante el inicio, se solicitará automáticamente a través de la terminal.

Instalación y Despliegue con Docker

Este proyecto está completamente dockerizado, lo que facilita enormemente su despliegue:

  1. Levantar el proyecto: Desde la raíz, ejecuta el siguiente comando para construir e iniciar todos los servicios (Base de datos, Backend, Frontend y utilidades):

    docker compose up -d

  2. Ejecutar migraciones: Una vez que los contenedores estén en marcha, debes poblar la base de datos con la información de aeropuertos y aerolíneas:

    # Migración de aeropuertos
docker compose exec server npx tsx scripts/migrations/airportsMigration.ts

# Migración de aerolíneas
docker compose exec server npx tsx scripts/migrations/airlinesMigration.ts

🌐 Acceso a los Servicios

ServicioURLCredenciales (Dev)
Frontendhttp://localhost:5173-
Backend APIhttp://localhost:3000-
Mailpit (Simulador de Email)http://localhost:8025-
MinIO (Almacenamiento S3)http://localhost:9001admin / admin123

🗄️ Administración de la Base de Datos

Para explorar y manipular los datos de desarrollo, puedes utilizar herramientas como MongoDB Compass.

Conexión local

Utiliza la siguiente URI para conectarte a la instancia de MongoDB en Docker:

mongodb://root:1234@localhost:27017/flAIghts?authSource=admin

Gestión de Roles (Superadmin)

Por razones de seguridad, no existe un registro directo para administradores. Si necesitas que un usuario tenga privilegios de superadmin (para acceder al panel de administración y ver métricas avanzadas), sigue estos pasos:

  1. Regístrate normalmente desde la aplicación frontend.
  2. Abre la base de datos con Compass u otra herramienta.
  3. Busca el documento del usuario en la colección users de la base de datos flAIghts.
  4. Cambia manualmente el valor del campo role de "user" a "superadmin".

🏗️ Consideraciones de Producción

El archivo docker-compose.yaml incluido está optimizado exclusivamente para entornos de desarrollo. Para un despliegue en producción, ten en cuenta lo siguiente:

  • Imágenes Docker: Puedes utilizar las imágenes generadas por el proyecto, pero asegúrate de usar los archivos Dockerfile de producción (si existen) o configurar adecuadamente los comandos de inicio en tu orquestador.
  • Variables de Entorno: Es crítico configurar correctamente las variables de entorno de producción (como NODE_ENV=production, MONGODB_URI a una instancia segura, secretos de JWT fuertes, etc.).
  • Persistencia y Seguridad: No utilices las credenciales por defecto de MongoDB o MinIO en producción. Se recomienda usar servicios gestionados para la base de datos y el almacenamiento de objetos.
  • Escalabilidad: Considera el uso de un orquestador como Kubernetes o servicios de nube tipo PaaS para gestionar el escalado y la disponibilidad de los servicios.

📊 Analytics y Reportes

El proyecto incluye herramientas avanzadas de análisis de usabilidad, con capacidad para exportar reportes en HTML y visualizaciones de datos (SUS, KDE distributions) para evaluar la experiencia del usuario.

  • Modo Evaluación: Por defecto, el modo evaluación está activado en el entorno de desarrollo para facilitar las pruebas del TFG.
  • Configuración: Puedes desactivarlo cambiando la variable de entorno VITE_EVALUATION_MODE a false en tu archivo .env.

📄 Licencia

Este proyecto está bajo la Licencia MIT. Consulta el archivo LICENSE para más detalles.

Desarrollado con ❤️ para el TFG de Ingeniería Informática en la Universidad Complutense de Madrid.