ADR-Portal-Multi-Framework

Estado

Implementada — PR #73 (reestructura monorepo a apps/) + PR #74 (AGENTS.md + credenciales) mergeados a main el 2026-06-18.

Contexto

ingel-portal (Angular 21) está consolidado como portal de documentación/wiki del proyecto. Surge la necesidad de un portal de datos de negocio: dashboards e informes interactivos sobre facturación, trazabilidad y cumplimiento.

Tensión central: ¿se extiende ingel-portal con Angular para cubrir también los datos de negocio, o conviven dos frameworks especializados?

La decisión tiene consecuencias en:

Complejidad de build/deploy
Ergonomía para desarrollar dashboards de datos
Coherencia visual desde la perspectiva del usuario
Mantenibilidad a largo plazo en un contexto agéntico

Opciones evaluadas

Opción	Ventaja	Desventaja
Extender `ingel-portal` (Angular único)	Un solo stack, un solo repo	Angular no es la herramienta más liviana para dashboards de datos intensivos; mezcla responsabilidades doc/datos
Microfrontends (shell único, múltiples frameworks en una página)	Un solo dominio/URL raíz	Dos runtimes en el mismo DOM → conflictos, complejidad de integración alta, overhead real
Multi-framework por URL (elegida)	Cada app se carga sola, sin conflictos de runtime; apps independientes (build/deploy)	Dos builds/deploys a mantener

Decisión

Portal multi-framework conviviendo bajo un mismo dominio raíz, separados por subdominio. Ambas apps viven bajo apps/ en el monorepo IngelCoding.

apps/portal-docs/ (Angular 21 + Vis.js + TS 5.9, pnpm) = portal de documentación/wiki — producción en https://ingelcode.cl. Proyecto Pages Cloudflare: ingelcode.
apps/portal-datos/ (Svelte 5 + Vite, npm) = portal de datos de negocio — dashboards/reportes interactivos. Producción en https://reportes.ingelcode.cl. Proyecto Pages Cloudflare: reportes-ingelsur.
Navegación entre apps mediante links HTML normales (sin integración de runtime).
Tokens visuales compartidos: mismo sistema de diseño (colores, tipografía, espaciado) en ambas apps → el usuario percibe un portal único.

portal-finanzas (proyecto personal/experimental de Manuel) queda como banco de patrones de visualización, no como base del portal de negocio, que es proyecto profesional propio.

Fundamento

Era agéntica: el costo histórico del multi-stack era cognitivo y humano. Con agentes ese costo casi desaparece — cada app puede ser asistida independientemente.
Sin problema real de microfrontends: separar por URL evita el problema central de los microfrontends (dos runtimes en la misma página). Cada app vive en su propio contexto.
Svelte es más liviano y ergonómico para dashboards de datos: bundle menor, reactividad nativa sin boilerplate, menos fricción para visualizaciones con Chart.js.
Vista única de datos preservada: ambas apps consumen desde control_gestion como fuente única — no se duplican métricas ni definiciones. Ver Portal-Datos-Contrato.

Roadmap de audiencias (en secuencia)

Interno / operativo: utilidad y densidad de información — primera versión entregable.
Gerencia: vista ejecutiva con KPIs destacados.
Externo / mandantes: acabado visual, acceso controlado (ver Portal-Auth-Cloudflare-Access).

Estructura de monorepo (implementación 2026-06-18)

PR #73 (commit b1bbb60) reestructuró el repo con git mv, preservando historia:

IngelCoding/
  apps/
    portal-docs/          ← Angular 21 + pnpm (antes portal/ / ingel-portal/)
    portal-datos/         ← Svelte 5 + npm (nuevo)
  .env                    ← credenciales Cloudflare compartidas por ambas apps (gitignored)
  .env.example            ← documenta CLOUDFLARE_ACCOUNT_ID y CLOUDFLARE_API_TOKEN

Package managers por app (política de seguridad):

apps/portal-docs/ → pnpm (npm PROHIBIDO)
apps/portal-datos/ → npm

Credenciales Cloudflare consolidadas en .env raíz del monorepo (PR #74):

CLOUDFLARE_ACCOUNT_ID — identificador de cuenta (no secreto)
CLOUDFLARE_API_TOKEN — token con permiso Zone:DNS:Edit sobre ingelcode.cl; se usa para gestionar registros DNS y custom domains de ambas apps

Motivación del usuario: “deben compartir una carpeta raiz e ir ramificado adecuadamente para integrar todo con consistencia” — la era agéntica abarata mantener multi-stack.

Consecuencias

Positivas

Cada app es independiente (build, deploy, evolución de stack).
Coherencia visual sin acoplamiento técnico de runtime.
apps/portal-datos/ puede adoptar librerías de datos (Chart.js, D3, etc.) sin afectar Angular.
Raíz apps/ ofrece un punto único de entrada para scripts de CI/CD o agentes que necesiten operar sobre ambos portales.
Credenciales Cloudflare compartidas desde .env raíz — sin duplicidad ni riesgo de desfase.

Neutras

Dos builds/deploys a gestionar — aceptable con automatización.
Los tokens compartidos requieren sincronización manual o un pipeline de design tokens si divergen.
Dos package managers distintos (pnpm y npm) — política explícita por app, no accidental.

Negativas / riesgos

Si los tokens visuales divergen, la percepción de portal único se rompe — requiere disciplina de diseño.

Estado de implementación

Hito	Estado	Referencia
Decisión multi-framework	✅ Aceptada	ADR original 2026-06-16
Reestructura monorepo a `apps/`	✅ Mergeado	PR #73, commit `b1bbb60`
AGENTS.md actualizado a `apps/`	✅ Mergeado	PR #74, commit `0ffe29a`
Deploy `apps/portal-docs/` → `ingelcode.cl`	✅ Producción	Proyecto Pages `ingelcode`
Deploy `apps/portal-datos/` → `reportes.ingelcode.cl`	✅ Producción (activo 2026-06-18)	Proyecto Pages `reportes-ingelsur`
Cloudflare Access (auth)	⏸ Diferido	Portal de datos público por ahora

Ver también

Portal-Datos-Arquitectura — cómo está construido apps/portal-datos
Portal-Datos-Contrato — especificación del contrato de datos DW ↔ portal
ADR-Arquitectura-Datos-Capas — capas del data warehouse que proveen los datos
Control-Gestion-Valorizaciones — fuente de datos de negocio

Principios Aplicados

Separation-of-Concerns — Angular maneja documentación, Svelte maneja datos de negocio; responsabilidades no mezcladas.
Single-Source-of-Truth — las métricas de negocio viven en control_gestion; ninguna app las define de nuevo.
Criterio Modularizacion - Adapter Port — un datasource (control_gestion.json), múltiples UIs que lo consumen vía port ReporteDataSource.
Criterio Modularizacion - Config vs Logica — cada reporte es config declarativa; la lógica de presentación no está hardcodeada en cada vista.