Architecture Overview¶

This document provides a high-level overview of architectural decisions made for the interposition project.

Architecture Decision Records¶

ADR-0001: Use Pydantic v2 for Data Models ¶

Status: Accepted | Date: 2026-01-05

Use Pydantic v2 BaseModel for all data models to enable serialization, runtime validation, and immutability without custom code.

ADR-0002: Use SHA-256 for Request Fingerprinting ¶

Status: Accepted | Date: 2026-01-05

Use SHA-256 hash of canonicalized request fields as fingerprints for efficient and collision-resistant interaction matching.

ADR-0003: Use Generator Pattern for Response Streaming ¶

Status: Accepted | Date: 2026-01-05

Use Python generators for streaming response chunks to enable lazy evaluation, memory efficiency, and backpressure support.

ADR-0004: Use First-Match Strategy for Duplicate Interactions ¶

Status: Accepted | Date: 2026-01-05

When multiple interactions have identical fingerprints, return the first match to ensure deterministic and predictable replay behavior.

ADR-0005: Build Fingerprint Index for O(1) Lookup ¶

Status: Accepted | Date: 2026-01-05

Build an in-memory hash map index from fingerprints to interaction positions at cassette construction time for O(1) lookup performance.

ADR-0006: External Protocol Adapters Strategy ¶

Status: Accepted | Date: 2026-01-10

Keep protocol-specific adapters external to the core package. Users implement adapters suited to their integration strategy (monkey patching, proxy servers, etc.).

ADR-0007: Broker Mode Parameter for Record Functionality ¶

Status: Accepted | Date: 2026-01-25

Add a mode parameter to the Broker class (replay, record, auto) to determine replay vs. live-forward behavior, enabling record functionality.

ADR-0008: Use Literal Type for Broker Mode Values ¶

Status: Accepted | Date: 2026-01-25

Use typing.Literal with a type alias for broker mode values instead of Enum, for simplicity and Pydantic compatibility.

ADR-0009: LiveResponder Port for Upstream Forwarding ¶

Status: Accepted | Date: 2026-01-25

Define LiveResponder as a callable port (Callable[[InteractionRequest], Iterable[ResponseChunk]]) for protocol-agnostic upstream communication.

ADR-0010: Buffer Live Responses Before Recording ¶

Status: Accepted | Date: 2026-01-25

When forwarding in record/auto mode, fully collect live response chunks before returning any data, then record and return the buffered response.

ADR-0011: CassetteStore Persistence Port ¶

Status: Accepted | Date: 2026-01-30

Define CassetteStore as a Protocol port with load() and save() methods for storage-agnostic cassette persistence with automatic save on record.

ADR-0012: Cassette Save Failure Behavior ¶

Status: Accepted | Date: 2026-01-31

Define fail-fast behavior when cassette persistence fails (save errors are propagated and response streaming stops).

ADR-0013: CassetteStore Load Behavior for Missing Storage ¶

Status: Accepted | Date: 2026-02-16

Store implementations allow configuring missing-storage behavior at construction time: raise an error by default, or opt in to returning an empty cassette for record workflows.

ADR-0014: Require live_responder for Auto and Record Modes at Construction ¶

Status: Accepted | Date: 2026-02-25

Broker initialization now enforces that record and auto modes must be configured with a live_responder, providing fail-fast validation for deterministic workflows.