Software Architecture and Design

# ADR 0003: Adopt Event-Driven Transaction Outbox Pattern
Date: 2026-03-15
Status: Accepted

## Context
- Dual-write problems exist between database updates and message publishing.
- Microservices require guaranteed message dispatch without distributed transactions (2PC).

## Options
1) Two-Phase Commit (2PC) — high latency, low availability.
2) Direct API calls — tight coupling, cascading failures.
3) Transactional Outbox Pattern — write events to local DB table in same transaction, tail log via CDC.

## Decision
We choose Option 3 (Transactional Outbox) to ensure eventual consistency and service decoupling.

## Consequences
+ Guarantees at-least-once event delivery.
- Requires idempotent consumer logic to handle duplicate delivery.

import { PactV3 } from '@pact-foundation/pact';
import fetch from 'node-fetch';

const provider = new PactV3({ consumer: 'CheckoutService', provider: 'OrderService' });

test('verifies order creation contract', async () => {
  provider
    .given('customer account is active')
    .uponReceiving('a request to create a new order')
    .withRequest('POST', '/v1/orders', {
      headers: { 'Idempotency-Key': 'key-123', 'Content-Type': 'application/json' },
      body: { customerId: '11111111-1111-1111-1111-111111111111', items: [{ sku: 'ITEM-A', qty: 1 }] }
    })
    .willRespondWith(201);

  await provider.executeTest(async mock => {
    const res = await fetch(`${mock.url}/v1/orders`, {
      method: 'POST',
      headers: { 'Idempotency-Key': 'key-123', 'Content-Type': 'application/json' },
      body: JSON.stringify({ customerId: '11111111-1111-1111-1111-111111111111', items: [{ sku: 'ITEM-A', qty: 1 }] })
    });
    expect(res.status).toBe(201);
  });
});

// ArchUnit Java Rule: Enforce Hexagonal Architecture Boundaries
import com.tngtech.archunit.junit.AnalyzeClasses;
import com.tngtech.archunit.junit.ArchTest;
import com.tngtech.archunit.lang.syntax.ArchRuleDefinition;

@AnalyzeClasses(packages = "com.example.app")
public class ArchitectureRules {
    @ArchTest
    static final var domain_independent_of_infrastructure =
        ArchRuleDefinition.noClasses().that().resideInAPackage("..domain..")
            .should().dependOnClassesThat().resideInAPackage("..infrastructure..");
}

// Python Resilience: Exponential Backoff Retry with Tenacity
from tenacity import retry, stop_after_attempt, wait_exponential
import requests

@retry(stop=stop_after_attempt(4), wait=wait_exponential(multiplier=0.2, max=3))
def fetch_remote_config(service_url: str):
    response = requests.get(service_url, timeout=2.0)
    response.raise_for_status()
    return response.json()