integration-automation-patterns 0.1.0__tar.gz

integration_automation_patterns-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,77 @@
+# 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/pyproject.toml

@@ -0,0 +1,73 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "integration-automation-patterns"
+version = "0.1.0"
+description = "Reference patterns for reliable enterprise integration, workflow automation, and system-of-record synchronization."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+  { name = "Ashutosh Rana" }
+]
+keywords = [
+  "enterprise-integration",
+  "event-driven",
+  "workflow-automation",
+  "crm",
+  "erp",
+  "idempotency",
+  "system-of-record",
+  "integration-patterns",
+  "enterprise-architecture",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: System :: Distributed Computing",
+  "Topic :: Office/Business",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/ashutoshrana/integration-automation-patterns"
+Issues = "https://github.com/ashutoshrana/integration-automation-patterns/issues"
+Changelog = "https://github.com/ashutoshrana/integration-automation-patterns/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+test = ["pytest>=7.0", "pytest-cov>=4.0"]
+lint = ["ruff>=0.4.0"]
+typecheck = ["mypy>=1.0"]
+dev = [
+  "integration-automation-patterns[test,lint,typecheck]",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --tb=short"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+ignore_missing_imports = true

integration_automation_patterns-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

integration_automation_patterns-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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/src/integration_automation_patterns.egg-info/PKG-INFO

@@ -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/src/integration_automation_patterns.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/integration_automation_patterns/__init__.py
+src/integration_automation_patterns/event_envelope.py
+src/integration_automation_patterns/sync_boundary.py
+src/integration_automation_patterns.egg-info/PKG-INFO
+src/integration_automation_patterns.egg-info/SOURCES.txt
+src/integration_automation_patterns.egg-info/dependency_links.txt
+src/integration_automation_patterns.egg-info/requires.txt
+src/integration_automation_patterns.egg-info/top_level.txt
+tests/test_event_envelope.py
+tests/test_sync_boundary.py

integration_automation_patterns-0.1.0/src/integration_automation_patterns.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

integration_automation_patterns-0.1.0/src/integration_automation_patterns.egg-info/requires.txt

@@ -0,0 +1,13 @@
+
+[dev]
+integration-automation-patterns[lint,test,typecheck]
+
+[lint]
+ruff>=0.4.0
+
+[test]
+pytest>=7.0
+pytest-cov>=4.0
+
+[typecheck]
+mypy>=1.0

integration_automation_patterns-0.1.0/src/integration_automation_patterns.egg-info/top_level.txt

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

integration_automation_patterns-0.1.0/tests/test_event_envelope.py

@@ -0,0 +1,158 @@
+"""Tests for integration_automation_patterns.event_envelope."""
+
+import pytest
+
+from integration_automation_patterns.event_envelope import (
+    DeliveryStatus,
+    EventEnvelope,
+    RetryPolicy,
+)
+
+
+# ---------------------------------------------------------------------------
+# RetryPolicy
+# ---------------------------------------------------------------------------
+
+class TestRetryPolicy:
+    def test_default_values(self):
+        rp = RetryPolicy()
+        assert rp.max_attempts == 3
+        assert rp.backoff_seconds == 30
+        assert rp.exponential is True
+        assert rp.max_backoff_seconds == 3600
+
+    def test_is_exhausted_at_limit(self):
+        rp = RetryPolicy(max_attempts=3)
+        assert rp.is_exhausted(3) is True
+
+    def test_is_not_exhausted_below_limit(self):
+        rp = RetryPolicy(max_attempts=3)
+        assert rp.is_exhausted(2) is False
+
+    def test_fixed_backoff(self):
+        rp = RetryPolicy(backoff_seconds=10, exponential=False)
+        assert rp.wait_seconds_for_attempt(0) == 10
+        assert rp.wait_seconds_for_attempt(5) == 10
+
+    def test_exponential_backoff(self):
+        rp = RetryPolicy(backoff_seconds=10, exponential=True, max_backoff_seconds=9999)
+        assert rp.wait_seconds_for_attempt(0) == 10   # 10 * 2^0
+        assert rp.wait_seconds_for_attempt(1) == 20   # 10 * 2^1
+        assert rp.wait_seconds_for_attempt(2) == 40   # 10 * 2^2
+
+    def test_exponential_backoff_capped(self):
+        rp = RetryPolicy(backoff_seconds=10, exponential=True, max_backoff_seconds=50)
+        assert rp.wait_seconds_for_attempt(10) == 50  # capped at max
+
+
+# ---------------------------------------------------------------------------
+# EventEnvelope lifecycle
+# ---------------------------------------------------------------------------
+
+def _make_event(**kwargs):
+    defaults = dict(
+        event_id="evt-001",
+        event_type="enrollment.student.updated",
+        source_system="crm",
+        payload={"student_id": "S-1"},
+    )
+    defaults.update(kwargs)
+    return EventEnvelope(**defaults)
+
+
+class TestEventEnvelopeInitial:
+    def test_initial_status_pending(self):
+        ev = _make_event()
+        assert ev.status == DeliveryStatus.PENDING
+
+    def test_initial_attempt_count_zero(self):
+        ev = _make_event()
+        assert ev.attempt_count == 0
+
+    def test_is_not_terminal_when_pending(self):
+        ev = _make_event()
+        assert ev.is_terminal() is False
+
+    def test_fields_stored(self):
+        ev = _make_event(correlation_id="corr-99", schema_version="2.0")
+        assert ev.event_id == "evt-001"
+        assert ev.event_type == "enrollment.student.updated"
+        assert ev.source_system == "crm"
+        assert ev.correlation_id == "corr-99"
+        assert ev.schema_version == "2.0"
+
+
+class TestEventEnvelopeTransitions:
+    def test_mark_dispatched_increments_attempt(self):
+        ev = _make_event()
+        ev.mark_dispatched()
+        assert ev.attempt_count == 1
+        assert ev.status == DeliveryStatus.DISPATCHED
+
+    def test_mark_acknowledged(self):
+        ev = _make_event()
+        ev.mark_dispatched()
+        ev.mark_acknowledged()
+        assert ev.status == DeliveryStatus.ACKNOWLEDGED
+
+    def test_mark_processed_is_terminal(self):
+        ev = _make_event()
+        ev.mark_dispatched()
+        ev.mark_processed()
+        assert ev.status == DeliveryStatus.PROCESSED
+        assert ev.is_terminal() is True
+
+    def test_mark_failed_within_budget_sets_retrying(self):
+        ev = _make_event()
+        ev.mark_dispatched()   # attempt_count = 1
+        ev.mark_failed()       # attempt_count=1 < max_attempts=3 → RETRYING
+        assert ev.status == DeliveryStatus.RETRYING
+        assert ev.is_terminal() is False
+
+    def test_mark_failed_budget_exhausted_sets_failed(self):
+        ev = _make_event()
+        for _ in range(3):     # exhaust budget
+            ev.mark_dispatched()
+        ev.mark_failed()
+        assert ev.status == DeliveryStatus.FAILED
+        assert ev.is_terminal() is True
+
+    def test_mark_skipped_is_terminal(self):
+        ev = _make_event()
+        ev.mark_skipped(reason="duplicate")
+        assert ev.status == DeliveryStatus.SKIPPED
+        assert ev.is_terminal() is True
+        assert ev.tags["skip_reason"] == "duplicate"
+
+    def test_mark_skipped_without_reason(self):
+        ev = _make_event()
+        ev.mark_skipped()
+        assert ev.status == DeliveryStatus.SKIPPED
+        assert "skip_reason" not in ev.tags
+
+    def test_next_retry_wait_zero_when_not_retrying(self):
+        ev = _make_event()
+        assert ev.next_retry_wait_seconds() == 0
+
+    def test_next_retry_wait_positive_when_retrying(self):
+        ev = _make_event()
+        ev.mark_dispatched()
+        ev.mark_failed()
+        assert ev.next_retry_wait_seconds() > 0
+
+
+class TestEventEnvelopeAudit:
+    def test_to_audit_line_contains_key_fields(self):
+        ev = _make_event(correlation_id="corr-1")
+        ev.mark_dispatched()
+        line = ev.to_audit_line()
+        assert "[INTEGRATION_EVENT]" in line
+        assert "event_id=evt-001" in line
+        assert "type=enrollment.student.updated" in line
+        assert "source=crm" in line
+        assert "correlation=corr-1" in line
+
+    def test_audit_line_no_correlation(self):
+        ev = _make_event()
+        line = ev.to_audit_line()
+        assert "correlation=none" in line

integration_automation_patterns-0.1.0/tests/test_sync_boundary.py

@@ -0,0 +1,197 @@
+"""Tests for integration_automation_patterns.sync_boundary."""
+
+from datetime import datetime, timezone
+
+import pytest
+
+from integration_automation_patterns.sync_boundary import (
+    RecordAuthority,
+    SyncBoundary,
+    SyncConflict,
+)
+
+
+def _dt(offset_seconds: int = 0) -> datetime:
+    from datetime import timedelta
+    return datetime(2026, 1, 1, tzinfo=timezone.utc) + timedelta(seconds=offset_seconds)
+
+
+def _boundary(**kwargs):
+    defaults = dict(
+        record_type="contact",
+        system_a_id="crm",
+        system_b_id="erp",
+        field_authority={
+            "email": RecordAuthority.SYSTEM_A,
+            "billing_address": RecordAuthority.SYSTEM_B,
+            "status": RecordAuthority.SYSTEM_A,
+        },
+        excluded_fields={"internal_notes"},
+    )
+    defaults.update(kwargs)
+    return SyncBoundary(**defaults)
+
+
+# ---------------------------------------------------------------------------
+# SyncBoundary.authority_for
+# ---------------------------------------------------------------------------
+
+class TestSyncBoundaryAuthority:
+    def test_returns_authority_for_known_field(self):
+        b = _boundary()
+        assert b.authority_for("email") == RecordAuthority.SYSTEM_A
+        assert b.authority_for("billing_address") == RecordAuthority.SYSTEM_B
+
+    def test_returns_none_for_excluded_field(self):
+        b = _boundary()
+        assert b.authority_for("internal_notes") is None
+
+    def test_returns_none_for_unknown_field(self):
+        b = _boundary()
+        assert b.authority_for("unknown_field") is None
+
+    def test_is_synced_true_for_mapped_field(self):
+        b = _boundary()
+        assert b.is_synced("email") is True
+
+    def test_is_synced_false_for_excluded(self):
+        b = _boundary()
+        assert b.is_synced("internal_notes") is False
+
+    def test_is_synced_false_for_unmapped(self):
+        b = _boundary()
+        assert b.is_synced("no_such_field") is False
+
+    def test_synced_fields_excludes_excluded(self):
+        b = _boundary()
+        synced = b.synced_fields()
+        assert "internal_notes" not in synced
+        assert "email" in synced
+
+    def test_fields_owned_by_system_a(self):
+        b = _boundary()
+        owned = b.fields_owned_by(RecordAuthority.SYSTEM_A)
+        assert "email" in owned
+        assert "status" in owned
+        assert "billing_address" not in owned
+
+    def test_fields_owned_by_system_b(self):
+        b = _boundary()
+        owned = b.fields_owned_by(RecordAuthority.SYSTEM_B)
+        assert "billing_address" in owned
+        assert "email" not in owned
+
+
+# ---------------------------------------------------------------------------
+# SyncBoundary.detect_conflict
+# ---------------------------------------------------------------------------
+
+class TestDetectConflict:
+    def test_no_conflict_when_values_equal(self):
+        b = _boundary()
+        result = b.detect_conflict("email", "a@x.com", "a@x.com", "rec-1")
+        assert result is None
+
+    def test_conflict_when_both_differ_from_last_sync(self):
+        b = _boundary()
+        conflict = b.detect_conflict(
+            field_name="email",
+            value_a="new_a@x.com",
+            value_b="new_b@x.com",
+            record_id="rec-1",
+            last_sync_value="old@x.com",
+        )
+        assert conflict is not None
+        assert isinstance(conflict, SyncConflict)
+        assert conflict.field_name == "email"
+
+    def test_no_conflict_when_only_a_changed(self):
+        b = _boundary()
+        result = b.detect_conflict(
+            field_name="email",
+            value_a="new_a@x.com",
+            value_b="old@x.com",
+            record_id="rec-1",
+            last_sync_value="old@x.com",
+        )
+        assert result is None
+
+    def test_no_conflict_when_only_b_changed(self):
+        b = _boundary()
+        result = b.detect_conflict(
+            field_name="email",
+            value_a="old@x.com",
+            value_b="new_b@x.com",
+            record_id="rec-1",
+            last_sync_value="old@x.com",
+        )
+        assert result is None
+
+    def test_conflict_without_last_sync_value(self):
+        b = _boundary()
+        conflict = b.detect_conflict("email", "a@x.com", "b@x.com", "rec-1")
+        assert conflict is not None
+
+    def test_no_conflict_for_excluded_field(self):
+        b = _boundary()
+        result = b.detect_conflict("internal_notes", "val_a", "val_b", "rec-1")
+        assert result is None
+
+    def test_no_conflict_for_unmapped_field(self):
+        b = _boundary()
+        result = b.detect_conflict("unknown_field", "val_a", "val_b", "rec-1")
+        assert result is None
+
+    def test_conflict_contains_correct_values(self):
+        b = _boundary()
+        conflict = b.detect_conflict(
+            "email", "a@x.com", "b@x.com", "rec-42", last_sync_value="old@x.com"
+        )
+        assert conflict.value_a == "a@x.com"
+        assert conflict.value_b == "b@x.com"
+        assert conflict.last_sync_value == "old@x.com"
+        assert conflict.record_id == "rec-42"
+
+
+# ---------------------------------------------------------------------------
+# SyncConflict.last_writer
+# ---------------------------------------------------------------------------
+
+class TestSyncConflictLastWriter:
+    def test_last_writer_a_wins(self):
+        c = SyncConflict(
+            field_name="email",
+            value_a="new",
+            value_b="old",
+            record_id="r1",
+            system_a_modified_at=_dt(100),
+            system_b_modified_at=_dt(50),
+        )
+        assert c.last_writer() == RecordAuthority.SYSTEM_A
+
+    def test_last_writer_b_wins(self):
+        c = SyncConflict(
+            field_name="email",
+            value_a="old",
+            value_b="new",
+            record_id="r1",
+            system_a_modified_at=_dt(50),
+            system_b_modified_at=_dt(100),
+        )
+        assert c.last_writer() == RecordAuthority.SYSTEM_B
+
+    def test_last_writer_none_when_timestamps_missing(self):
+        c = SyncConflict(field_name="email", value_a="a", value_b="b", record_id="r1")
+        assert c.last_writer() is None
+
+    def test_last_writer_none_when_same_timestamp(self):
+        ts = _dt(100)
+        c = SyncConflict(
+            field_name="email",
+            value_a="a",
+            value_b="b",
+            record_id="r1",
+            system_a_modified_at=ts,
+            system_b_modified_at=ts,
+        )
+        assert c.last_writer() is None