Loading module
Resolving locale, route permissions, and workspace projection.
Event-Driven Architecture
Status: ACTIVE
Audit Date: 2026-03-16
Audit Basis: code-verified repository inspection
Reality Verdict
- VERIFIED: Kafka is real and operational in this repo.
- VERIFIED: Kafka is currently most important in KES + outbox + projection flows.
- VERIFIED: Kafka is not yet equally central across all product domains.
- VERIFIED: Broad claims that the entire platform is already event-driven would be misleading.
Messaging Infrastructure
Configuration
Primary runtime configuration lives in:
Verified environment variables:
KES_ORCHESTRATOR_KAFKA_ENABLED
READ 2026-03-28T23:42:21.903Z
READ 2026-03-29T04:52:41.869Z
CORE STRICT SAFE DELETE AFTER RERUN REPORT
PUBLIC | DRAFT | v1.0.0
READ 2026-03-29T03:13:33.020Z
KES_ORCHESTRATOR_KAFKA_BROKERSKES_ORCHESTRATOR_KAFKA_TOPICKES_ORCHESTRATOR_KAFKA_CLIENT_IDKES_ORCHESTRATOR_KAFKA_GROUP_IDKES_ORCHESTRATOR_KAFKA_FROM_BEGINNINGKES_ORCHESTRATOR_KAFKA_DLQ_ENABLEDKES_ORCHESTRATOR_KAFKA_DLQ_TOPICKES_ORCHESTRATOR_KAFKA_MAX_RETRIESKES_ORCHESTRATOR_KAFKA_RETRY_BASE_MSKES_ORCHESTRATOR_KAFKA_RETRY_MAX_MSKES_OUTBOX_ENABLEDKES_OUTBOX_KAFKA_TOPICKES_OUTBOX_POLL_MSKES_OUTBOX_BATCH_SIZEKES_OUTBOX_MAX_ATTEMPTSKES_OUTBOX_MONITORING_ENABLEDKES_OUTBOX_MONITORING_HOSTKES_OUTBOX_MONITORING_PORTKES_DOMAIN_EVENTS_DLQ_ENABLEDKES_DOMAIN_EVENTS_DLQ_TOPICKafka Client Libraries
- VERIFIED:
kafkajs is used in:
Topic Inventory
Producer Inventory
1. KES proxy mutation producer
- Source:
services/api/src/routes/kes-orchestrator.ts
- Trigger: every non-GET KES proxy call after upstream response is received.
- Event type:
- Safety verdict:
- VERIFIED: direct producer, not outbox-driven.
- VERIFIED: not transactionally tied to upstream service DB commit.
- VERIFIED: producer failure is swallowed after comment-only handling.
- Verdict: useful operational event stream, but not canonical durability.
2. Outbox relay producer
- Source:
services/svc-tenders/src/kafka/kesOutboxRelay.ts
- Trigger: polling undispatched rows from
kes_outbox_events.
- Query evidence:
- uses
FOR UPDATE SKIP LOCKED
- marks
dispatched_at or increments attempts
- Safety verdict:
- VERIFIED: this is the durable producer path.
- VERIFIED: DB write and outbox enqueue are transactionally linked via triggers.
- VERIFIED: Kafka publication is async and at-least-once.
Consumer Inventory
1. KesEventConsumer
- Source:
services/svc-tenders/src/kafka/kesEventConsumer.ts
- Consumes:
kes.orchestrator.events
- Failure behavior:
- strict JSON/envelope validation
- retry with exponential backoff
- DLQ publish for parse failures and handler failures
- idempotency via
kafka_consumer_idempotency
- Critical truth:
- VERIFIED: current default
main() handler logs consumption only.
- Business-side effects beyond logging are UNVERIFIED in the current wired runtime.
2. kesDomainEventConsumer
- Source:
services/svc-tenders/src/kafka/kesDomainEventConsumer.ts
- Consumes:
kes.orchestrator.domain-events
- Side effects:
- writes
kes_domain_event_projection_events
- writes
kes_domain_event_projection_counters
- writes
kes_domain_event_projection_aggregates
- Failure behavior:
- strict contract validation
- optional DLQ for invalid domain payloads
- idempotency keyed by
eventId
- Verdict:
- VERIFIED: this is the most meaningful downstream event-driven processor in the repo.
Outbox Pattern
Tables and Migrations
Canonicality
- VERIFIED: KES/tender outbox is real and canonical for domain-event publication.
- VERIFIED: outbox is partial platform-wide. It is not used consistently by all services/domains.
Idempotency / Duplicate Protection
Consumer idempotency store
Actual behavior
- VERIFIED: at-least-once delivery with consumer-side duplicate protection.
- VERIFIED: not true exactly-once.
- VERIFIED:
kesEventConsumer uses payload.requestId fallback eventId.
- VERIFIED:
kesDomainEventConsumer uses eventId.
DLQ and Replay
Implemented
kes.orchestrator.events.dlq
- poison outbox replay:
- relay monitoring:
Incomplete
- INFERRED: domain-events DLQ replay story is weaker/documented less clearly than orchestrator-event DLQ replay.
Event Contract Discipline
- VERIFIED: KES orchestrator proxy events have explicit envelope schema and parser.
- VERIFIED: domain events enforce
schemaVersion, eventType, eventVersion.
- VERIFIED: event naming in KES area is much more disciplined than the rest of the repo.
- UNVERIFIED: broader cross-service event version compatibility governance beyond these flows.
KES Event Flow
Command / mutation entry
- Web or operator action calls
/api/v1/kes/orchestrator/* via services/api.
- Gateway proxies to
svc-tenders /kes-orchestrator/*.
svc-tenders persists KES state + writes kes_orchestrator_events.- Postgres trigger enqueues row into
kes_outbox_events.
- Optional relay publishes to
kes.orchestrator.domain-events.
- Domain consumer updates projection tables.
- Read routes expose case, projection, control-plane, and suggestions.
Supporting evidence
Strongest Event-Driven Areas
- VERIFIED: KES + tender outbox + domain-event projection pipeline
- VERIFIED: idempotency + DLQ tooling in
svc-tenders
- VERIFIED: replay/operator tooling is real enough to be operationally meaningful
Misleading Claims To Avoid
- “Kafka is the universal backbone of every product flow.”
- “All KES Kafka consumers perform business mutations.”
- False; the
kes.orchestrator.events consumer is currently mostly transport/logging oriented.
- “Financial-layer Kafka orchestration is already a core production runtime.”
- False; current evidence points to demo/script-heavy usage.