Module Base – 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/R-003: contratos claros + @ModuleDecorator + configuración directa.
• Cumplir R-004/R-005: servicios de registro/descubrimiento/configuración con multitenancy desde security.
• Cumplir R-006/R-007: estado/acciones y componentes base standalone.
• Cumplir R-008 y NFR: eventos observables y logging, rendimiento y compatibilidad.

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

Dependencias y límites

Internas

• Contratos (module, manifest, acciones, estado, componentes, servicios).
• Servicios base: Registry, Discovery, Configuration/Config, Communication.
• Componentes base: BaseModuleComponent, ModuleLayout, ModuleRouterOutlet, ComponentBase.

Externas

• @libs-core/security: AuthService, PermissionService, tenant context.
• @libs-core/event-system: EventBusService, eventos de ciclo de vida.
• @libs-core/log-system: LoggerService y decoradores.
• @libs-core/action-registry: registro y descubrimiento de acciones.
• @gograb-space/utilities, @libs-core/data-access; Angular 20, RxJS.

Arquitectura y componentes

Contexto (texto)

• App
  • ModuleIntegrator (externo, orquesta)
    • ModuleRegistryService (R-004)
    • ModuleDiscoveryService (R-004)
    • ModuleConfigurationService/ModuleConfigService (R-004, R-005)
  • Módulos implementan BrowserModuleContract (R-001) y se marcan con @ModuleDecorator (R-002)
  • EventBus + Logger para ciclo de vida y observabilidad (R-008)

Responsabilidades

• BrowserModuleContract: ciclo de vida (configure, initialize, start, stop, destroy) + manifest.
• ModuleRegistryService: alta/baja/consulta de módulos registrados.
• ModuleDiscoveryService: auto‑registro al cargar (escaneo/instanciación bajo decorador).
• ModuleConfigurationService: resolver configuración por moduleId y tenant actual.
• ModuleCommunicationService: canal básico de comunicación inter‑módulo.
• BaseModuleState/ModuleStateService/Selectors: estado base con signals; NGXS opcional.
• ActionRegistry/ModuleActions: descubrir/registrar/ejecutar acciones públicas.
• Componentes base: layout estándar y outlet de rutas propio.

Contratos y modelos (ligeros)

Entidades clave

• ModuleManifest: { id: string; version: string; displayName?; permissions? }
• BrowserModuleContract: { manifest; configure(config: T); initialize(); start(); stop(); destroy() }
• ModuleConfig: Record<string, unknown> por módulo; enabled opcional.
• ActionContract/Metadata: id, permisos requeridos, validadores.
• LifecycleStates/ModuleEvents: eventos y estados estándar.

APIs/eventos (nombres y E/S)

• ModuleRegistryService
  • register(module: BrowserModuleContract): void | Error relevantes: id duplicado
  • getModules(): BrowserModuleContract[]; get(moduleId): BrowserModuleContract | undefined
• ModuleConfigurationService
  • getModuleConfiguration(): Promise<Record<string, ModuleConfig>>
  • getModuleConfig(moduleId: string): Promise<T | undefined>
• Eventos (EventBus)
  • ApplicationInitializing/Initialized
  • ModuleRegistered/Activated/Failed

Decisiones de diseño (ADR)

• DEC-001: Configuración directa por método configure; alternativa (tokens DI). Justificación: simplicidad/KISS y multitenancy flexible. Impacto: menos acoplamiento a DI.
• DEC-002: Carga nativa de Angular (sin Module Federation); alternativa MF. Justificación: complejidad y tamaño. Impacto: build y runtime más simples.
• DEC-003: Usar security para tenant y permisos; alternativa: tokens locales. Impacto: unificación de contexto y menor duplicación.

Riesgos y mitigaciones

• Riesgo: fuga de responsabilidades en Discovery. Mitigación: límites claros y tests de integración.
• Riesgo: configuraciones inconsistentes por tenant. Mitigación: validación y logs; contratos estrictos.
• Riesgo: sobrecarga de eventos/logs. Mitigación: niveles de logging y sampling.

Estrategia de pruebas y observabilidad

• Unit: contratos, servicios base, decoradores, utilidades.
• Integración: Registry+Discovery+Configuration con security/event/log.
• E2E mínimo: flujo de activación con config enabled y permisos.
• Observabilidad: emisión de eventos por cada transición; métricas de Performance API opcionales.

Mapeo de cobertura

• R-001/US-001 -> BrowserModuleContract, ModuleManifest, @ModuleDecorator
• R-002/US-001 -> ModuleDiscoveryService, ModuleRegistryService
• R-003/US-001 -> método configure(config)
• R-004/US-002 -> ModuleConfigurationService/ModuleConfigService
• R-005/US-002 -> Integración con security (Auth/Permissions)
• R-006/US-003 -> ModuleStateService, ActionRegistry/ModuleActions
• R-007 -> Componentes base standalone
• R-008 -> EventBus + Logger (eventos de ciclo de vida)

Enlaces: requirements.md · tasks.md