DAGEA

📋 Resumen Ejecutivo

Visión del Proyecto

DAGEA (Geografía Aplicada y Cartografía Inteligente) es una plataforma web GIS profesional diseñada para investigadores, educadores y profesionales del análisis espacial. Su objetivo es democratizar el acceso a herramientas avanzadas de cartografía e inteligencia artificial sin sacrificar potencia técnica.

Enfoque Técnico

• Arquitectura: Monorepo modular con separación clara de responsabilidades
• Frontend: Progresivo (Vanilla JS → Next.js 14 + TypeScript)
• Backend: Microservicios especializados (GIS, IA, Tiles, API Gateway)
• Infraestructura: Contenedores Docker + orquestación Kubernetes (planificado)

🏗️ Arquitectura del Sistema

Estructura de Directorios (Monorepo Propuesto)

dagea/
├── apps/
│   └── web/                    # SPA principal (Next.js 14 propuesto)
│       ├── app/
│       │   ├── (auth)/         # Rutas de autenticación
│       │   └── (dashboard)/    # Rutas protegidas
│       │       ├── hub/        # Hub principal de navegación
│       │       ├── urban/      # Módulo DAGEA Urban (Mapillary)
│       │       ├── geoia/      # Módulo GeoIA (Asistente IA)
│       │       └── diseno/     # Módulo Diseño (Editor cartográfico)
│       ├── components/         # Componentes React reutilizables
│       ├── hooks/              # Custom hooks de React
│       ├── stores/             # Zustand stores
│       └── lib/                # Utilidades y configuración
│
├── packages/
│   ├── ui/                     # Sistema de diseño compartido
│   ├── geo-utils/              # Funciones geoespaciales (Turf.js wrapper)
│   └── types/                  # Tipos TypeScript compartidos
│
├── services/
│   ├── api-gateway/            # Fastify + validación + rate limiting
│   ├── gis-service/            # Análisis pesado (Turf + Bull queues)
│   ├── ai-service/             # Proxy LLM con contexto geográfico
│   └── tile-service/           # Martin / PMTiles
│
└── infra/
    ├── docker-compose.yml      # Desarrollo local
    └── k8s/                    # Manifiestos Kubernetes

Diagrama de Flujo de Datos

┌─────────────────┐
│   Frontend      │
│   (Next.js)     │
└────────┬────────┘
         │ HTTPS / JSON
         ▼
┌─────────────────┐
│  API Gateway    │
│  (Fastify)      │
└────┬────┬────┬──┘
     │    │    │
     ▼    ▼    ▼
┌────────┐ ────────┐ ┌────────┐
│ GIS    │ │ AI     │ │ Tiles  │
│ Service│ │ Service│ │ Service│
└────┬───┘ └────┬───┘ └────┬───┘
     │          │          │
     ▼          ▼          ▼
┌────────┐ ────────┐ ┌────────
│PostGIS │ │Gemini  │ │Martin/ │
│Redis   │ │AI Studio│ │PMTiles│
└────────┘ └────────┘ └────────┘

💻 Stack Tecnológico

Frontend Actual (Fase 1)

Backend y Servicios

🧩 Módulos — Estado Actual

1. DAGEA Urban

Archivo: urban.html

Descripción: Georreferenciación urbana con imágenes a nivel de calle.

Características técnicas:

• Integración con Mapillary Graph API (token en objeto CFG)
• Visor 360° con Pannellum (carga directa de thumb_original_url)
• Marker clustering optimizado para miles de puntos
• LRU cache para bounding boxes de consultas espaciales
• Renderizado en batches con requestIdleCallback
• AbortController para cancelar requests obsoletos
• Exportación PDF/PNG con html2canvas + jsPDF

Endpoints utilizados:

GET https://graph.mapillary.com/images?bbox={minLon},{minLat},{maxLon},{maxLat}
GET https://images.mapillary.com/{id}/thumb-2048.jpg

2. GeoIA

URL: https://dagea-ai.onrender.com

