integration-automation-patterns 0.1.0__py3-none-any.whl

integration_automation_patterns/__init__.py

@@ -0,0 +1,15 @@
+"""Reference patterns for reliable enterprise integration and workflow automation."""
+
+from .event_envelope import DeliveryStatus, EventEnvelope, RetryPolicy
+from .sync_boundary import RecordAuthority, SyncBoundary, SyncConflict
+
+__all__ = [
+    # Event handling
+    "DeliveryStatus",
+    "EventEnvelope",
+    "RetryPolicy",
+    # Sync boundary
+    "RecordAuthority",
+    "SyncBoundary",
+    "SyncConflict",
+]

integration_automation_patterns/event_envelope.py

@@ -0,0 +1,206 @@
+"""
+event_envelope.py — Reliable Event Handling for Enterprise Integration
+
+Enterprise integration fails most often at the transport layer — not because
+the business logic is wrong, but because events are dropped, duplicated, or
+processed out of order when systems restart, network partitions occur, or
+downstream services are temporarily unavailable.
+
+This module provides the structural primitives for building reliable,
+replay-safe event handling in enterprise integration workflows. The patterns
+apply regardless of the message broker (Kafka, SQS, Azure Service Bus,
+GCP Pub/Sub, RabbitMQ, MQ Series) or the enterprise platforms being integrated
+(CRM, ERP, ITSM, custom services).
+
+Design goals:
+  - Every event carries enough context to be replayed safely
+  - Retry behavior is explicit and bounded, not implicit
+  - Delivery status is inspectable without querying the broker
+  - Deduplication is structural (idempotency key), not a side effect of storage
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any
+
+
+class DeliveryStatus(Enum):
+    """
+    Tracks the lifecycle of one event through the integration pipeline.
+
+    Events move forward through this lifecycle. An event that has reached
+    FAILED should not be silently dropped — it should be routed to a dead
+    letter queue or an explicit remediation path.
+    """
+    PENDING = "pending"         # Created, not yet dispatched
+    DISPATCHED = "dispatched"   # Sent to broker or downstream system
+    ACKNOWLEDGED = "acknowledged"  # Downstream confirmed receipt
+    PROCESSED = "processed"     # Business logic completed successfully
+    RETRYING = "retrying"       # Failed at least once, within retry budget
+    FAILED = "failed"           # Retry budget exhausted; requires intervention
+    SKIPPED = "skipped"         # Intentionally not processed (e.g., duplicate)
+
+
+@dataclass(slots=True)
+class RetryPolicy:
+    """
+    Defines retry behavior for a failed event delivery attempt.
+
+    Explicit retry policies prevent two common failure modes:
+    1. Infinite retry loops that mask persistent downstream failures
+    2. Retry storms that overwhelm recovering services
+
+    Attributes:
+        max_attempts: Total number of delivery attempts allowed (including
+            the first). After this many attempts, the event moves to FAILED.
+        backoff_seconds: Base wait time between retries in seconds.
+            Actual wait = backoff_seconds * (2 ** attempt_number) when
+            exponential = True.
+        exponential: If True, use exponential backoff. If False, use
+            fixed-interval retry.
+        max_backoff_seconds: Upper bound on wait time when using exponential
+            backoff. Prevents unbounded delays.
+    """
+    max_attempts: int = 3
+    backoff_seconds: int = 30
+    exponential: bool = True
+    max_backoff_seconds: int = 3600
+
+    def wait_seconds_for_attempt(self, attempt_number: int) -> int:
+        """
+        Calculate the wait time before the given attempt number.
+
+        Args:
+            attempt_number: Zero-indexed attempt count (0 = first retry,
+                not the original attempt).
+
+        Returns:
+            Seconds to wait before attempting delivery again.
+        """
+        if not self.exponential:
+            return self.backoff_seconds
+        delay = self.backoff_seconds * (2 ** attempt_number)
+        return min(delay, self.max_backoff_seconds)
+
+    def is_exhausted(self, attempt_number: int) -> bool:
+        """Return True if the attempt budget is exhausted."""
+        return attempt_number >= self.max_attempts
+
+
+@dataclass
+class EventEnvelope:
+    """
+    A transport container for one unit of work in an enterprise integration flow.
+
+    An EventEnvelope carries the event payload alongside the metadata needed
+    to route, deduplicate, retry, and audit it. Separating envelope metadata
+    from business payload means integration infrastructure can handle
+    reliability concerns without touching business logic.
+
+    Design principle: The envelope must contain everything needed to replay
+    the event safely, without requiring coordination with the original sender.
+
+    Attributes:
+        event_id: Globally unique identifier for this event. Used as the
+            idempotency key — processing the same event_id twice should
+            produce the same result as processing it once.
+        event_type: A namespaced string identifying what happened.
+            Convention: "<domain>.<entity>.<action>" (e.g., "enrollment.student.updated")
+        source_system: Identifier for the system that originated the event.
+            Used for routing, filtering, and audit.
+        payload: The business data associated with the event. Keep payloads
+            small — prefer IDs + change summary over full record snapshots.
+            Full records should be fetched from the system of record at
+            processing time, not embedded in the event.
+        correlation_id: Links this event to a parent workflow, request, or
+            transaction. Enables tracing across system boundaries.
+        schema_version: Semantic version of the payload schema. Consumers
+            should reject events with unexpected versions rather than
+            silently misinterpreting the payload.
+        created_at: Wall clock time when the event was created. Stored in
+            UTC. Do not use for business ordering — use a sequence or
+            logical clock for that.
+        status: Current delivery status. Updated as the event moves through
+            the pipeline.
+        attempt_count: Number of delivery attempts made. Starts at 0,
+            incremented before each attempt.
+        retry_policy: Retry behavior for failed delivery attempts.
+        tags: Arbitrary key-value metadata for routing, filtering, or
+            observability. Not used in business logic.
+    """
+    event_id: str
+    event_type: str
+    source_system: str
+    payload: dict[str, Any]
+    correlation_id: str = ""
+    schema_version: str = "1.0"
+    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    status: DeliveryStatus = DeliveryStatus.PENDING
+    attempt_count: int = 0
+    retry_policy: RetryPolicy = field(default_factory=RetryPolicy)
+    tags: dict[str, str] = field(default_factory=dict)
+
+    def mark_dispatched(self) -> None:
+        """Record that this event has been sent to the broker or downstream system."""
+        self.attempt_count += 1
+        self.status = DeliveryStatus.DISPATCHED
+
+    def mark_acknowledged(self) -> None:
+        """Record that the downstream system confirmed receipt."""
+        self.status = DeliveryStatus.ACKNOWLEDGED
+
+    def mark_processed(self) -> None:
+        """Record that business processing completed successfully."""
+        self.status = DeliveryStatus.PROCESSED
+
+    def mark_failed(self) -> None:
+        """
+        Record a failed delivery attempt and advance status accordingly.
+
+        If the retry budget is not exhausted, status becomes RETRYING.
+        If the budget is exhausted, status becomes FAILED.
+        """
+        if self.retry_policy.is_exhausted(self.attempt_count):
+            self.status = DeliveryStatus.FAILED
+        else:
+            self.status = DeliveryStatus.RETRYING
+
+    def mark_skipped(self, reason: str = "") -> None:
+        """Record that this event was intentionally skipped (e.g., duplicate)."""
+        self.status = DeliveryStatus.SKIPPED
+        if reason:
+            self.tags["skip_reason"] = reason
+
+    def next_retry_wait_seconds(self) -> int:
+        """
+        Return the wait time before the next delivery attempt.
+
+        Returns 0 if the event is not in a retryable state.
+        """
+        if self.status != DeliveryStatus.RETRYING:
+            return 0
+        return self.retry_policy.wait_seconds_for_attempt(self.attempt_count)
+
+    def is_terminal(self) -> bool:
+        """Return True if the event has reached a state that requires no further processing."""
+        return self.status in {
+            DeliveryStatus.PROCESSED,
+            DeliveryStatus.FAILED,
+            DeliveryStatus.SKIPPED,
+        }
+
+    def to_audit_line(self) -> str:
+        """Format a structured log line for integration observability systems."""
+        return (
+            f"[INTEGRATION_EVENT] event_id={self.event_id} "
+            f"type={self.event_type} "
+            f"source={self.source_system} "
+            f"status={self.status.value} "
+            f"attempts={self.attempt_count} "
+            f"correlation={self.correlation_id or 'none'} "
+            f"schema={self.schema_version} "
+            f"created={self.created_at.isoformat()}"
+        )

integration_automation_patterns/sync_boundary.py

@@ -0,0 +1,214 @@
+"""
+sync_boundary.py — System-of-Record Synchronization Boundaries
+
+Bi-directional synchronization between enterprise systems (CRM and ERP,
+for example) fails in predictable ways. The most common failure is
+ambiguity about which system is authoritative for a given field when
+both systems have updated the same record simultaneously.
+
+This module provides the structural primitives for making synchronization
+boundaries explicit. It does not implement a full sync engine — it
+provides the objects needed to define authority, detect conflicts, and
+route resolution decisions to the right system.
+
+The pattern applies wherever two or more enterprise platforms must
+maintain consistent state for overlapping records: CRM + ERP,
+CRM + SIS (Student Information System), ERP + ITSM, and similar pairings.
+Platform-agnostic — the primitives work regardless of vendor.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any
+
+
+class RecordAuthority(Enum):
+    """
+    Defines which system is authoritative for a given field or record type.
+
+    In bi-directional sync, a field must have exactly one authoritative system.
+    Changes in the authoritative system propagate outward; changes in
+    non-authoritative systems are either rejected, queued for review, or
+    overwritten on next sync.
+
+    SHARED indicates that authority is determined per-field (see SyncBoundary)
+    rather than per-record. Use this sparingly — field-level authority
+    increases complexity.
+    """
+    SYSTEM_A = "system_a"    # Source system A is authoritative
+    SYSTEM_B = "system_b"    # Source system B is authoritative
+    SHARED = "shared"        # Field-level authority defined separately
+    MANUAL = "manual"        # Human review required before sync
+
+
+@dataclass(slots=True)
+class SyncConflict:
+    """
+    Represents a detected conflict between two systems' versions of a field.
+
+    A conflict occurs when both systems have modified the same field since
+    the last successful sync. The sync boundary policy determines how to
+    resolve it: prefer one system, defer to manual review, or apply a
+    merge function.
+
+    Attributes:
+        field_name: The name of the field where the conflict was detected.
+        value_a: The value in system A at detection time.
+        value_b: The value in system B at detection time.
+        last_sync_value: The agreed-upon value from the last successful sync.
+            If None, this is the first sync for this record.
+        detected_at: Wall-clock time when the conflict was detected.
+        record_id: Identifier of the record where the conflict exists.
+        system_a_modified_at: When system A last modified this field.
+            None if not available.
+        system_b_modified_at: When system B last modified this field.
+            None if not available.
+    """
+    field_name: str
+    value_a: Any
+    value_b: Any
+    record_id: str
+    last_sync_value: Any = None
+    detected_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    system_a_modified_at: datetime | None = None
+    system_b_modified_at: datetime | None = None
+
+    def last_writer(self) -> RecordAuthority | None:
+        """
+        Return which system made the most recent modification, based on
+        available modification timestamps.
+
+        Returns None if timestamps are unavailable for one or both systems.
+        """
+        if self.system_a_modified_at is None or self.system_b_modified_at is None:
+            return None
+        if self.system_a_modified_at > self.system_b_modified_at:
+            return RecordAuthority.SYSTEM_A
+        if self.system_b_modified_at > self.system_a_modified_at:
+            return RecordAuthority.SYSTEM_B
+        return None  # Same timestamp — cannot determine last writer
+
+
+@dataclass
+class SyncBoundary:
+    """
+    Defines the synchronization contract between two systems for one record type.
+
+    A SyncBoundary specifies:
+    1. Which fields exist in both systems
+    2. Which system is authoritative for each field
+    3. Which fields should never be synced (exclusions)
+
+    Keeping this as an explicit data object — rather than encoding it in
+    sync scripts — makes the contract readable, testable, and auditable.
+
+    Usage::
+
+        boundary = SyncBoundary(
+            record_type="contact",
+            system_a_id="crm",
+            system_b_id="erp",
+            field_authority={
+                "email": RecordAuthority.SYSTEM_A,
+                "billing_address": RecordAuthority.SYSTEM_B,
+                "preferred_name": RecordAuthority.SYSTEM_A,
+                "account_status": RecordAuthority.SYSTEM_B,
+            },
+            excluded_fields={"internal_notes", "crm_lead_score"},
+        )
+
+        # Check if a field is synced and which system wins
+        authority = boundary.authority_for("email")   # RecordAuthority.SYSTEM_A
+        is_synced = boundary.is_synced("internal_notes")  # False
+
+    Attributes:
+        record_type: A name for the type of record this boundary governs.
+        system_a_id: Identifier for the first system (e.g., "crm", "salesforce", "hubspot").
+        system_b_id: Identifier for the second system (e.g., "erp", "peoplesoft", "sap").
+        field_authority: Maps field names to which system is authoritative.
+        excluded_fields: Fields that are never synchronized, even if present
+            in both systems.
+        allow_system_b_override: If True, system B changes to SYSTEM_A-authoritative
+            fields are queued for manual review rather than silently discarded.
+            Default False (system A changes simply overwrite system B).
+    """
+    record_type: str
+    system_a_id: str
+    system_b_id: str
+    field_authority: dict[str, RecordAuthority] = field(default_factory=dict)
+    excluded_fields: set[str] = field(default_factory=set)
+    allow_system_b_override: bool = False
+
+    def authority_for(self, field_name: str) -> RecordAuthority | None:
+        """
+        Return the authoritative system for the given field.
+
+        Returns None if the field is not in the sync boundary (either
+        excluded or not mapped).
+        """
+        if field_name in self.excluded_fields:
+            return None
+        return self.field_authority.get(field_name)
+
+    def is_synced(self, field_name: str) -> bool:
+        """Return True if this field is part of the synchronization boundary."""
+        return field_name not in self.excluded_fields and field_name in self.field_authority
+
+    def synced_fields(self) -> list[str]:
+        """Return the list of field names that are actively synchronized."""
+        return [f for f in self.field_authority if f not in self.excluded_fields]
+
+    def fields_owned_by(self, authority: RecordAuthority) -> list[str]:
+        """Return all fields where the given system is authoritative."""
+        return [
+            f for f, auth in self.field_authority.items()
+            if auth == authority and f not in self.excluded_fields
+        ]
+
+    def detect_conflict(
+        self,
+        field_name: str,
+        value_a: Any,
+        value_b: Any,
+        record_id: str,
+        last_sync_value: Any = None,
+        system_a_modified_at: datetime | None = None,
+        system_b_modified_at: datetime | None = None,
+    ) -> SyncConflict | None:
+        """
+        Detect whether a conflict exists for the given field.
+
+        A conflict exists when both systems have a value different from the
+        last sync value, indicating both have modified the field since the
+        last sync. If only one system differs from the last sync value,
+        that system made the authoritative change and no conflict exists.
+
+        Returns None if no conflict is detected or if the field is not synced.
+        """
+        if not self.is_synced(field_name):
+            return None
+
+        # Both systems agree — no conflict
+        if value_a == value_b:
+            return None
+
+        # If we have a last sync value, check whether both systems diverged
+        if last_sync_value is not None:
+            a_changed = value_a != last_sync_value
+            b_changed = value_b != last_sync_value
+            if not (a_changed and b_changed):
+                # Only one system changed — not a conflict
+                return None
+
+        return SyncConflict(
+            field_name=field_name,
+            value_a=value_a,
+            value_b=value_b,
+            record_id=record_id,
+            last_sync_value=last_sync_value,
+            system_a_modified_at=system_a_modified_at,
+            system_b_modified_at=system_b_modified_at,
+        )

