Kafka Events

12 Kafka event topics published and consumed by the Reports Service.

Event-Driven Architecture

Reports Service uses the transactional outbox pattern with DynamoDB Streams for reliable Kafka publishing. All events follow CloudEvents 1.0 format with tenant_id as partition key.

Published Events (6 topics)

Events emitted by reports-svc during report lifecycle operations.

Topic	Trigger	Key Payload Fields
`eventzr.reports.job.queued.v1`	Export job created	jobId, tenantId, templateId, format
`eventzr.reports.job.processing.v1`	Job starts processing	jobId, tenantId, startedAt
`eventzr.reports.report.ready.v1`	Report generation complete	jobId, tenantId, downloadUrl, format, fileSizeBytes
`eventzr.reports.report.failed.v1`	Report generation failed	jobId, tenantId, errorCode, errorMessage
`eventzr.reports.report.expired.v1`	Report output expired	jobId, tenantId, expiredAt
`eventzr.reports.export.large.v1`	Large export started (>1M rows)	jobId, tenantId, estimatedRows

Consumed Events (6 topics)

Events consumed by reports-svc from other services.

Topic	Action	Source
`eventzr.analytics.snapshot.created.v1`	Cache invalidation for analytics data	analytics-svc
`eventzr.analytics.snapshot.updated.v1`	Cache invalidation for updated snapshots	analytics-svc
`eventzr.studio.theme.updated.v1`	Refresh theme cache for PDF theming	studio-svc
`eventzr.event.completed.v1`	Auto-generate event completion report	event-svc
`eventzr.campaign.completed.v1`	Auto-generate campaign report	campaign-svc
`eventzr.tour.leg.completed.v1`	Auto-generate tour leg report	tour-svc

CloudEvents Envelope

Example: report.ready eventjson

{
  "specversion": "1.0",
  "id": "evt-550e8400-e29b-41d4-a716-446655440000",
  "source": "reports-svc",
  "type": "com.eventzr.reports.report.ready.v1",
  "datacontenttype": "application/json",
  "time": "2026-02-24T19:30:00.000Z",
  "subject": "tenant:a0000001-0000-0000-0000-000000000001",
  "data": {
    "jobId": "job-uuid",
    "tenantId": "a0000001-0000-0000-0000-000000000001",
    "templateId": "template-uuid",
    "format": "pdf",
    "fileSizeBytes": 245760,
    "downloadUrl": "https://s3.amazonaws.com/eventzr-reports-output/...",
    "generatedAt": "2026-02-24T19:30:00.000Z"
  }
}

Outbox Pattern

Reports Service uses the transactional outbox pattern for reliable event publishing:

Business operation writes to PostgreSQL + DynamoDB outbox table in same transaction
DynamoDB Streams triggers the outboxProcessorHandler Lambda
Handler reads new INSERT records and publishes to Kafka via OutboxService.publishToKafka()
Failed publishes are retried by DynamoDB Streams (up to 3 times)