messagekit

Package-first universal messaging infrastructure shared across microservices. Services should install the messagekit distribution and import it as messagekit. The package owns reusable event contracts, outbox persistence, Kafka publishing/consumption primitives, DLQ handling, health checks, and in-process dispatch ergonomics. It does not own gamification-specific reward rules or producer-specific business handlers.

Contents

• Event catalog
  • Event type and source validation
  • Published domain event examples
  • Trusted backend fact examples
  • Storage contract
• Integration guide
  • Install the package
  • Add a new event schema
  • Register and dispatch
  • Publish through the outbox
  • Consume idempotently
  • Optional later extension
  • Topic convention
• Broker selection guide
  • Overview: Dual-broker architecture
  • Recommended: Pattern 1 - Choose at publish time
  • Event streaming vs task queuing
  • When to use each broker (industry pattern Uber/Zalando)
  • Real-world example: E-commerce service
  • Optional: Pattern 2 - Bridge component
  • Decision matrix
  • See also
• Debezium CDC architecture
  • What is Debezium?
  • Outbox publishing: With vs without Debezium
  • How Debezium works: WAL-based CDC
  • Debezium EventRouter SMT
  • External infrastructure required
  • Performance impact
  • PostgreSQL WAL configuration
  • Troubleshooting
  • See also
• Kafka and RabbitMQ features comparison
  • Kafka features
  • RabbitMQ features
  • Feature comparison matrix
  • Configuration examples
  • See also
• Cross-service communication
  • Overview
  • Architecture principle: Database isolation
  • Complete event flow
  • Production deployment
  • Architecture decisions
  • Troubleshooting
  • See also
• Transactional outbox pattern - usage guide
  • Overview
  • Correct usage
  • Anti-pattern (dual write problem)
  • Key points
  • Testing
  • Background worker
• Dead letter queue (DLQ) handler guide
  • Overview
  • When to use each
  • Examples
  • Testing
  • Comparison
• Consumer transaction management guide
  • Overview
  • Transaction lifecycle
  • Critical: caller must commit
  • Correct usage
  • Transaction guarantees
  • Common pitfalls
  • Testing transaction boundaries
  • Integration with Kafka
  • Summary
• Troubleshooting
  • Events stuck in outbox (not publishing)
  • Duplicate messages consumed
  • Health check failures
  • Performance issues
  • Further assistance

The manual pages in this guide explain the stable contracts and wiring points. The generated API section documents the current Python implementation directly from source.

Option 3 later: if operational needs grow, add a small Eventing ops/admin service for replay, DLQ inspection, event catalog browsing, or observability. That later service stays outside the hot path and does not replace the package-first publish/consume model.