Sistema de mapeo interactivo para la Universidad Catolica del Norte (UCN) - Campus Coquimbo, que permite la navegacion y busqueda de ubicaciones dentro del campus universitario mediante Progressive Web App (PWA).

Elige una de las siguientes opciones según tu sistema operativo:

Opción A: Docker (Recomendado para Windows/Mac)

• Docker Desktop (Incluye Docker Compose)
• En Windows: Asegúrate de tener WSL 2 activado.

Opción B: Podman (Recomendado para Linux)

• Podman 4.x o superior
• Podman Compose

1. Clonar repositorio

   git clone https://github.com/esteban-escudero/InteractiveMapUCN.git
   cd InteractiveMapUCN

2. Configurar variables de entorno

   cp .env.example .env
   # El archivo .env ya viene preconfigurado para desarrollo

3. Iniciar servicios

   Si usas Docker:

   # Opción recomendada para desarrollo (con hot-reload y correcciones de entorno)
   docker compose -f compose.yaml -f compose.dev.yaml up -d

   Si usas Podman:

   podman compose up -d

# Docker
docker compose ps

# Podman
podman ps

Para Docker:

# Ver logs en tiempo real
docker compose logs -f

# Detener servicios
docker compose down

# Reiniciar todo desde cero (útil si hay errores)
docker compose down -v
docker compose -f compose.yaml -f compose.dev.yaml up -d --force-recreate

Para Podman:

# Ver logs
podman compose logs -f

# Detener servicios
podman compose down

InteractiveMapUCN es una Progressive Web App (PWA) de tipo Sistema de Información Geográfica (SIG/GIS) Web diseñada para facilitar la orientación y navegación dentro del campus Coquimbo de la UCN. Los usuarios podrán acceder directamente desde su navegador web sin necesidad de instalación de aplicaciones nativas.

Aplicación nativa: se refiere a una app que está desarrollada específicamente para un sistema operativo o plataforma en particular, usando sus lenguajes y herramientas propias. ¿Qué la hace "nativa"?:

• Se instala directamente en el dispositivo.
• Accede de forma directa al hardware (cámara, GPS, sensores, etc.).
• Tiene mejor rendimiento y una experiencia de usuario más fluida.
• Sigue las guías visuales y de comportamiento del sistema operativo.

• Categoría: Sistema de Información Geográfica (SIG/GIS) Web
• Arquitectura: Progressive Web App (PWA) Full-Stack
  • PWA (Progressive Web App): Aplicación web que utiliza tecnologías web modernas para ofrecer una experiencia similar a una aplicación nativa, incluyendo instalación, funcionamiento offline y notificaciones push.
  • Full-Stack: Arquitectura que incluye tanto el frontend (interfaz de usuario) como el backend (servidor y base de datos) desarrollados de manera integrada.

1. Acceso Universal: No requiere descarga desde tiendas de aplicaciones, accesible directamente desde cualquier navegador web
2. Multiplataforma: Funciona en iOS, Android, Windows y macOS sin desarrollo separado
3. Actualización Simplificada: Las actualizaciones se despliegan en el servidor, los usuarios siempre tienen la versión más reciente
4. Bajo Costo de Desarrollo: Un solo código base para todas las plataformas
5. Soporte Offline: Capacidad de funcionar con conexión limitada mediante Service Workers
6. Instalación Directa: Los usuarios pueden "instalar" la PWA en su pantalla de inicio
7. Optimización para Campus: Ideal para entorno educativo con múltiples dispositivos y usuarios temporales
8. Menor Barrera de Entrada: Estudiantes y visitantes pueden acceder inmediatamente sin descargas

• Dominio: Educación Superior / Campus Universitario
• Campus: Coquimbo, Chile
• Acceso: Navegador Web
• Complejidad: Medio-Alto