Descripción: Asistente de IA especializado en geografía y cartografía.

Arquitectura:

Frontend (Vanilla JS) → Backend (Express + Node.js) → Gemini API

Características técnicas:

• Backend Node.js desplegado en Render.com
• Autenticación vía header X-goog-api-key
• Prompt del sistema contextualizado para enseñanza geográfica
• Respuestas en español con formato markdown básico

Variables de entorno requeridas:

GEMINI_API_KEY=AIzaSy...          # API Key de Google AI Studio
NODE_ENV=production               # Entorno de ejecución
PORT=3000                         # Puerto (Render asigna dinámicamente)

Endpoint principal:

POST /api/chat
Body: { "message": "Pregunta del usuario" }
Response: { "response": "Respuesta de GeoAI" }

3. Diseño DAGEA (Beta)

Archivo: diseno.html

Descripción: Editor cartográfico tipo Canva para composición de mapas.

Características:

• Fabric.js para manipulación de objetos vectoriales
• Integración con Leaflet para captura de base cartográfica
• Sistema de plantillas predefinidas
• Exportación a PNG/PDF con resolución configurable

🚧 Módulos en Desarrollo (9/12)

🎨 Hub Principal

Archivo: dagea-hub-v3.html

Concepto de Diseño

No es una landing page tradicional. Es un dashboard GIS estilo sala de control cartográfica, inspirado en Linear, Vercel y terminales Bloomberg.

Sistema de Diseño

Paleta de Colores (CSS Variables)

:root {
  /* Fondos */
  --ink:        #050a0e;    /* Fondo principal ultra oscuro */
  --deep:       #0a1620;    /* Fondos secundarios */
  --panel:      #0d1e2d;    /* Paneles */
  --surface:    #13293d;    /* Superficies elevadas */
  
  /* Acentos - Verde Oliva */
  --olive:      #6b8e23;    /* Verde oliva base */
  --olive-br:   #88b02c;    /* Verde oliva medio */
  --olive-lt:   #a4ce3e;    /* Verde oliva acento principal */
  
  /* Texto */
  --fog:        #a8bcc8;    /* Texto secundario */
  --mist:       #5e7a8a;    /* Texto terciario */
  
  /* Estados */
  --amber:      #ffb432;    /* Badge BETA */
  --red:        #ff4759;    /* Errores */
  --success:    #00ff88;    /* Confirmaciones */
}

Tipografía

Estructura de la Interfaz

1. Rail Lateral Izquierdo (68px) - Navegación con íconos y tooltips
2. Topbar Superior (46px) - Estado del sistema, versión, coordenadas LIVE
3. Hero Section - Mega logo, parallax, equalizer animado, métricas
4. Módulos — Cinta Horizontal - Cards con scroll drag-to-scroll
5. Modal "Módulo no activo" - Preview de módulos en desarrollo
6. Sección Acerca - Contenido con radial glow
7. Footer Strip - Copyright y links esenciales

Efectos Visuales Implementados

• Red Neuronal Canvas - Fondo animado con nodos y conexiones
• Parallax de Blobs - 4 blobs con scroll + mouse X/Y
• Grain/Noise Overlay - SVG turbulence (4% opacity)
• Scanlines CRT - Líneas horizontales estilo retro (1.5% opacity)
• Cursor Personalizado - Punto verde + anillo (desktop ≥1024px)
• Grid Veil - Máscara radial sobre grid sutil

🔧 Implementación Técnica

Decisiones Arquitectónicas Clave

1. Estado Compartido Global (Planificado)

// stores/mapStore.js (Zustand)
import { create } from 'zustand';

export const useMapStore = create((set, get) => ({
  center: [4.7110, -74.0721],
  zoom: 13,
  layers: [],
  
  setCenter: (center) => set({ center }),
  addLayer: (layer) => set((state) => ({ 
    layers: [...state.layers, layer] 
  })),
  
  visibleLayers: (state) => state.layers.filter(l => l.visible),
}));

