Module Integrator – Diseño

Este documento deriva de ./requirements.md y describe el "cómo" a nivel de arquitectura y responsabilidades.

Objetivos de diseño

• Cumplir R-001/R-002: Orquestador central con arquitectura de 8 capas y auto-registro mediante decoradores.
• Cumplir R-003/R-011: Activación basada en configuración API con merge inteligente y validación por tenant.
• Cumplir R-004: Gestión de navegación y componentes embebibles inter-módulo con UI integration avanzada.
• Cumplir R-005: Comunicación y coordinación entre módulos (acciones, datos, assets) con providers/consumers.
• Cumplir R-006: Validación de contratos, dependencias y seguridad en runtime con CSP compliance.
• Cumplir R-008: Integración con ecosistema core importando contratos de module-base.
• Cumplir R-009/R-010: Bootstrap sequence optimizada y orchestration con Web Workers.

Referencias: ver requisitos en requirements.md (US-001, US-002, US-003, US-004, US-005, US-006).

Dependencias y límites del módulo

Servicios REUTILIZADOS de libs/core (NO implementar)

• @gograb-space/utilities (BASE OBLIGATORIA sin dependencias):
  • Validadores: validateModuleId(), validateTenantConfig(), validateDependencyGraph()
  • Helpers: formatModuleName(), parseConfiguration(), normalizeRoute()
  • Transformadores: transformToModuleConfig(), mapTenantSettings()
  • Constantes: MODULE_STATES, VALIDATION_RULES, DEFAULT_TIMEOUTS
  • Guards: CanActivateModule, CanDeactivateModule
• @libs-core/shared-models (TIPOS BASE sin dependencias):
  • Tenant: Context, Config, Features, ContextInfo
  • UI: UiConfig, NavigationConfig, BrandingConfig, ThemeConfig, UserPreferences
  • API: ApiResponse<T>, PaginationRequest, PaginationResponse<T>, ErrorResponse
  • Common: BaseEntity, AuditFields, DateRange, KeyValue<T>
  • Auth: UserProfile, AuthState
  • RBAC: Role, Permission
• @libs-core/log-system: LoggerService, formatters, appenders para logging integrado (depende de utilities).
• @libs-core/event-system: EventBusService, SystemEventService, eventos pre-definidos (depende de utilities, log-system).
• @libs-core/security: PermissionService, AuthService, ActionAuthorizerService, security guards (depende de utilities, log-system).
• @libs-core/module-base: ModuleRegistryService, ModuleDiscoveryService, ModuleConfigurationService, BrowserModuleContract, ModuleManifest (depende de todas las core libs).
• @libs-core/action-registry: ActionRegistryService, ActionHandlerService, ActionDiscoveryService, PermissionCheckerService.
• @libs-core/data-access: Repositorios y acceso a APIs.

Servicios NUEVOS específicos del integrator (SÍ implementar)

• Core Layer:
  • IntegratorService (orquestador) - usa validadores de @gograb-space/utilities + Context de @libs-core/shared-models
  • LifecycleManagerService - usa helpers y constantes de @gograb-space/utilities + AuditFields de @libs-core/shared-models
  • DependencySolverService - usa validateDependencyGraph() de @gograb-space/utilities
• Management Layer:
  • ConfigMergerService - usa parseConfiguration() y transformToModuleConfig() de @gograb-space/utilities + Config de @libs-core/shared-models
  • ModuleActivator - usa guards CanActivateModule de @gograb-space/utilities + Context de @libs-core/shared-models
  • SettingsResolver - usa mapTenantSettings() de @gograb-space/utilities + Features de @libs-core/shared-models
• Navigation Layer:
  • NavigationManagerService - usa normalizeRoute() de @gograb-space/utilities + NavigationConfig de @libs-core/shared-models
  • EmbeddableComponentRegistry - usa validadores de @gograb-space/utilities + UiConfig de @libs-core/shared-models
  • ToolbarManagerService - usa validadores de @gograb-space/utilities + BrandingConfig de @libs-core/shared-models
  • BreadcrumbService - usa validadores de @gograb-space/utilities
• Communication Layer:
  • ModuleProviderRegistry, ModuleConsumerResolver - usan validateModuleId() de @gograb-space/utilities + ApiResponse de @libs-core/shared-models
  • CrossModuleActionService - usa transformadores de @gograb-space/utilities + ApiResponse de @libs-core/shared-models
  • AssetSharingService - usa transformadores de @gograb-space/utilities
