Event Architecture
BANA services communicate asynchronously through three mechanisms: Kafka (event streaming + CDC), Redis pub/sub (lightweight event bus), and WebSocket (real-time client notifications). This page catalogs every topic, channel, and event type.
Kafka Topics
Defined in packages/core/src/queues/kafka/topics.ts.
Application Events
| Topic | Producer | Consumer(s) | Purpose |
|---|---|---|---|
payment.success | sale | finance, inventory | Payment for a sale order completed |
purchase-order.received | inventory | finance | Purchase order received and confirmed |
commerce.initialized | commerce | finance, inventory | New merchant onboarding completed |
merchant.created | commerce | inventory | New merchant created (inventory setup) |
product.created | commerce | taxation | New product created |
product.updated | commerce | taxation | Product updated |
product-variant.created | commerce | pricing | New product variant created |
product-variant.updated | commerce | pricing | Product variant updated |
ledger.generate | ledger (producer) | ledger (consumer) | Ledger PDF/XLSX generation job |
CDC Topics (Debezium)
Defined in packages/search/src/common/kafka-topics.ts. Debezium captures PostgreSQL WAL changes and publishes them to Kafka, which the search service consumes to sync Typesense.
| CDC Topic | Source Table | Typesense Collection |
|---|---|---|
nx.seller.public.Organizer | public.Organizer | organizers |
nx.seller.public.Merchant | public.Merchant | merchants |
nx.seller.public.Category | public.Category | categories |
nx.seller.public.Device | public.Device | devices |
nx.seller.public.SaleChannel | public.SaleChannel | sale-channels |
nx.seller.public.Product | public.Product | products |
nx.seller.public.ProductInfo | public.ProductInfo | (enriches products) |
Dead letter queue: nx.seller.cdc.dlq
Kafka Consumer Groups
| Service | Client ID | Group ID | Topics |
|---|---|---|---|
| finance | SVC-00040-FINANCE_CONSUMER | SVC-00040-FINANCE_CONSUMER_GROUP | payment.success, purchase-order.received, commerce.initialized |
| inventory | SVC-00050-INVENTORY_CONSUMER | SVC-00050-INVENTORY_CONSUMER_GROUP | payment.success, commerce.initialized, merchant.created |
| pricing | SVC-00070-PRICING_CONSUMER | SVC-00070-PRICING_CONSUMER_GROUP | product-variant.created, product-variant.updated |
| taxation | SVC-00130-TAXATION_CONSUMER | SVC-00130-TAXATION_CONSUMER_GROUP | product.created, product.updated |
| ledger | SVC-00060-LEDGER-{n} | SVC-00060-LEDGER_GROUP | ledger.generate |
| search (CDC) | commerce-cdc-consumer | commerce-cdc-group | All nx.seller.public.* CDC topics |
Kafka Producer Client IDs
| Service | Client ID |
|---|---|
| commerce | SVC-00020-COMMERCE_PRODUCER |
| sale | SVC-00030-SALE_PRODUCER |
| inventory | SVC-00050-INVENTORY_PRODUCER |
| ledger | SVC-00060-LEDGER-01 |
Redis Pub/Sub Event Channels
Lightweight event channels for intra-service communication. These don't go through Kafka — they're direct Redis pub/sub.
Payment Events
Defined in packages/core/src/common/events/payment-events.ts.
| Channel | Publisher | Subscriber(s) | Purpose |
|---|---|---|---|
payment.order.success | sale (payment webhook handler) | finance, inventory | Order payment completed — triggers income recording and stock adjustment |
Sale Check Events
Defined in packages/sale/src/common/sale-check.constants.ts.
| Event | Description |
|---|---|
sale.check.created | New check created for a sale order |
sale.check.updated | Check amounts/items updated |
sale.check.merged | Two checks merged together |
sale.check.rolledBack | Check merge rolled back |
sale.check.paid | Check fully paid |
sale.order.merged | Two orders merged |
sale.order.mergeRolledBack | Order merge rolled back |
sale.order.split | Order split into multiple orders |
WebSocket Topics
WebSocket topics follow the pattern ws:{namespace}.{domain}.{entity}. Room names follow wr:{namespace}/{path}.
Builder utilities
Defined in packages/core/src/common/events/websocket-events.ts:
WebSocketTopics— builds topic strings:ws:observation.sale.sale-orderWebSocketRooms— builds room names:wr:observation/merchants/{merchantId}
Per-service topics
Sale (packages/sale/src/common/websocket.ts):
| Topic | Purpose |
|---|---|
ws:observation.sale.sale-order | Order created/updated |
ws:observation.sale.sale-order-item | Order item changes |
ws:observation.sale.sale-check | Check state changes |
ws:observation.sale.kitchen-ticket | Kitchen ticket dispatched |
ws:observation.sale.kitchen-ticket-item | Kitchen ticket item updates |
ws:observation.allocation.allocation-usage | Seat/allocation usage changes |
Payment (packages/payment/src/common/websocket.ts):
| Topic | Purpose |
|---|---|
ws:observation.payment.transaction | Payment transaction status updates |
ws:observation.payment.payment-attempt | Individual payment attempt events |
Outreach (packages/outreach/src/components/websocket/topics.ts):
| Topic | Purpose |
|---|---|
ws:observation.outreach.inquiry.submitted | New inquiry submitted (real-time admin notification) |
Webhook Event Types
MQ-Pay → Sale (Payment Webhooks)
Defined in packages/sale/src/common/webhook-types.ts. The sale service receives these from MQ-Pay via the X-Webhook-Event-Type HTTP header:
| Event Type | Direction | Purpose |
|---|---|---|
mq-pay:attempt.success | MQ-Pay → Sale | Payment attempt succeeded |
mq-pay:attempt.failed | MQ-Pay → Sale | Payment attempt failed |
mq-pay:attempt.expired | MQ-Pay → Sale | Payment attempt timed out |
mq-pay:attempt.cancelled | MQ-Pay → Sale | Payment attempt cancelled by user |
mq-pay:transaction.settled | MQ-Pay → Sale | Full transaction settled (all items paid) |
mq-pay:transaction.cancelled | MQ-Pay → Sale | Transaction cancelled |
MQ-Pay Internal Events
Published via Node.js EventEmitter within the MQ-Pay library:
| Event | Purpose |
|---|---|
mq-pay:transaction.created | New payment transaction created |
mq-pay:transaction.settled | Transaction fully settled |
mq-pay:transaction.cancelled | Transaction cancelled |
mq-pay:attempt.created | Payment attempt initiated |
mq-pay:attempt.sent | Request sent to provider |
mq-pay:attempt.success | Provider confirmed success |
mq-pay:attempt.failed | Provider reported failure |
mq-pay:attempt.expired | Attempt timed out |
mq-pay:attempt.cancelled | Attempt cancelled |
mq-pay:refund.success | Refund completed |
mq-pay:refund.failed | Refund failed |
These are bridged to the sale service via MQPaySaleEventAdapter → SaleEventMapperService → SalePaymentEventHandlerService.
Event Flow Diagrams
New Merchant Onboarding
Payment Flow
Product Sync (CDC)
Related Pages
| Page | Description |
|---|---|
| Architecture | Service registry, dependency chain, component matrix |
| Infrastructure — Kafka | Kafka KRaft cluster setup |
| Infrastructure — CDC | Debezium CDC pipeline configuration |
| Packages Overview | Per-package documentation |