2. Instancia Única de Leaflet

// lib/leaflet-instance.js
let mapInstance = null;

export const getMap = () => {
  if (!mapInstance) {
    mapInstance = L.map('map-container', {
      center: [4.7110, -74.0721],
      zoom: 13
    });
  }
  return mapInstance;
};

3. Configuración Centralizada

// lib/config.js
export const CFG = {
  mapillary: {
    token: 'MLY|...',
    apiUrl: 'https://graph.mapillary.com'
  },
  gemini: {
    apiUrl: 'https://generativelanguage.googleapis.com/v1beta',
    model: 'gemini-flash-latest'
  }
};

Problemas Técnicos Resueltos

🚀 Despliegue e Infraestructura

Configuración Actual

GeoIA (Render.com)

# render.yaml
services:
  - type: web
    name: dagea-geoia
    env: node
    buildCommand: npm install
    startCommand: node server.js
    envVars:
      - key: GEMINI_API_KEY
        sync: false
      - key: NODE_ENV
        value: production
    plan: free

Variables de Entorno

# .env.local (NO subir a Git)
GEMINI_API_KEY=AIzaSy...
NODE_ENV=production
MAPILLARY_TOKEN=MLY|...
DATABASE_URL=postgresql://user:pass@host:5432/dagea
REDIS_URL=redis://localhost:6379

Comandos de Desarrollo

# Instalar dependencias
npm install

# Iniciar servidor GeoIA local
npm run dev

# Probar frontend estático
npx live-server .

# Ejecutar tests
npm test

# Build producción
npm run build

🔌 API y Servicios

Endpoint GeoIA: /api/chat

Request

POST /api/chat
Content-Type: application/json

{
  "message": "¿Qué es un sistema de información geográfica?"
}

Response Exitosa

{
  "success": true,
  "response": "Un Sistema de Información Geográfica (SIG) es una herramienta..."
}

Códigos de Estado HTTP

🗺️ Roadmap de Desarrollo

Fase 1: Consolidación (0-3 meses)

• Migrar frontend a Next.js 14 + TypeScript
• Implementar autenticación (NextAuth o Clerk)
• Configurar PostgreSQL básico con PostGIS
• Unificar estado con Zustand
• Documentar API con OpenAPI/Swagger

Fase 2: Funcionalidad Avanzada (3-6 meses)

• Sistema de proyectos con persistencia
• Exportación asíncrona con colas (Bull + Redis)
• Conectar GeoIA con contexto del mapa
• Implementar módulos 04-06

Fase 3: Escalamiento SaaS (6-12 meses)

• Multi-tenancy con aislamiento de datos
• Planes de suscripción (free/pro/team)
• Colaboración en tiempo real (WebSockets/CRDTs)
• API pública documentada
• Marketplace de plantillas

🤝 Contribución

Flujo de Trabajo

1. Fork del repositorio principal
2. Clonar tu fork localmente:

   git clone https://github.com/TU_USUARIO/dagea-ai.git
   cd dagea-ai

3. Crear branch para tu feature:

   git checkout -b feature/nueva-funcionalidad

4. Desarrollar siguiendo estándares:
   • Commits semánticos: feat:, fix:, docs:...
   • Código tipado (TypeScript)
   • Tests para lógica crítica
5. Push y abrir Pull Request

Estándares de Código

/**
 * Calcula el buffer geoespacial.
 * @param {GeoJSON.Geometry} geometry - Geometría
 * @param {number} distance - Distancia en metros
 * @returns {Promise<GeoJSON.Polygon>} Resultado
 */
export async function calculateBuffer(geometry, distance) {
  // Implementación...
}

📎 Apéndice

Recursos Externos

• Documentación Leaflet
• Turf.js Docs
• Gemini API Guide
• Mapillary Graph API
• Pannellum Docs

Contacto y Soporte

• Desarrollador: AlexDev19992001UPTC
• Repositorio: GitHub
• Issues: Reportar bugs