• Bootstrap Layer: BrowserBootstrapper, StartupSequencer - usan constantes DEFAULT_TIMEOUTS de @gograb-space/utilities
• Orchestration Layer: WorkflowCoordinator, AsyncOperationCoordinator, EventCoordinator, StateCoordinator - usan helpers de @gograb-space/utilities

Dependencias externas

• Angular 20, RxJS 7.8+, signals, standalone components.

Arquitectura y componentes

Arquitectura de 8 capas (contexto) - Integración con servicios existentes

App (Angular 20 + Signals)
├── Core Layer (NUEVOS servicios que coordinan existentes)
│   ├── IntegratorService (orquestador principal) ✨ NUEVO
│   ├── [REUTILIZA] ModuleRegistryService (@libs-core/module-base)
│   ├── DependencySolverService (resolución de dependencias) ✨ NUEVO
│   ├── LifecycleManagerService (gestión de ciclo de vida) ✨ NUEVO
│   └── [REUTILIZA] ModuleDiscoveryService (@libs-core/module-base)
├── Management Layer (NUEVOS servicios + reutilización)
│   ├── ConfigMergerService (usa ModuleConfigurationService existente) ✨ NUEVO
│   ├── ModuleActivator (activación/desactivación) ✨ NUEVO
│   ├── SettingsResolver (configuración por tenant) ✨ NUEVO
│   └── [REUTILIZA] ModuleConfigurationService (@libs-core/module-base)
├── Navigation Layer (NUEVOS servicios específicos UI)
│   ├── NavigationManagerService (navegación inter-módulo) ✨ NUEVO
│   ├── EmbeddableComponentRegistry (componentes embebibles) ✨ NUEVO
│   ├── ToolbarManagerService (toolbar global) ✨ NUEVO
│   └── BreadcrumbService (breadcrumbs dinámicos) ✨ NUEVO
├── Communication Layer (NUEVOS servicios + action-registry)
│   ├── ModuleProviderRegistry (servicios/datos proveedores) ✨ NUEVO
│   ├── ModuleConsumerResolver (resolución dependencias) ✨ NUEVO
│   ├── CrossModuleActionService (usa ActionRegistryService) ✨ NUEVO
│   ├── AssetSharingService (assets compartidos) ✨ NUEVO
│   └── [REUTILIZA] ActionRegistryService (@libs-core/action-registry)
├── Bootstrap Layer (NUEVOS servicios inicialización)
│   ├── BrowserBootstrapper (inicialización navegador) ✨ NUEVO
│   ├── StartupSequencer (secuencia priorizada) ✨ NUEVO
│   └── ModuleActivator (activación runtime) ✨ NUEVO
├── Validation Layer (NUEVOS + security existente)
│   ├── ContractValidator (validación contratos) ✨ NUEVO
│   ├── DependencyValidator (validación dependencias) ✨ NUEVO
│   ├── BrowserCompatibilityChecker (compatibilidad) ✨ NUEVO
│   ├── SecurityValidator (CSP y seguridad) ✨ NUEVO
│   └── [REUTILIZA] PermissionService (@libs-core/security)
├── Orchestration Layer (NUEVOS + event-system)
│   ├── WorkflowCoordinator (coordinación con Workers) ✨ NUEVO
│   ├── AsyncOperationCoordinator (operaciones asíncronas) ✨ NUEVO
│   ├── EventCoordinator (usa EventBusService) ✨ NUEVO
│   ├── StateCoordinator (sincronización BroadcastChannel) ✨ NUEVO
│   └── [REUTILIZA] EventBusService (@libs-core/event-system)

Versión futura (v2.0) - Web Workers

Web Workers (threads específicos del integrator - FUTURA IMPLEMENTACIÓN)
├── ModuleLoaderWorker (carga módulos pesados) 🔮 FUTURO v2.0
├── DependencyResolverWorker (dependencias complejas) 🔮 FUTURO v2.0
└── PerformanceAnalyzerWorker (análisis performance) 🔮 FUTURO v2.0

División de responsabilidades por capa

