ENES

Introducción a la arquitectura

Plataforma Micro Frontends -- React + TypeScript, Module Federation v2, Cloudflare Workers Plataforma Micro Frontends React + TypeScript Module Federation v2 Cloudflare Workers Edge-first

Diagrama de arquitectura del sistema

Diagrama de arquitectura del sistema -- Navegador, Shell App, MFEs, Cloudflare Edge NAVEGADOR Shell App (Host) MFE A MFE B MFE C MFE D MFE E Design System Remote (componentes UI compartidos) ◄ Bus CustomEvents (comunicación inter-MFE) ► HTTP / WebSocket Module Federation Runtime (CDN) CLOUDFLARE EDGE API Gateway Worker • CORS • Rate limiting • JWT verification • Request routing BFF Workers BFF A BFF B BFF C BFF D CDN / R2 Bundles MFE Version Config KV + D1 Durable Objects Sesiones en tiempo real AI Agents Agents SDK (EU) service bindings WebSocket WebSocket (AI)

Stack tecnologico

CapaTecnologiaVersionProposito
Frontend FrameworkReact + TypeScript^19.2.4 / ^5.9.3Renderizado de UI, solo CSR
Composición MFEModule Federation v2 (@module-federation/enhanced)^2.0.1Carga de remotes en runtime
BundlerRsbuild (@rsbuild/core) / Rspack^1.7.3Builds rapidos con soporte nativo de MF v2
Design Systemshadcn/ui + Base UI (npm + MF remoto) + Storybook^10.2.14 (Storybook)Biblioteca de componentes UI compartidos
EstilosTailwind CSS / CSS Modules--Utility-first (componentes) + aislados (MFEs)
Routingreact-router (consolidado desde react-router-dom)^7.13.1Routing del lado del cliente
Gestión de estadozustand^5.0.11Stores ligeros por MFE
Validaciónzod^4.3.6Validación de schemas en runtime
Manejo de JWTjose^6.1.3Firma/verificación de tokens en Workers
Package Managerpnpm10.30.3Content-addressable store, dependencias estrictas
Herramienta de monorepoTurborepo (turbo)^2.8.12Orquestación de tareas, remote caching
LintingESLint (solo flat config)^10.0.2Analisis estatico
TestingVitest^4.0.18Tests unitarios / de integracion
RuntimeNode.js22 (Maintenance LTS), 24 (Active LTS) -- Node 20 EOL abril 2026Runtime para build y CI
Edge RuntimeCloudflare Workers (Wrangler v4)--API gateway, BFFs, Workers Static Assets (Pages deprecado abr 2025)
Object StorageCloudflare R2--Almacenamiento versionado de bundles MFE
KV StoreCloudflare KV--Configuración de versiones (lecturas rapidas en el edge)
Base de datos SQLCloudflare D1 (GA desde abril 2024)--Audit trail, historial de versiones
ORMDrizzle ORM (drizzle-orm)^0.45.1Acceso type-safe a la base de datos D1
DB Toolingdrizzle-kit^0.31.9Migraciones y generación de esquema D1
Tiempo realDurable Objects (Hibernatable WebSockets)--Coordinación WebSocket; tiempo de CPU de Workers configurable hasta 5 min
Agentes IACloudflare Agents SDK (agents)--Servicios educativos con IA (jurisdicción UE)
Compatibility DateCloudflare Workers2026-02-25Fecha de compatibilidad base para todos los Workers
AutenticaciónWorkOS AuthKit--OAuth, SSO empresarial, RBAC
CI/CDGitHub Actions--Pipelines de build, test y deploy
VersionadoChangesets--Versionado semantico independiente
Actualizaciones cross-repoRenovate--Actualizaciones automaticas de dependencias
Desarrollo local (cross-repo)yalc + Verdaccio--Enlace local de paquetes y registro

Flujo de datos

Secuencia de carga de pagina

Secuencia de carga de pagina -- Pasos 1 a 7 1El usuario navega a app.example.com 2Cloudflare CDN sirve la Shell App (index.html + bundle del shell) 3Bootstrap de la Shell App 3a. Obtiene version config de KV → { "mfe-a": "…/mf-manifest.json" } 3b. Inicializa el runtime de Module Federation → registerRemotes([…]) 3c. WorkOS AuthKit comprueba la sesion / redirige al login 4El usuario navega a una ruta del MFE A 5La Shell App ejecuta loadRemote("mfe_a/App") 5a. El runtime de MF obtiene mf-manifest.json desde CDN/R2 5b. Descarga los chunks del MFE A (deps compartidas ya cargadas → se omiten) 5c. El componente del MFE A se monta en el boundary <React.Suspense> del Shell 6El MFE A llama a su BFF Worker a traves del API Gateway 6a. El API Gateway valida el JWT (desde HttpOnly cookie) 6b. Enruta la peticion al BFF-A Worker (service binding) 6c. BFF-A procesa la peticion y devuelve los datos 7El MFE A renderiza con datos ✓

Flujo de peticiones API

