integration-automation-patterns 0.20.0

Reference patterns for reliable enterprise integration, workflow automation, and system-of-record synchronization.

integration-automation-patterns

]

---

The problem this solves

Enterprise systems that span CRM + ERP + messaging fail in predictable ways: duplicate event processing, partial transaction failures, and lost messages under retry. This library provides reference implementations of the patterns that solve these problems structurally — idempotent event envelopes, field-level authority boundaries, distributed saga orchestration, and transactional outbox — so integration logic is explicit, testable, and broker-agnostic.

---

Architecture

Inbound Event
     │
     ▼
EventEnvelope
(event_id, idempotency_key, source, schema_version, metadata)
     │
     ├─ Duplicate Check ──────────────────────────────────────────┐
     │   event_id already processed? → skip, return cached result │
     │                                                             │
     ├─ Authority Check ──────────────────────────────────────────┤
     │   SyncBoundary.detect_conflict()                           │
     │   Which system owns this field?                            │
     │   Conflict → raise ConflictError, log authority boundary   │
     │                                                             │
     ├─ Retry Policy ─────────────────────────────────────────────┤
     │   Exponential backoff, max attempts                        │
     │   CircuitBreaker: CLOSED → OPEN → HALF_OPEN recovery       │
     │                                                             │
     └─ Outbox → DB Transaction → Reliable Publish ───────────────┘
         Write event in same DB tx as domain change
         Relay process delivers to broker independently

---

Installation

pip install integration-automation-patterns

---

30-second example

from integration_automation_patterns.event_envelope import EventEnvelope, DeliveryStatus
from integration_automation_patterns.sync_boundary import SyncBoundary, FieldAuthority

# Idempotent event envelope — safe to process multiple times
event = EventEnvelope(
    event_id="evt_8f3a1b",
    source="salesforce",
    event_type="contact.updated",
    payload={"email": "[e-mail]", "phone": "[phone]"},
    schema_version="1.0",
)

# Field-level authority — who owns each field across systems?
boundary = SyncBoundary(
    authorities={
        "email": FieldAuthority(owner="salesforce", read_others=["erp", "itsm"]),
        "phone": FieldAuthority(owner="erp", read_others=["salesforce"]),
    }
)

conflicts = boundary.detect_conflict(
    incoming_system="salesforce",
    fields={"email": "[e-mail]", "phone": "[phone]"},
)
# conflicts → {"phone": ConflictDetail(owner="erp", incoming_system="salesforce")}

if not conflicts:
    event.mark_delivered()

See docs/implementation-note-01.md for a full walkthrough.

---

Pattern catalog

Pattern	Class	Problem Solved
Idempotent Event	EventEnvelope	Duplicate processing under at-least-once delivery
Authority Model	SyncBoundary	Field-level conflict detection across systems
Circuit Breaker	CircuitBreaker	Cascading failure isolation with automatic recovery
Saga	SagaOrchestrator	Multi-step distributed transaction with compensation
Outbox	OutboxPublisher	Reliable event publish in the same DB transaction
Kafka Envelope	KafkaEnvelope	Partition routing, schema versioning, DLQ support
Webhook Validation	WebhookHandler	HMAC-SHA256 signature verification + idempotency
Change Data Capture	CDCEvent	Typed INSERT/UPDATE/DELETE with Debezium parsing

---

Repository structure

src/integration_automation_patterns/
├── event_envelope.py         # Reliable event transport + retry + delivery status
├── sync_boundary.py          # Bi-directional SOR sync with field authority
├── circuit_breaker.py        # CLOSED/OPEN/HALF_OPEN state machine
├── saga.py                   # Distributed saga orchestrator + compensation
├── outbox.py                 # Transactional outbox for at-least-once delivery
├── kafka_envelope.py         # Kafka-aware envelope: partition key, DLQ, schema
├── webhook_handler.py        # HMAC-SHA256 webhook verification
└── cdc_event.py              # Change Data Capture event types (Debezium-compatible)
docs/
├── architecture.md
├── implementation-note-01.md  # Event-driven integration reliability
├── implementation-note-02.md  # Idempotency in enterprise event processing
└── adr/

See ECOSYSTEM.md for the full broker, connector, and framework coverage matrix.

---

Published notes

• Implementation Note 01 — Event-driven integration reliability
• Implementation Note 02 — Idempotency in enterprise event processing

---

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for guidelines. Run pytest tests/ -v to verify your changes before opening a pull request.

---

Citation

If you use these patterns in research or production, please cite:

@software{rana2026iap,
  author    = {Rana, Ashutosh},
  title     = {integration-automation-patterns: Enterprise integration reliability patterns},
  year      = {2026},
  url       = {https://github.com/ashutoshrana/integration-automation-patterns},
  license   = {MIT}
}

Or use GitHub's "Cite this repository" button above (reads CITATION.cff).

---

Part of the enterprise AI patterns trilogy

Library	Focus	Regulation
enterprise-rag-patterns	What to retrieve	FERPA identity-scoped RAG
regulated-ai-governance	What agents may do	FERPA, HIPAA, GLBA policy enforcement
integration-automation-patterns	How data flows	Event-driven enterprise integration

---

License

MIT — see LICENSE.