System Event Plugin

Topic Namespace

system.health               // Platform health status update
system.deployment.started   // Deployment pipeline started
system.deployment.completed // Deployment finished (success or failure)
system.config.changed       // Configuration reloaded
system.tenant.suspended     // Tenant account suspended
system.maintenance.started  // Maintenance window opened
system.maintenance.ended    // Maintenance window closed
system.broadcast            // Admin broadcast to all users

Message Formats

// system.health
interface SystemHealthEvent {
  serviceId: string;      // e.g., 'process-engine', 'atlas-forms'
  status: 'healthy' | 'degraded' | 'critical' | 'offline';
  message?: string;
  metrics?: {
    cpuPercent: number;
    memoryPercent: number;
    requestsPerSecond: number;
    errorRate: number;
  };
  timestamp: string;
}

// system.deployment.completed
interface DeploymentCompletedEvent {
  deploymentId: string;
  environment: 'staging' | 'production';
  version: string;
  status: 'success' | 'failed' | 'rolledBack';
  deployedAt: string;
  services: string[];     // services updated in this deployment
}

// system.broadcast
interface SystemBroadcastEvent {
  id: string;
  severity: 'info' | 'warning' | 'critical';
  title: string;
  message: string;
  targetAudience: 'all' | 'admin' | 'tenant';
  tenantId?: string;      // set when targetAudience === 'tenant'
  expiresAt?: string;
}

Subscribing to System Events

// System health dashboard
stream.subscribe('bas', 'system.health', (envelope) => {
  const { serviceId, status, metrics } = envelope.body;
  healthStore.updateService(serviceId, {
    status,
    cpu: metrics?.cpuPercent,
    memory: metrics?.memoryPercent,
    errorRate: metrics?.errorRate,
  });
});

// Maintenance window banner
stream.subscribe('bas', 'system.maintenance.*', (envelope) => {
  const topic = envelope.meta.topic;
  if (topic === 'system.maintenance.started') {
    bannerStore.show({
      type: 'warning',
      message: 'Maintenance in progress — some features may be unavailable',
      persistent: true,
    });
  } else if (topic === 'system.maintenance.ended') {
    bannerStore.dismiss();
  }
});

Admin Broadcast Handling

// system.broadcast — may be tenant-specific
stream.subscribe('bas', 'system.broadcast', (envelope) => {
  const { severity, title, message, targetAudience, tenantId } = envelope.body;

  // Filter: only show if intended for current tenant or all users
  if (targetAudience === 'tenant' && tenantId !== currentTenantId) return;

  toastService.show({
    type: severity === 'critical' ? 'error' : severity,
    title,
    message,
    duration: severity === 'critical' ? 0 : 10000, // persist critical
  });
});

Combining with TenantBoundaryHook

System events often carry a tenantId. Register a TenantBoundaryHook to automatically filter out events not intended for the current tenant before they reach subscribers:

// TenantBoundaryHook filters at priority 130 — before subscriber delivery
server.incomingPipeline.addHook(new TenantBoundaryHook({
  currentTenantId: authStore.getTenantId(),
  tenantIdPath: 'body.tenantId',  // where to find tenantId in the envelope
  allowNull: true,                // allow messages with no tenantId (global broadcasts)
}));