• Core: IntegratorService orquesta servicios existentes (ModuleRegistryService, ModuleDiscoveryService) usando validadores de @gograb-space/utilities. LifecycleManagerService gestiona transiciones usando eventos del EventBusService + helpers de @gograb-space/utilities.
• Management: ConfigMergerService extiende ModuleConfigurationService existente usando transformadores de @gograb-space/utilities. ModuleActivator usa PermissionService + guards de @gograb-space/utilities para validación.
• Navigation: NavigationManagerService usa normalizeRoute() de @gograb-space/utilities. EmbeddableComponentRegistry y ToolbarManagerService usan validadores de @gograb-space/utilities para UI específica del integrador.
• Communication: CrossModuleActionService delega en ActionRegistryService existente + transformadores de @gograb-space/utilities. ModuleProviderRegistry usa validateModuleId() de @gograb-space/utilities para coordinar servicios entre módulos.
• Bootstrap: BrowserBootstrapper y StartupSequencer usan constantes DEFAULT_TIMEOUTS y helpers de @gograb-space/utilities para secuencia de inicialización optimizada.
• Validation: Validadores NUEVOS que complementan (no reemplazan) servicios de security existentes PERO REUTILIZAN validadores base de @gograb-space/utilities.
• Orchestration: EventCoordinator usa EventBusService existente + helpers de @gograb-space/utilities. WorkflowCoordinator y StateCoordinator usan constantes y transformadores de @gograb-space/utilities para coordinación asíncrona.

Contratos y modelos (ligeros)

Entidades clave (importadas de module-base y shared-models)

• ModuleManifest: { id: string; version: string; displayName?; permissions?; tenantConfig? } (de @libs-core/module-base)
• BrowserModuleContract: { manifest; configure(config: T); initialize(); start(); stop(); destroy() } (de @libs-core/module-base)
• ModuleConfig: { enabled: boolean; requiredDependencies?; [key: string]: any } (de @libs-core/module-base)
• Context: { tenantId, tenantName, apiBaseUrl, locale, timezone, permissions, configuration, features } (de @libs-core/shared-models)
• UiConfig: { branding, theme, navigation, userPreferences } (de @libs-core/shared-models)
• ApiResponse: { data: T; statusCode: number; success: boolean; message?: string } (de @libs-core/shared-models)

Modelos específicos del integrator (extienden shared-models)

• DependencyGraph: Grafo de dependencias entre módulos con resolución en tiempo real (extiende BaseEntity de shared-models)
• BrowserLifecycleState: Estados optimizados para navegador (discovering, validating, loading, initializing, configuring, starting, running, stopping, unloading, error, disabled) + AuditFields de shared-models
• LocalModuleConfig: Configuración específica de módulos locales con lazy routes (extiende Config de shared-models)
• EmbeddableComponent: { id, moduleId, componentType, category, permissions } (usa UiConfig de shared-models)
• WorkerMessage: { type, payload, moduleId?, correlationId? } (usa ApiResponse pattern de shared-models)

APIs principales (nombres y E/S)

• IntegratorService
  • initializeApplication(): Promise
  • manageModuleLifecycle(module, config): Promise
  • applicationStatus: Signal<'initializing' | 'ready' | 'error'>
• ConfigMergerService
  • loadAndMergeConfigs(moduleIds): Promise
  • validateModuleConfig(moduleId, config): ValidationResult
• CrossModuleActionService
  • executeCrossModuleAction(fromModuleId, targetModuleId, actionId, parameters): Promise
  • getDataFromModule(moduleId, providerId, parameters?): Promise

Eventos del ciclo de vida (EventBus)

• ApplicationInitializing/Initialized
• ModuleRegistered/Activated/Failed/ConfigurationUpdated
• WorkerTaskStarted/Completed/Failed

Decisiones de diseño (ADR)

• DEC-001: Arquitectura de 8 capas especializada; alternativa estructura plana. Justificación: separación clara de responsabilidades y mantenibilidad. Impacto: código más organizado pero mayor complejidad inicial.
• DEC-002: Usar integración nativa de Angular para lazy loading; alternativa Module Federation. Justificación: simplicidad y mejor compatibilidad con Angular 20. Impacto: carga de módulos más eficiente y mantenible.
• DEC-003: Centralizar orquestación en IntegratorService; alternativa servicios distribuidos. Justificación: control unificado del ciclo de vida y mejor trazabilidad. Impacto: arquitectura más clara y mantenible.
• DEC-004: Importar contratos de module-base; alternativa reimplementar. Justificación: consistencia y reducción de duplicación. Impacto: menor mantenimiento y mayor coherencia.
• DEC-005: Web Workers para operaciones pesadas; alternativa Main Thread. Justificación: evitar bloqueos de UI y mejor performance. Impacto: mayor complejidad pero mejor UX.
• DEC-006: Signals over Observables donde sea posible; alternativa RxJS puro. Justificación: mejor performance y sintaxis más simple en Angular 20. Impacto: código más eficiente pero curva de aprendizaje.
• DEC-007: Configuración por tenant desde API; alternativa configuración estática. Justificación: flexibilidad multi-tenant y activación dinámica. Impacto: mayor adaptabilidad pero dependencia de red.
• DEC-008: Circuit Breaker pattern para módulos; alternativa sin protección. Justificación: prevención de fallos en cascada. Impacto: mayor robustez pero overhead de monitoreo.

