system-event-listener: Architecture and Failure Modes

system-event-listener routes system.events (RabbitMQ) to registered HTTP handlers. The backbone of the event bus. All published events flow through here.

HOW HANDLER RESOLUTION WORKS:

1. Message arrives with event_type on system.events exchange

2. SELECT from system_event_handlers JOIN endpoint_registry WHERE event_type = ? AND is_active = 1

3. For each handler: POST the full event envelope to {base_url}{handler_path}

4. On non-2xx: log failed + publish {event_type}.failed

5. On no handlers: log WARN + publish {event_type}.failed

COMMON FAILURES:

1. "No active handlers for event type: X" warning: The event_type has no row in system_event_handlers with is_active=1, OR the handler_service has no matching row in endpoint_registry. Check both tables. Add missing handler or reactivate with UPDATE system_event_handlers SET is_active=1 WHERE event_type=?.

2. Handler endpoint URL cannot be resolved: handler_service in system_event_handlers does not match service_name in endpoint_registry. They must match exactly.

3. Handler service unreachable (ECONNREFUSED): Target service container is down. Restart the handler service. Check health endpoint.

4. Circular .failed events: A .failed event handler returns non-2xx, generating another .failed. Handlers like /events/acknowledge must always return 200.