integration_automation_patterns-0.1.0.dist-info/METADATA

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: integration-automation-patterns
+Version: 0.1.0
+Summary: Reference patterns for reliable enterprise integration, workflow automation, and system-of-record synchronization.
+Author: Ashutosh Rana
+License: MIT
+Project-URL: Homepage, https://github.com/ashutoshrana/integration-automation-patterns
+Project-URL: Issues, https://github.com/ashutoshrana/integration-automation-patterns/issues
+Project-URL: Changelog, https://github.com/ashutoshrana/integration-automation-patterns/blob/main/CHANGELOG.md
+Keywords: enterprise-integration,event-driven,workflow-automation,crm,erp,idempotency,system-of-record,integration-patterns,enterprise-architecture
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Topic :: Office/Business
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: pytest-cov>=4.0; extra == "test"
+Provides-Extra: lint
+Requires-Dist: ruff>=0.4.0; extra == "lint"
+Provides-Extra: typecheck
+Requires-Dist: mypy>=1.0; extra == "typecheck"
+Provides-Extra: dev
+Requires-Dist: integration-automation-patterns[lint,test,typecheck]; extra == "dev"
+Dynamic: license-file
+
+# integration-automation-patterns
+
+[![CI](https://github.com/ashutoshrana/integration-automation-patterns/actions/workflows/ci.yml/badge.svg)](https://github.com/ashutoshrana/integration-automation-patterns/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+[![PyPI](https://img.shields.io/pypi/v/integration-automation-patterns.svg)](https://pypi.org/project/integration-automation-patterns/)
+
+Practical patterns for enterprise integration, workflow orchestration, and system-of-record synchronization in complex operating environments.
+
+## Why this repo exists
+
+Enterprise modernization usually breaks down at the integration layer:
+- brittle handoffs between systems
+- inconsistent event handling
+- weak retry and idempotency models
+- workflow logic scattered across tools
+- poor visibility into operational state
+
+This repository is a public-safe reference for patterns that help teams build more reliable integration and automation systems. The patterns are platform-agnostic and cloud-agnostic — applicable across any combination of CRM, ERP, ITSM, and custom services, on any cloud environment (AWS, GCP, Azure, OCI) or on-premises.
+
+## Scope
+
+This repo focuses on:
+- event-driven integration patterns with explicit retry and idempotency models
+- system-of-record synchronization with authority boundaries
+- workflow orchestration and escalation boundaries
+- observability for automation flows
+- public-safe architecture notes for enterprise operations
+
+The patterns do not assume any specific vendor, broker, or cloud platform.
+
+## Modules
+
+- `event_envelope.py`
+  Reliable event transport with explicit delivery status, bounded retry policy,
+  and structured audit logging. Works with any message broker (Kafka, SQS,
+  Azure Service Bus, GCP Pub/Sub, RabbitMQ, IBM MQ, and others).
+
+- `sync_boundary.py`
+  System-of-record synchronization contracts for bi-directional integration
+  between enterprise platforms. Explicit field-level authority assignment,
+  conflict detection, and exclusion management. Platform-agnostic.
+
+## Repository structure
+
+- `src/integration_automation_patterns/`
+  - `event_envelope.py` — event transport with retry and audit
+  - `sync_boundary.py` — bi-directional sync authority boundaries
+- `docs/architecture.md`
+- `docs/implementation-note-01.md`
+- `docs/adr/`
+- `examples/event-flow.yaml`
+- `CITATION.cff`
+- `CONTRIBUTING.md`
+- `GOVERNANCE.md`
+
+## Near-term roadmap
+
+- add integration reliability ADRs
+- add examples for retry-safe event handling across broker types
+- document action logging and audit boundaries
+- add workflow orchestration boundary patterns
+
+## Published notes
+
+- implementation note: [`docs/implementation-note-01.md`](./docs/implementation-note-01.md)
+
+## Intended audience
+
+- enterprise architects
+- integration engineers
+- workflow and automation operators
+- platform teams responsible for system-of-record reliability across CRM, ERP, and service platforms
+
+## Citing this work
+
+If you use these patterns in your work, see `CITATION.cff` or use GitHub's "Cite this repository" button above.

integration_automation_patterns-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+integration_automation_patterns/__init__.py,sha256=3Ovz1M_BrF1oeuR30kHC8F7pJFvAow8ubVP9OlkJH4M,410
+integration_automation_patterns/event_envelope.py,sha256=lLsyIzjj-6e3-xUFI8G9RaWMpiNAexQQi7olYFdL-Es,8780
+integration_automation_patterns/sync_boundary.py,sha256=BxNDRvr1yBtp5q--Q0t5lUYSIAS3qeT0C1ejDev8BC4,8713
+integration_automation_patterns-0.1.0.dist-info/licenses/LICENSE,sha256=L6npPxlrwrbxlLHOCdxrcGGhlRpL0YR7OevMVApNuG4,1070
+integration_automation_patterns-0.1.0.dist-info/METADATA,sha256=Ut7bzl14hF0C1-UooS22dlaz1OP1VskpoHq222hr-nw,4861
+integration_automation_patterns-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+integration_automation_patterns-0.1.0.dist-info/top_level.txt,sha256=FLqJ0YhyPI2Y0duuD1lFIfuInngldNmeeVnVKUnfqqQ,32
+integration_automation_patterns-0.1.0.dist-info/RECORD,,

integration_automation_patterns-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

integration_automation_patterns-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ashutosh Rana
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

integration_automation_patterns-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+integration_automation_patterns