Riesgos y mitigaciones

• Riesgo: Sobrecarga de memoria con muchos módulos cargados. Mitigación: gestión eficiente de memoria con signals y descarga automática.
• Riesgo: Errores en cascada entre módulos dependientes. Mitigación: circuit breaker pattern y validación de dependencias.
• Riesgo: Problemas de seguridad con comunicación cross-module. Mitigación: validación estricta de permisos y sanitización de datos.
• Riesgo: Dependencia fuerte de module-base. Mitigación: uso de interfaces y contratos bien definidos para facilitar evolución.

Estrategia de pruebas y observabilidad

• Unit: servicios core, validadores, monitores de performance.
• Integración: ciclo de vida completo con módulos reales, comunicación cross-module.
• E2E: flujos de activación/desactivación, navegación inter-módulo.
• Observabilidad: eventos de ciclo de vida, métricas de performance, logs detallados.

Mapeo de cobertura (servicios nuevos vs. reutilizados)

• R-001/US-001 -> NUEVOS: IntegratorService, LifecycleManagerService, DependencySolverService | REUTILIZA: ModuleRegistryService (@libs-core/module-base) + validadores base (@gograb-space/utilities) + Context (@libs-core/shared-models)
• R-002/US-001 -> REUTILIZA: ModuleDiscoveryService con decoradores auto-registro (@libs-core/module-base) + helpers (@gograb-space/utilities)
• R-003/US-002 -> NUEVOS: ConfigMergerService, ModuleActivator, SettingsResolver | REUTILIZA: ModuleConfigurationService (@libs-core/module-base) + transformadores (@gograb-space/utilities) + Config, Features (@libs-core/shared-models)
• R-004/US-003 -> NUEVOS: NavigationManagerService, EmbeddableComponentRegistry, ToolbarManagerService, BreadcrumbService | REUTILIZA: validadores y helpers (@gograb-space/utilities) + NavigationConfig, UiConfig, BrandingConfig (@libs-core/shared-models)
• R-005/US-004 -> NUEVOS: ModuleProviderRegistry, ModuleConsumerResolver, CrossModuleActionService, AssetSharingService | REUTILIZA: ActionRegistryService (@libs-core/action-registry) + transformadores (@gograb-space/utilities) + ApiResponse (@libs-core/shared-models)
• R-006/US-002,US-005 -> NUEVOS: ContractValidator, SecurityValidator, DependencyValidator, BrowserCompatibilityChecker | REUTILIZA: PermissionService (@libs-core/security) + validadores base (@gograb-space/utilities)
• R-008 -> ESTRATEGIA: Integración profunda con ecosystem existente, no reimplementación + BASE OBLIGATORIA: @gograb-space/utilities + TIPOS BASE: @libs-core/shared-models
• R-009/US-005 -> NUEVOS: BrowserBootstrapper, StartupSequencer, ModuleActivator | REUTILIZA: constantes DEFAULT_TIMEOUTS (@gograb-space/utilities)
• R-010/US-005 -> NUEVOS: WorkflowCoordinator, AsyncOperationCoordinator, StateCoordinator | REUTILIZA: EventBusService (@libs-core/event-system) + helpers (@gograb-space/utilities)
• R-011/US-002 -> NUEVO: ConfigMergerService con merge inteligente por tenant | REUTILIZA: parseConfiguration, mapTenantSettings (@gograb-space/utilities) + Context, Config (@libs-core/shared-models)

Versión futura (v2.0)

• Web Workers: ModuleLoaderWorker, DependencyResolverWorker, PerformanceAnalyzerWorker (implementación futura)

Enlaces: requirements.md · tasks.md