Module Integrator – Requerimientos

Resumen: orquestador central responsable del ciclo de vida completo de módulos, gestionando auto-registro, activación basada en configuración API, y coordinación de la integración entre módulos en aplicaciones web Angular.

Alcance e ítems fuera de alcance

En alcance

• R-001: Orquestador central del ciclo de vida completo de módulos con 8 capas arquitectónicas.
• R-002: Auto-registro de módulos mediante decoradores al iniciar la aplicación.
• R-003: Activación basada en configuración obtenida del API backend por tenant.
• R-004: Gestión de navegación inter-módulo y componentes embebibles.
• R-005: Comunicación y coordinación entre módulos (acciones, datos, assets).
• R-006: Validación de contratos, dependencias y seguridad en runtime.
• R-008: Integración con ecosistema core (@libs-core/module-base, action-registry, etc.).
• R-009: Bootstrap sequence optimizada para navegador con prioridades de carga.
• R-010: Orchestration avanzada con coordinación de eventos y operaciones asíncronas.
• R-011: Management de configuración con merge inteligente y validación por tenant.

Fuera de alcance (versión inicial)

• Implementación de módulos de negocio finales.
• Server-side rendering o Module Federation.
• Gestión de bundles remotos o carga desde CDN.
• Compatibilidad con Internet Explorer o navegadores legacy.
• Web Workers para operaciones pesadas (versión futura v2.0).
• Workers para resolución de dependencias complejas (versión futura v2.0).
• Análisis de performance en background workers (versión futura v2.0).

Suposiciones y restricciones

• Angular 20+, standalone components, signals; sin Module Federation.
• Todo el sistema usa el sistema nativo de lazy loading de Angular.
• Integración exclusiva con librerías core de @gograb-space.
• KISS y tree‑shaking: API mínima, sin configuraciones complejas.
• Compatibilidad: navegadores modernos; RxJS 7.8+; NGXS opcional.

Stakeholders/roles

• Arquitectura FE, Desarrolladores de módulos, QA, DevOps/Platform.

Historias de usuario (US)

US-001 – Core Services y Estructura Base (Fase 1)

• Como desarrollador quiero servicios core del orquestador para gestionar el ciclo de vida completo de módulos.
• Criterios (AC-001):
  • IntegratorService orquesta el ciclo de vida usando servicios existentes de @libs-core/module-base.
  • REUTILIZA ModuleRegistryService de @libs-core/module-base para registro central.
  • DependencySolverService resuelve dependencias usando validadores de @gograb-space/utilities.
  • LifecycleManagerService gestiona transiciones usando helpers de @gograb-space/utilities.
  • REUTILIZA ModuleDiscoveryService de @libs-core/module-base para auto-registro.
  • OBLIGATORIO: Todos los validadores, helpers y constantes DEBEN provenir de @gograb-space/utilities.
  • OBLIGATORIO: Todos los modelos base DEBEN usar tipos de @libs-core/shared-models (Context, UserProfile, ApiResponse, etc.).
• Reqs: R-001, R-002, R-008.
• Nota: Integración con servicios existentes y utilities como base, no reimplementación.

US-002 – Configuración API y Gestión de Módulos (Fase 2)

• Como integrador quiero gestión de configuración desde API para activar módulos por tenant.
• Criterios (AC-002):
  • ConfigMergerService unifica configuraciones usando EXISTENTE @libs-core/module-base ModuleConfigurationService.
  • ModuleActivator activa/desactiva módulos usando validadores de @gograb-space/utilities.
  • SettingsResolver resuelve configuraciones usando transformadores de @gograb-space/utilities.
  • ConfigurationValidator usa validadores core de @gograb-space/utilities (NO reimplementar).
  • REUTILIZA PermissionService de @libs-core/security para validación de permisos.
  • OBLIGATORIO: Toda validación de configuración DEBE usar @gograb-space/utilities.
  • OBLIGATORIO: Toda configuración de tenant y UI DEBE usar modelos de @libs-core/shared-models (Context, Config, UiConfig, etc.).
• Reqs: R-003, R-006, R-011.
• Nota: Integración con servicios existentes @libs-core/data-access, security y utilities como base.

US-003 – Navegación y UI Integration (Fase 3)

• Como desarrollador quiero navegación inter-módulo y componentes embebibles para integración UI.
• Criterios (AC-003):
  • NavigationManagerService gestiona menús y navegación con signals usando NavigationConfig de @libs-core/shared-models.
  • EmbeddableComponentRegistry registra componentes embebibles entre módulos usando UiConfig de @libs-core/shared-models.
  • ToolbarManagerService gestiona toolbar y acciones globales usando BrandingConfig de @libs-core/shared-models.
  • BreadcrumbService gestiona breadcrumbs dinámicos.
  • ThemeCoordinator coordina temas entre módulos usando ThemeConfig de @libs-core/shared-models.
  • OBLIGATORIO: Toda configuración UI DEBE usar modelos de @libs-core/shared-models.
