integration

The Integration submodule provides the event-driven infrastructure for reliable, decoupled communication between internal business logic and external systems. Its core mechanism is the transactional outbox: when a domain event is produced, the event record is written to an outbox table in the same database transaction as the originating change. This guarantees that the event cannot be lost to a crash occurring between the business operation and the dispatch — either both the change and the event record are committed, or neither is.

A background processor reads unprocessed outbox entries and delivers them to their destinations — webhooks, queues, or integration profiles. Incoming events from external systems land in an inbox table for idempotent processing, preventing duplicate side-effects from retried deliveries. Events that exceed the maximum retry count move to a dead-letter store for manual inspection, ensuring transient failures do not result in permanent data loss.

The integration event catalog registers all known domain event types. Each catalog entry carries a slug, a human-readable name, an optional description, and an optional JSON Schema documenting the payload structure. The catalog is the single source of truth for event consumers: both event webhooks and integration profiles subscribe against catalog entries rather than hardcoded event names.

The Integration submodule owns the event catalog and the outbox/inbox engine. The Webhook Integration submodule consumes the catalog to power event-based webhook subscriptions. This separation keeps the transport layer pluggable — the same outbox events can be consumed by webhooks today and by a message queue tomorrow without changing the producer code.

MCP tools for the catalog (core.integration-events.*) allow AI agents and automation pipelines to inspect available event types, create new catalog entries, and manage existing ones programmatically.