• Orientación en campus universitario
• Búsqueda de ubicaciones (edificios, salas, servicios)
• Geolocalización en tiempo real
• Cálculo de rutas inteligentes con dos perfiles (peatonal y accesible)
• Navegación asistida desde ubicación actual
• Gestión administrativa de edificios, salas y rutas
• Acceso público sin autenticación para usuarios

• Mapa Interactivo: Visualización del campus usando Leaflet con capas personalizadas
• PWA: Funciona como app nativa, instalable, con soporte offline
• Búsqueda Inteligente: Encuentra edificios y salas por nombre con autocompletado
• Geolocalización GPS: Muestra tu ubicación actual en el mapa con marcador animado
• Navegación desde Mi Ubicación: Calcula rutas desde tu posición actual al destino
• Cálculo de Rutas Inteligente: 2 perfiles de rutas con algoritmo de Dijkstra
  • Peatonal: Ruta estándar para caminar
  • Accesible: Adaptada para personas con movilidad reducida (evita obstáculos/escaleras)
• Colores por Categoría: Edificios coloreados según su tipo (académico, administrativo, servicios, etc.)
• Navegación por URL: Permite compartir rutas directas mediante enlaces (ej: /rutas/G5-35)
• Modo Oscuro: Interfaz adaptable para mayor comodidad
• Diseño Responsive: Optimizado para móviles y tablets

• Sistema de Autenticación: Login seguro con JWT
• Gestión de Edificios: CRUD completo con soporte para polígonos y puntos
• Estadísticas: Visualización rápida del conteo de salas y planos registrados
• Gestión de Salas: Administración de salas por edificio con diseño de grid 3 columnas
• Gestión de Imágenes: Subida y administración de planos por edificio y piso
• Análisis de Proximidad: Herramientas para analizar distancias entre edificios y rutas
• Análisis Espacial: Cálculo de rutas óptimas y análisis geoespacial avanzado
• Gestión de Rutas: Creación y edición de rutas con múltiples segmentos (polylines)
• Gestión de Usuarios: Administración de cuentas de administradores
• Panel de Control: Vista completa de edificios, rutas y estadísticas
• Material Icons: Interfaz moderna con iconos de Material Design

La elección de cada componente del stack se basó en el equilibrio entre rendimiento, escalabilidad y soporte para datos geoespaciales.

El sistema sigue una arquitectura desacoplada para separar responsabilidades y facilitar el mantenimiento.

graph TD
     User["Usuario / Admin"] -->|HTTPS| Nginx["Nginx Reverse Proxy"]
    Nginx -->|Static Assets| Frontend["Frontend React PWA"]
    Nginx -->|/api| Backend["Backend Node.js Express"]
    Backend -->|SQL / Geo Queries| DB[("PostgreSQL + PostGIS")]
    Backend -->|Read/Write| FS["File System<br/>(Images)"]

Explicación del Diagrama de Arquitectura:

Este diagrama representa la arquitectura desacoplada del sistema Mapa Interactivo UCN:

1. Usuario/Admin → Nginx Reverse Proxy:

   • Los usuarios y administradores acceden al sistema mediante HTTPS
   • Nginx actúa como puerta de entrada única para todas las solicitudes

2. Nginx → Frontend React PWA:

   • Las solicitudes para archivos estáticos (HTML, CSS, JS, imágenes) son servidas directamente por el frontend
   • El frontend es una Progressive Web App (PWA) construida con React

3. Nginx → Backend Node.js Express:

   • Las solicitudes que comienzan con /api son redirigidas al backend
   • El backend está construido con Node.js y Express

4. Backend → PostgreSQL + PostGIS:

   • El backend realiza consultas SQL y consultas geoespaciales a la base de datos
   • PostgreSQL con la extensión PostGIS almacena todos los datos espaciales

5. Backend → File System (Images):

   • El backend también maneja la lectura/escritura de archivos de imágenes en el sistema de archivos
   • Esto incluye planos de edificios y otras imágenes estáticas

Ventajas de esta arquitectura:

• Separación clara de responsabilidades: Cada componente tiene un propósito específico
• Escalabilidad: Cada capa puede escalarse independientemente
• Seguridad: Nginx actúa como firewall de aplicación
• Mantenibilidad: Cambios en un componente no afectan necesariamente a los otros

MVC (Modelo-Vista-Controlador): Patrón de arquitectura de software que separa la lógica de negocio (Model), la interfaz de usuario (Vista) y el control de flujo (Controlador).

Implementa una división en capas para aislar la lógica de negocio del acceso a datos:

1. Routes Layer: Define los endpoints y aplica middlewares (como validación de JWT). Endpoints: URLs específicas que responden a solicitudes HTTP en una API. Middlewares: Funciones intermedias que procesan solicitudes antes de que lleguen al controlador final.
2. Controller Layer: Maneja la comunicación HTTP y formatea las respuestas. Controller: Componente que recibe solicitudes HTTP, interactúa con los servicios y devuelve respuestas.
3. Service Layer: Contiene la lógica de negocio pura y algoritmos complejos (e.g., Dijkstra). Service Layer: Capa que encapsula la lógica de negocio independiente de la API y la base de datos.
4. Data Access Layer (Models): Interactúa directamente con PostgreSQL/PostGIS. Models: Representaciones de las entidades de negocio y su interacción con la base de datos.

Estructurado para una alta interactividad:

• Context Providers: Gestión de estado global (Autenticación, Mapa). Context Providers: Mecanismo de React para compartir datos entre componentes sin pasar props manualmente.
• Custom Hooks: Encapsulan la lógica de geolocalización y cálculos (useMap, useRoute). Custom Hooks: Funciones personalizadas de React que encapsulan y reutilizan lógica de estado y efectos.
• PWA Core: Service Workers para soporte offline y manifiesto para instalación. Service Workers: Scripts que se ejecutan en segundo plano para manejar solicitudes de red y almacenamiento en caché. Manifiesto: Archivo JSON que describe la PWA (nombre, iconos, colores, etc.) para instalación.

El motor PostgreSQL + PostGIS es la pieza central para el manejo de datos espaciales con SRID 4326 (WGS 84).

SRID 4326: Identificador del Sistema de Referencia Espacial WGS 84, utilizado por GPS y sistemas de mapeo global.

