06. Frontend¶

Repositorio: aclimate_v3_frontend Stack: TypeScript (97.4%), CSS (1.6%), React 19, Next.js 15

Visión General¶

El frontend es la aplicación web principal con la que interactúan los usuarios finales. Consume la WebAPI de AClimate v3 para proporcionar análisis climático, visualización de pronósticos y soporte de decisiones agronómicas.

Stack Tecnológico¶

Componente	Tecnología	Propósito
Framework	Next.js 15 (App Router)	Renderizado del lado del servidor, enrutamiento, proxy API
UI	React 19	UI basada en componentes
Lenguaje	TypeScript 5	Seguridad de tipos
Estilos	Tailwind CSS 4 + Flowbite 3	Sistema de diseño responsivo
Gráficos	ApexCharts 5 + react-apexcharts	Visualización de datos climáticos
Mapas	Leaflet + react-leaflet + leaflet-timedimension	Capas de datos espaciales
Auth	keycloak-js 26	Integración Keycloak SSO
HTTP	axios 1	Cliente API
Iconos	FontAwesome 7 + Lucide React	Sistema de iconos
PDF	jsPDF + html-to-image	Generación de reportes

Arquitectura¶

La aplicación utiliza la arquitectura App Router de Next.js con componentes tanto de servidor como de cliente:

src/
  app/
    layout.tsx          # Layout raíz con todos los providers
    page.tsx            # Página de inicio
    HomeClient.tsx      # Componente cliente de inicio
    config.ts           # Configuración de entorno
    locations/          # Módulo de estaciones meteorológicas
    spatial/            # Módulo de mapas espaciales
    scenario/           # Módulo de escenarios climáticos
    favorites/          # Estaciones favoritas
    user-profile/       # Perfil de usuario y suscripciones
    about/              # Acerca de AClimate
    api/                # Rutas proxy de API
    components/         # Componentes UI compartidos
    components_special/ # Componentes especializados
    contexts/           # Contextos React (Auth, Country, I18n, etc.)
    hooks/              # Hooks personalizados de React
    i18n/               # Internacionalización
    lib/                # Utilidades de librería
    services/           # Capa de servicios API
    types/              # Definiciones de tipos TypeScript
    utils/              # Funciones de utilidad
    configs/            # Configuraciones específicas por rama
    m/                  # Vistas específicas para móvil

Providers (layout.tsx)¶

El layout raíz envuelve la aplicación en múltiples context providers:

ColorProvider -> I18nProvider -> CookieConsentProvider -> AuthProvider -> CountryProvider -> StationsProvider

Provider	Propósito
AuthProvider	Gestión del estado de autenticación Keycloak
CountryProvider	Contexto del país seleccionado para consultas de datos
StationsProvider	Contexto de la estación meteorológica activa
I18nProvider	Internacionalización y traducciones
CookieConsentProvider	Gestión de consentimiento de cookies GDPR
ColorProvider	Personalización del color del tema

Configuración¶

Variables de entorno configuradas en tiempo de compilación (prefijo NEXT_PUBLIC_*):

Variable	Default	Descripción
NEXT_PUBLIC_ACLIMATE_API_URL	http://127.0.0.1:8000	URL base de la WebAPI
NEXT_PUBLIC_ACLIMATE_API_FRONTEND_URL	http://127.0.0.1:9000	API de Usuarios/Auth
NEXT_PUBLIC_KEYCLOAK_URL	http://localhost:8080	Servidor Keycloak
NEXT_PUBLIC_KEYCLOAK_REALM	aclimate	Realm de Keycloak
NEXT_PUBLIC_KEYCLOAK_CLIENT_ID	aclimate_admin	Cliente de Keycloak
NEXT_PUBLIC_GEOSERVER_URL	https://geo.aclimate.org/geoserver/climate_historical	GeoServer WMS
NEXT_PUBLIC_COUNTRY_NAME	Colombia	País por defecto
NEXT_PUBLIC_ACLIMATE_APP_ID	1	Identificador de aplicación

Feature flags:

NEXT_PUBLIC_SHOW_STATIONS_MODULE
NEXT_PUBLIC_SHOW_USERS_MODULE

Despliegue¶

Docker¶

Dockerfile multi-etapa con 3 etapas:

deps: Instala dependencias (npm ci)
builder: Compila Next.js con ARGs en tiempo de compilación (NEXTPUBLIC*)
runner: Imagen de producción con dumb-init, usuario no-root (nextjs), HEALTHCHECK

docker build \
  --build-arg NEXT_PUBLIC_ACLIMATE_API_URL=https://api.aclimate.org \
  --build-arg NEXT_PUBLIC_KEYCLOAK_URL=https://keycloak.aclimate.org \
  -t aclimate-v3-frontend:latest .

PM2¶

El archivo ecosystem.config.js gestiona la aplicación con el administrador de procesos PM2:

{
  name: 'aclimate_v3_hn',
  script: 'npm start',
  cwd: './src',
  instances: 1,
  port: 8005
}

CI/CD¶

Pipeline de Jenkins que:

Se conecta por SSH al servidor de despliegue
Git pull del código más reciente
npm install + npm run build
Reinicio de la aplicación con PM2

Health Check¶

GET /api/health -> 200 OK