Flujo de peticiones API -- Del navegador a traves del API Gateway y BFF Worker hasta los servicios backend Navegador API Gateway Worker JWT · CORS · Rate limit · Routing BFF Worker Logica de dominio · Transformacion · Cache External / D1 KV / R2 Service Bindings (RPC)

Flujo en tiempo real

Flujo en tiempo real -- Del navegador a traves de Durable Object hasta Hibernatable WebSocket Navegador Durable Object (via Worker) Coordinación de estado · Broadcast · Limpieza con Alarm Hibernatable WebSocket El WS permanece abierto durante hibernacion ($0)

Flujo de agentes

Flujo de agentes -- Del navegador a traves del Agent Service Worker al Agent DO y al proveedor de modelo IA Navegador Agent Service Worker Route · WebSocket upgrade · DO stub Agent DO AIChatAgent · SQLite · jurisdiction("eu") AI Model Provider EU JURISDICTION

Mapa de repositorios

Mapa de repositorios -- Monorepo central con polyrepos e infraestructura como radios MONOREPO — platform-core 📦 design-system 📦 shared-types 📦 shared-utils 📦 eslint-config 📦 tsconfig 📦 prettier-config 📦 event-contracts turbo.json pnpm-workspace.yaml .changeset/ Changesets → npm publish → Renovate updates POLYREPOS shell-app (Host) mfe-dashboard (Alpha) mfe-settings (Beta) mfe-analytics (Gamma) mfe-messaging (Delta) mfe-admin (Platform) mfe-agents (Platform) INFRAESTRUCTURA api-gateway bff-workers version-service realtime-service agent-service Cloudflare Workers

Modelo de propiedad por equipos

EquipoResponsable deReposResponsabilidades
PlatformShell App, API Gateway, Version Service, Agent Service, CI/CD, Design Systemshell-app, api-gateway, version-service, agent-service, mfe-agents, platform-coreInfraestructura, tooling compartido, agentes IA, onboarding de MFEs, coordinación de releases
Team AlphaDashboard MFE, Dashboard BFFmfe-dashboard, BFF en bff-workersFuncionalidades del dashboard, visualizacion de datos
Team BetaSettings MFE, Settings BFFmfe-settings, BFF en bff-workersConfiguración de usuario/organizacion, preferencias
Team GammaAnalytics MFE, Analytics BFFmfe-analytics, BFF en bff-workersReporting, graficos, exportacion de datos
Team DeltaMessaging MFE, Real-time Servicemfe-messaging, realtime-serviceChat, notificaciones, funcionalidades WebSocket

Principios de propiedad

  1. Propiedad vertical: Cada equipo es dueno de su MFE de extremo a extremo (UI → BFF → datos).
  2. Las libs compartidas pertenecen al equipo Platform: El monorepo lo mantiene el equipo Platform, con contribuciones de todos los equipos via PRs.
  3. Despliegues autonomos: Cada MFE puede desplegarse de forma independiente sin coordinar con otros equipos.
  4. Integracion basada en contratos: Los equipos acuerdan contratos de eventos (CustomEvents) y schemas de API, no detalles de implementacion.
  5. Gobernanza del design system: El equipo Platform revisa y fusiona los cambios del design system; los equipos de funcionalidad proponen via PR.

Decisiónes arquitectonicas clave

DecisiónEleccionADR
Composición MFEModule Federation v2ADR-001
Plataforma edgeCloudflare WorkersADR-002
Estrategia de repositoriosHíbrida mono + polyADR-003
Package managerpnpmADR-004
AutenticaciónWorkOS AuthKitADR-005
Orquestación de monorepoTurborepoADR-006
Comunicación inter-MFEBrowser CustomEventsADR-007
BundlerRsbuild / RspackADR-008
Ecosistema TanStackEvaluar (Start rechazado)ADR-009
ORM de base de datosDrizzle ORMADR-010
Biblioteca de componentesshadcn/ui + Base UIADR-011
Agentes IACloudflare Agents SDKADR-012

Documentos relacionados

DocumentoDescripción
Module FederationConfiguración de MF v2, deps compartidas, remotes dinamicos
Infraestructura CloudflareWorkers, R2, KV, D1, service bindings
Design SystemDistribucion dual, theming, Storybook
Desarrollo localFlujo de trabajo de desarrollo, yalc, Verdaccio, Miniflare
Estrategia de repositoriosEstructura monorepo/polyrepo, Turborepo, pnpm
Comunicación en tiempo realDurable Objects, WebSockets, hibernacion
Gestión de versionesUI de admin, pinning de versiones, rollback
AutenticaciónWorkOS, validación JWT, gestión de sesiones
CI/CD y despliegueGitHub Actions, Changesets, entornos de preview
Comunicación inter-MFECustomEvents, payloads tipados, patrones
Agentes IASDK de agentes, servicios educativos con IA, cumplimiento GDPR
AnteriorADR 012: Cloudflare Agents SDK para servicios educativos impulsados por IASiguienteModule Federation v2