Event Catalog (Kafka + Outbox)

Last updated: 2026-03-06

Kafka Topics

| Topic | Purpose | Producer | Consumer / Tooling | | --- | --- | --- | --- | | kes.orchestrator.events | KES proxy mutation events (method/path/statusCode) | services/api (kes-orchestrator route) | services/svc-tenders consume:kes-events | | kes.orchestrator.events.dlq | Dead-letter events for failed kes.orchestrator.events processing | services/svc-tenders kesEventConsumer | replay:kes-dlq | | kes.orchestrator.domain-events | Domain events from DB outbox (tenders + kes_orchestrator streams) | services/svc-tenders relay:kes-outbox | consume:kes-domain-events |

Domain Event Envelope (kes.orchestrator.domain-events)

Current envelope version: schemaVersion = "1.0.0"

Top-level fields:

• eventId
• eventType
• eventVersion
• occurredAt
• intentId
• producer
• payload

payload common fields (from outbox triggers):

• eventType
• eventVersion
• actorId
• sourcePayload
• tenderId (for tenders stream) or caseId (for kes_orchestrator stream)

Implemented Tender Domain Events

Source: tenders_events table + outbox trigger (0028_tenders_events_outbox.sql)

| Event Type | Emitted from API | Stream | Persisted in tenders_events | Enqueued to outbox | | --- | --- | --- | --- | --- | | TENDER_SUBMITTED | POST /tenders/submit | tenders | Yes | Yes | | TENDER_APPROVED | POST /admin/tenders/:id/approve | tenders | Yes | Yes | | TENDER_REJECTED | POST /admin/tenders/:id/reject | tenders | Yes | Yes |

Implemented Legacy Tender Domain Events

Source: legacy_tender_events table + outbox trigger (0031_legacy_tender_events_outbox.sql)

| Event Type | Emitted from API legacy flow | Stream | Persisted in legacy_tender_events | Enqueued to outbox | | --- | --- | --- | --- | --- | | TENDER_CREATED | POST /api/v1/tenders/legacy/propose | tenders_legacy | Yes | Yes | | BID_SUBMITTED | POST /api/v1/tenders/legacy/:id/bids | tenders_legacy | Yes | Yes | | BIDDING_CLOSED | POST /api/v1/tenders/legacy/:id/close | tenders_legacy | Yes | Yes | | AWARD_PROPOSED | POST /api/v1/tenders/legacy/:id/award/propose | tenders_legacy | Yes | Yes | | AWARD_RATIFIED | POST /api/v1/tenders/legacy/:id/award/ratify | tenders_legacy | Yes | Yes |

Implemented KES Orchestrator Domain Events

Source: kes_orchestrator_events table + outbox trigger (0027_kes_outbox.sql)

| Event Type | Typical action | Stream | Enqueued to outbox | | --- | --- | --- | --- | | CASE_CREATED | Create case | kes_orchestrator | Yes | | LANDOWNER_APPROVED | Landowner approval | kes_orchestrator | Yes | | AUCTION_PUBLISHED | Auction publication | kes_orchestrator | Yes | | FUNDING_CONFIRMED | Funding confirmation | kes_orchestrator | Yes | | TASK_ASSIGNED | Task assignment | kes_orchestrator | Yes | | INSPECTION_SUBMITTED | Inspection submission | kes_orchestrator | Yes | | PAYMENT_REQUESTED | Payment request | kes_orchestrator | Yes | | PAYMENT_APPROVED | Payment approval | kes_orchestrator | Yes | | PAYMENT_SETTLED | Payment settlement | kes_orchestrator | Yes | | CASE_CLOSED | Case close | kes_orchestrator | Yes |

Consumer + Projection Status

• consume:kes-domain-events is implemented and writes to:
  • kes_domain_event_projection_events
  • kes_domain_event_projection_counters
  • kes_domain_event_projection_aggregates
• Idempotency is implemented via kafka_consumer_idempotency.
• Outbox poison replay command is implemented: replay:kes-outbox-poison.
• Strict contract validation is enabled for kes.orchestrator.domain-events:
  • required envelope fields: schemaVersion, eventType, eventVersion, eventId, occurredAt, intentId, producer, payload
  • invalid payloads are dead-lettered with explicit reasonCode.

Backlog / To Add

• [ ] TENDER_CANCELLED event (requires cancel endpoint wiring in svc-tenders API layer).
• [ ] TENDER_REOPENED event (requires reopen endpoint wiring in svc-tenders API layer).
• [ ] Contract tests for producer/consumer compatibility on kes.orchestrator.domain-events.
• [ ] Event-version policy (eventType + schema evolution rules per event family).