• Reqs: R-004.
• Nota: Integración con Angular Router y sistema de permisos + modelos UI de shared-models.

US-004 – Comunicación Cross-Module (Fase 3)

• Como desarrollador quiero comunicación avanzada entre módulos para compartir recursos.
• Criterios (AC-004):
  • ModuleProviderRegistry registra servicios/datos que proporcionan módulos.
  • ModuleConsumerResolver resuelve dependencias entre módulos.
  • CrossModuleActionService ejecuta acciones usando EXISTENTE @libs-core/action-registry ActionRegistryService.
  • AssetSharingService comparte assets entre módulos.
  • ComponentEmbedder facilita embedding de componentes.
• Reqs: R-005.
• Nota: REUTILIZA ActionRegistryService y ActionDiscoveryService existentes.

US-005 – Browser Orchestration (Fase 4)

• Como arquitecto quiero orchestration optimizada para coordinación de módulos sin bloquear UI.
• Criterios (AC-005):
  • BrowserBootstrapper inicializa optimizada para navegador.
  • StartupSequencer secuencia basada en prioridades de carga.
  • AsyncOperationCoordinator gestiona operaciones asíncronas en Main Thread.
  • EventCoordinator usa EXISTENTE @libs-core/event-system EventBusService para eventos cross-module.
  • StateCoordinator sincroniza estados usando BroadcastChannel.
• Reqs: R-009, R-010.
• Nota: REUTILIZA EventBusService y SystemEventService existentes. Web Workers quedan para v2.0.

Requerimientos no funcionales (NFR)

• NFR-01 Performance: Tiempo de inicialización < 200ms overhead; bundle size < 100KB gzipped; gestión eficiente de memoria con descarga automática.
• NFR-02 Seguridad: Validación estricta de CSP; control de acceso granular; sanitización de datos cross-module; validación de origen de módulos.
• NFR-03 Observabilidad: Logging completo de eventos; health checks por módulo; análisis de bundles.
• NFR-04 Compatibilidad: Navegadores modernos (Chrome 90+, Firefox 88+, Safari 15+); soporte para Web Workers y BroadcastChannel.
• NFR-05 Calidad: ≥ 90% coverage unit tests; ≥ 85% integration tests; E2E tests para ciclo de vida completo; 0 linting errors.
• NFR-06 Escalabilidad: Soporte para múltiples módulos concurrentes; carga progresiva basada en prioridad; Circuit Breaker pattern.
• NFR-07 Mantenibilidad: Arquitectura de 8 capas bien definidas; contratos claros entre servicios; documentación completa de APIs.

Glosario

Contratos reutilizados de libs/core

• Utilities Core (BASE OBLIGATORIA): Validadores, helpers, transformadores, constantes de @gograb-space/utilities.
• Shared Models (TIPOS BASE): Context, Config, UiConfig, NavigationConfig, BrandingConfig, ThemeConfig, ApiResponse, AuditFields, BaseEntity de @libs-core/shared-models.
• ModuleManifest: Contrato existente en @libs-core/module-base que define metadata de un módulo.
• BrowserModuleContract: Contrato existente en @libs-core/module-base para ciclo de vida de módulos.
• ActionRegistryService: Servicio existente en @libs-core/action-registry para registro y ejecución de acciones.
• EventBusService: Servicio existente en @libs-core/event-system para comunicación por eventos.
• PermissionService: Servicio existente en @libs-core/security para gestión de permisos.
• LoggerService: Servicio existente en @libs-core/log-system para logging integrado.

Servicios nuevos específicos del integrator

• IntegratorService: Orquestador principal que coordina servicios existentes del ecosystem (usa utilities para validación + Context de shared-models).
• LifecycleManagerService: Gestión de transiciones de estado usando helpers de @gograb-space/utilities + AuditFields de shared-models.
• NavigationManagerService: Gestión de navegación inter-módulo usando validadores de @gograb-space/utilities + NavigationConfig de shared-models.
• CrossModuleActionService: Comunicación entre módulos usando ActionRegistryService + transformadores de @gograb-space/utilities + ApiResponse de shared-models.

Conceptos técnicos

• Dynamic Import: Mecanismo nativo de ES2020 para carga lazy de módulos locales.
• BroadcastChannel: API nativa para comunicación entre pestañas del mismo origen.
• Circuit Breaker: Patrón de protección contra fallos en cascada entre módulos.

Versión futura (v2.0)

• Web Worker: Threads separados para operaciones pesadas (implementación futura).
• Background Analysis: Análisis de performance en workers (implementación futura).