erDiagram
    edificio ||--o{ plano : "posee"
    edificio ||--o{ sala : "contiene"
    administrador ||--o{ refresh_tokens : "gestiona"
    ruta {
        GEOMETRY geometria_ruta
        VARCHAR tipo_ruta
    }
    edificio {
        GEOMETRY ubicacion
        VARCHAR tipo
    }

Explicación del Diagrama ER (Entity-Relationship):

Este diagrama representa las principales entidades y sus relaciones en la base de datos:

1. edificio (entidad):

   • Contiene los edificios del campus
   • Atributos: ubicacion (GEOMETRY - Polygon), tipo (VARCHAR - tipo de edificio)
   • Relaciones:
     • ||--o{ plano: Un edificio puede tener cero o muchos planos
     • ||--o{ sala: Un edificio contiene cero o muchas salas

2. plano (entidad):

   • Almacena los planos/pisos de cada edificio
   • Relación: edificio ||--o{ plano (un edificio posee múltiples planos)

3. sala (entidad):

   • Representa las salas, oficinas y espacios dentro de los edificios
   • Relación: edificio ||--o{ sala (un edificio contiene múltiples salas)

4. ruta (entidad):

   • Almacena los segmentos de rutas para navegación
   • Atributos: geometria_ruta (GEOMETRY - LineString), tipo_ruta (VARCHAR - peatonal/accesible)

5. administrador (entidad):

   • Contiene las cuentas de administradores del sistema
   • Relación: ||--o{ refresh_tokens (un administrador gestiona múltiples refresh tokens)

6. refresh_tokens (entidad):

   • Almacena los tokens de refresco para la autenticación JWT
   • Relación: administrador ||--o{ refresh_tokens (gestión de tokens por administrador)

• ST_Distance: Cálculo de distancias reales en metros. ST_Distance: Función PostGIS que calcula la distancia más corta entre dos geometrías en unidades de medida específicas.

• ST_Contains: Determinación de puntos dentro de edificios. ST_Contains: Función PostGIS que determina si una geometría contiene completamente a otra.

• ST_AsGeoJSON: Conversión nativa para visualización en Leaflet. ST_AsGeoJSON: Función PostGIS que convierte geometrías al formato GeoJSON para uso en aplicaciones web.

El proyecto podría significar un impacto tangible en la comunidad universitaria:

• Inclusión Real: Implementación efectiva de rutas para movilidad reducida.
• Modernización: Primer SIG web especializado para el Campus Coquimbo.
• Rendimiento: Tiempos de cálculo de ruta menores a 200ms mediante optimización de grafos.
• Disponibilidad: Acceso público sin autenticación para usuarios.
• Flexibilidad: Interfaz responsive para dispositivos móviles y tablets.
• Escalabilidad: Podría ser implementado en otros campus universitarios.

El cálculo de rutas es el núcleo tecnológico del proyecto. Se utiliza el algoritmo de Dijkstra sobre un grafo dinámico generado a partir de datos espaciales.

• Dijkstra: Algoritmo clásico para encontrar el camino más corto entre nodos en un grafo con pesos no negativos.
• Grafo: Estructura de datos compuesta por nodos (vértices) conectados por aristas con pesos asociados.

flowchart LR
    A[Inicio] --> B{"Validar Puntos"}
    B -->|Válido| D["Obtener Rutas DB"]
    D --> E["Construir Grafo"]
    E --> F["Filtrar Tipo (Peatonal/Accesible)"]
    F --> G["Ejecutar Dijkstra"]
    G --> H["Generar GeoJSON"]
    H --> I[Fin]

Explicación del Diagrama de Flujo de Navegación:

Este diagrama describe el proceso completo para calcular una ruta entre dos puntos:

1. Inicio: El proceso comienza cuando un usuario solicita calcular una ruta

2. Validar Puntos:

   • Se verifica que ambos puntos (origen y destino) sean válidos
   • Se comprueba que estén dentro del campus
   • Si no son válidos, el proceso termina con un error

3. Obtener Rutas DB:

   • Se consulta la base de datos para obtener todos los segmentos de ruta disponibles
   • Esto incluye rutas peatonales y accesibles
   • Se filtran por área geográfica relevante

4. Construir Grafo:

   • Los segmentos de ruta se convierten en un grafo matemático
   • Nodos = intersecciones/puntos de conexión
   • Aristas = segmentos de ruta con peso = distancia

5. Filtrar Tipo:

   • Según la selección del usuario, se filtra por:
     • Peatonal: Todas las rutas disponibles
     • Accesible: Solo rutas marcadas como accesibles (sin escaleras, con rampas)

6. Ejecutar Dijkstra:

   • Se aplica el algoritmo de Dijkstra al grafo filtrado
   • Encuentra el camino más corto entre origen y destino
   • Considera pesos (distancias) para optimización

7. Generar GeoJSON:

   • La ruta calculada se convierte al formato GeoJSON
   • GeoJSON es estándar para representar datos geográficos en la web
   • Incluye geometría LineString y metadatos

8. Fin:

   • La ruta se devuelve al frontend para visualización
   • Se muestra en el mapa interactivo de Leaflet

El acceso administrativo está protegido mediante un flujo de autenticación robusto basado en JWT y validación de sesiones.

sequenceDiagram
    participant Admin
    participant Frontend
    participant API (Node.js)
    participant DB (PostGIS)

    Admin->>Frontend: Login Credentials
    Frontend->>API: POST /auth/login
    API->>DB: Verify & Compare Hash
    DB-->>API: Validated
    API-->>Frontend: Set JWT Token
    Frontend->>Admin: Redirect to Dashboard

Explicación del Diagrama de Secuencia de Autenticación:

Este diagrama muestra el proceso completo de autenticación de un administrador:

1. Admin → Frontend: Login Credentials

   • El administrador ingresa sus credenciales (usuario y contraseña) en la interfaz del frontend

2. Frontend → API: POST /auth/login

   • El frontend envía las credenciales al backend mediante una solicitud HTTP POST al endpoint /auth/login
   • Las credenciales se envían de forma segura (HTTPS)

3. API → DB: Verify & Compare Hash

   • El backend (Node.js + Express) recibe las credenciales
   • Consulta la base de datos para encontrar el usuario
   • Compara el hash de la contraseña proporcionada con el hash almacenado
   • Hash: Función criptográfica que transforma datos de entrada en una cadena de longitud fija, ideal para almacenar contraseñas de forma segura.

4. DB → API: Validated

   • La base de datos responde indicando si las credenciales son válidas
   • Si son válidas, procede con la generación del token

5. API → Frontend: Set JWT Token

   • El backend genera un token JWT (JSON Web Token) firmado
   • El token contiene información del usuario y tiempo de expiración
   • Se envía al frontend en la respuesta HTTP

6. Frontend → Admin: Redirect to Dashboard

   • El frontend almacena el token JWT de forma segura (HttpOnly cookie o localStorage)
   • Redirige al administrador al panel de control/dashboard
   • En solicitudes futuras, el token se incluye en el header Authorization

Este diagrama ilustra cómo el sistema interactúa con el usuario para proporcionar navegación en tiempo real:

sequenceDiagram
    autonumber
    actor User as Usuario
    participant Frontend as Frontend (React PWA)
    participant API as Backend (Node.js)
    participant DB as Base de Datos (PostGIS)

    User->>Frontend: Selecciona Origen y Destino
    User->>Frontend: Elige tipo de ruta (Peatonal/Accesible)
    Frontend->>API: POST /api/routes/calculate
    Note over API: Carga todas las rutas de la DB
    API->>DB: query: SELECT * FROM rutas
    DB-->>API: Listado de geometrías (LineStrings)
    
    rect rgba(0, 0, 0, 0)
        Note over API: Procesamiento del Grafo
        API->>API: Construir Grafo desde geometrías
        API->>API: Fusionar nodos cercanos (Intersecciones)
        API->>API: Identificar nodos más cercanos a origen/destino
        API->>API: Ejecutar Algoritmo de Dijkstra
    end

    API-->>Frontend: GeoJSON (Ruta, Distancia, Tiempo)
    Frontend->>Frontend: Renderiza ruta con Leaflet
    Frontend-->>User: Visualiza el camino óptimo en el mapa

Explicación del Diagrama de Secuencia de Búsqueda de Rutas:

1. Selección de Puntos: El usuario interactúa con el mapa o el buscador para definir dónde empieza y termina su recorrido, indicando además su preferencia de accesibilidad.
2. Solicitud de Cálculo: El frontend envía las coordenadas y el perfil elegido al backend mediante un endpoint dedicado.
3. Obtención de Datos: El servidor recupera todos los segmentos de ruta almacenados en PostGIS que coinciden con el tipo de navegación solicitado.
4. Construcción del Grafo: Las geometrías (LineStrings) se transforman en una estructura de red (grafo). Se realiza un proceso de "fusión" para asegurar que los segmentos que se tocan o están muy cerca (intersecciones) queden conectados correctamente.
5. Optimización con Dijkstra: Se identifica el punto de la red más cercano al origen y al destino del usuario, y se aplica el algoritmo para encontrar la ruta con la menor distancia total.
6. Respuesta y Visualización: El resultado se envía en formato GeoJSON, que incluye la línea exacta que el usuario debe seguir, junto con la distancia total y el tiempo estimado. El mapa de Leaflet dibuja esta línea automáticamente.