# Arquitectura Dashboard Datos API

> Arquitectura completa de un dashboard web que consume APIs de datos externas. Patrón inspirado en ESIOS Dashboard — estructura de 5 capas: config, infra, dominio, shared, presentación.

- Skill: `ntizar/arquitectura-dashboard-datos-api` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add ntizar/arquitectura-dashboard-datos-api`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ntizar/arquitectura-dashboard-datos-api/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- License: MIT
- Author: ntizar (https://skillmd.com/u/ntizar)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ntizar/arquitectura-dashboard-datos-api

---


# Arquitectura Dashboard con Datos de APIs Externas

Patrón validado en el proyecto ESIOS Dashboard (24.469 líneas, Node.js + HTML vanilla + Chart.js).

## Flujo completo del dato

```
API externa (ESIOS/REE)
    │
    ▼
[Cliente HTTP] → reintentos, backoff, jitter
    │
    ├──► [Cache Disco] → persiste respuestas (TTL)
    │
    ▼
[Servicio Dominio] → normalización, conversión unidades, merge
    │
    ├──► [Cache Memoria] → LRU con métricas (hits/misses)
    │
    ▼
[API REST] → /api/v1/summary, /api/v1/indicator, /healthz, /readyz
    │
    ▼
[Frontend Vanilla] → state.js → data.js → api.js → render*.js
```

## Principios clave

### 1. Capa de cliente API independiente
- Un solo módulo `clients/api.client.js` que maneja HTTP, reintentos, tokens
- NUNCA mezclar lógica de negocio con fetch
- Siempre cachear antes de retornar

### 2. Cache multicapa defensiva
- **Capa 1 (memoria)**: responde en <1ms, ideal para requests repetidos en misma sesión
- **Capa 2 (disco)**: persiste entre reinicios, reduce peticiones a la API externa
- Ambas con TTL configurable y mecanismo de limpieza

### 3. Dominio separado de infraestructura
- `src/domains/` → lógica de negocio (resumen, forecast, agregación)
- `src/infra/` → caché, clientes HTTP, repositorios
- `src/shared/` → utilidades transversales (timezones, unidades)
- `src/config/` → validación de entorno

### 4. Frontend sin framework, con estado centralizado
- `AppState` global → única fuente de verdad
- Persistencia en URL hash + localStorage
- Carga orquestada desde `data.js`, render delegado a módulos especializados

### 5. Contrato API estable
- Endpoints con nombres en español
- Estructura de respuesta documentada en README
- versionado semántico en los datos

## Cuándo aplicar este patrón

- Dashboards con datos de APIs externas (1 o múltiples fuentes)
- Proyectos que necesitan forecast/análisis sobre datos históricos
- Cuando quieres cache agresiva para no malgastar créditos de API
- Cuando necesitas que funcione sin frameworks pesados (vanilla JS)

## Anti-patrones que evitar

- ❌ Llamar a la API externa desde el frontend (expone tokens)
- ❌ Mezclar lógica de cache con lógica de negocio
- ❌ No validar fechas/timezones (todo dashboard tiene fechas)
- ❌ Un solo punto de fallo en el fetch paralelo (usar Promise.allSettled + fetchIndicatorSafe)

## Referencia

- Proyecto ESIOS Dashboard: github.com/Ntizar/esios-dashboard
- Skills relacionadas: api-cliente-http-robusto, cache-multicapa-memoria-disco, fetch-paralelo-fallos-parciales, servicio-resumen-consolidado