Librería Event System (Core)

Prioridad: Muy Alta

Propósito: Sistema de eventos que permite el desacoplamiento de módulos mediante un bus de eventos, facilitando la comunicación asíncrona y la orquestación de operaciones complejas en toda la plataforma GoGrab.

Especificación funcional

Esta librería debe proporcionar:

Modelos e interfaces:

• DomainEvent - Clase abstracta base para eventos de dominio
• SystemEvent - Clase abstracta para eventos del sistema
• EventMetadata - Información de contexto y trazabilidad
• EventHandler - Interface para manejadores de eventos
• EventSubscription - Interface para suscripciones

Servicios core:

• EventBusService - Bus principal de eventos
• SystemEventService - Servicio específico para eventos del sistema
• EventBusNgxsService - Integración opcional con NgXS

Utilidades:

• Event serialization/deserialization
• Event filtering y routing
• Error handling para eventos fallidos
• Logging integration para auditoría
• Performance monitoring de eventos

Características avanzadas:

• Event replay para debugging
• Event sourcing básico
• Transactional events
• Event scheduling/delayed dispatch
• Multi-tenant event isolation

Estado actual

• Tipo: librería Nx de Angular.
• Ruta de importación: @libs-core/event-system (configurada en tsconfig.base.json).
• API pública actual: solo barrel src/index.ts.

API pública actual

• Re-export desde: libs/core/event-system/src/index.ts.
• No hay componentes principales ni servicios publicados aún.

Estructura del paquete

• src/lib/event-system/event-system.ts: componente placeholder interno (no parte de una API estable).
• src/index.ts: barrel para futuros exports públicos.

Comandos de mantenimiento

• Ejecutar pruebas: nx test event-system
• Linting: nx lint event-system

Importancia en el ecosistema GoGrab

Esta librería es fundamental para la arquitectura de desacoplamiento de la plataforma:

• Desacoplamiento: Permite que módulos se comuniquen sin dependencias directas
• Escalabilidad: Facilita agregar nuevos módulos sin modificar existentes
• Auditabilidad: Trazabilidad completa de eventos para debugging y compliance
• Flexibilidad: Permite cambios en la lógica de negocio sin afectar otros módulos
• Integración: Base para workflows complejos y orquestación de procesos

Sin este sistema, los módulos estarían fuertemente acoplados, limitando la mantenibilidad y escalabilidad.

Dependencias identificadas

Dependencias propias:

• LogSystem (@libs-core/log-system) - Para logging de eventos y auditoría
• Utilities (@gograb-space/utilities) - Para validaciones y transformaciones

Esta librería será requerida por:

• Autenticación y autorización - Para eventos de sesión y seguridad
• DataAccess - Para eventos de sincronización y cache invalidation
• Action Registry - Para comunicación entre acciones
• Module Integrator - Para orquestación de módulos
• Media Asset Management - Para eventos de upload/processing
• Core App - Para eventos de navegación y UI
• I18n - Para eventos de cambio de idioma/locale

Nota de implementación: Debe implementarse en paralelo con LogSystem para evitar dependencias circulares.

Modelo de dominio (tipos clave)

• EventType: 'domain' | 'system' | 'integration' | 'notification'
• EventPriority: 'low' | 'normal' | 'high' | 'critical'
• EventStatus: 'pending' | 'processing' | 'completed' | 'failed' | 'retrying'
• EventMetadata: { eventId: string; timestamp: Date; tenantId?: string; correlationId?: string; causationId?: string; version: number; }
• BaseEvent: { type: EventType; priority: EventPriority; metadata: EventMetadata; payload: unknown; }
• DomainEvent<T>: extends BaseEvent con payload tipado para eventos de dominio
• SystemEvent<T>: extends BaseEvent con payload tipado para eventos del sistema
• EventHandler<T>: { handle(event: T): Promise<void> | void; canHandle(event: BaseEvent): boolean; }
• EventSubscription: { eventType: string; handler: EventHandler<any>; options?: SubscriptionOptions; }

API pública prevista

Servicios principales:

• EventBusService - Bus central de eventos con publish/subscribe
• SystemEventService - Manejo específico de eventos del sistema
• EventStoreService - Persistencia opcional de eventos para replay/audit

Utilidades:

• EventValidationService - Validación de estructura y contenido de eventos
• EventSerializationService - Serialización para persistencia/transmisión
• EventFilterService - Filtrado avanzado de eventos

Decoradores:

• @EventHandler(eventType) - Decorador para auto-registro de handlers
• @EventSource() - Decorador para clases que publican eventos

Roadmap de implementación

Fase 1 - MVP Crítico (Prioridad: Muy Alta)

Objetivo: Funcionalidad básica para desacoplamiento de módulos

• ✅ Modelos base (DomainEvent, SystemEvent, EventMetadata)
• ✅ EventBusService con publish/subscribe básico
• ✅ Sistema de handlers y suscripciones
• ✅ Integración básica con LogSystem
• ✅ Error handling y retry básico
• ✅ Multi-tenant event isolation

Fase 2 - Funcionalidad avanzada

Objetivo: Características empresariales

• Event persistence y replay
• EventBusNgxsService para integración con NgXS
• Transactional events
• Event scheduling/delayed dispatch
• Performance monitoring y métricas
• Event validation avanzada

Fase 3 - Observabilidad y herramientas

Objetivo: Herramientas de desarrollo y debugging

• Event replay dashboard
• Event flow visualization
• Performance analytics
• Debugging tools
• Event sourcing completo

Estructura propuesta

libs/core/event-system/src/
  index.ts
  lib/
    models/
      base-event.ts
      domain-event.ts
      system-event.ts
      event-metadata.ts
      event-handler.ts
    services/
      event-bus.service.ts
      system-event.service.ts
      event-store.service.ts
      event-validation.service.ts
    decorators/
      event-handler.decorator.ts
      event-source.decorator.ts
    utils/
      event-serialization.ts
      event-filtering.ts
      event-routing.ts
    integrations/
      ngxs-event-bus.service.ts
      log-integration.ts

Próximos pasos críticos

Implementación inmediata requerida

1. Coordinación con LogSystem - Implementar en paralelo para evitar dependencias circulares
2. Completar Fase 1 - Requerido por múltiples módulos core
3. Testing de integración - Especialmente importante para eventos inter-módulos

Dependencias críticas

• Utilities: Para validaciones y utilities base
• LogSystem: Para auditoría y debugging (implementación paralela)

Módulos bloqueados sin esta librería

• Module Integrator (comunicación entre módulos)
• DataAccess (eventos de sincronización)
• Autenticación (eventos de seguridad)
• Action Registry (comunicación de acciones)

Estado recomendado: Implementar inmediatamente después de Utilities y en paralelo con LogSystem.

Nota: Al implementar, mantener API explícita, cobertura de pruebas exhaustiva y re-exportar desde src/index.ts.