🏗️ Reading: Architecture Descriptions

The Provider Adapter abstracts the payment provider — making it swappable:

The document says: "Abstracts the External Payment Provider. Currently wraps Stripe's API. Designed to be swappable — switching providers requires only changing this adapter without touching the Business Logic Layer."

This is the Adapter design pattern:

• The Business Logic Layer calls a consistent internal interface
• The Adapter translates those calls into whatever the external provider (Stripe, PayPal, etc.) requires
• If the company switches from Stripe to Adyen, only the Adapter changes — no other layer is affected

Why this matters architecturally:
This is called "loose coupling" — components depend on abstractions, not concrete implementations. It reduces vendor lock-in and makes the system easier to maintain and test.

Architecture document vocabulary:

• abstracts → hides implementation details behind an interface
• swappable → can be replaced without affecting surrounding components
• adapter → translates between two incompatible interfaces
• standalone microservice → an independently deployable service with its own database and responsibilities

A new refund transaction is created — the original transaction is never modified:

The document states: "Transactions are append-only. To 'cancel' a payment, a separate refund transaction is created rather than updating the original."

This is the "immutable ledger" pattern:

• Transactions are like accounting journal entries — once written, they cannot be changed
• To reverse a charge, you CREATE a new record (a refund) rather than modifying the original
• The balance is derived by summing all transactions, not by reading a single mutable "current state"

Why immutability matters for financial data:

• ✅ Complete audit trail — every action is recorded
• ✅ Easier to debug — you can see exactly what happened and when
• ✅ Fraud detection — modified records would be immediately visible
• ✅ Compliance — financial regulations often require full transaction history

Vocabulary: "append-only"
Describes a data store where you can only add new records, never modify or delete existing ones. Also seen in: event sourcing, blockchain, write-ahead logs (WAL in PostgreSQL).

Processing continues — message queues decouple producers from consumers:

The architecture uses a Message Queue to publish payment.completed and payment.failed events. Consumers (Order Service, Notification Service, Analytics Service) read from this queue independently.

This is asynchronous event-driven architecture:

• The Payment Service publishes an event and moves on — it doesn't wait for consumers
• If Analytics goes down, the message queue holds the events until Analytics recovers
• When Analytics comes back online, it processes the backlog of missed events

Key properties of this pattern:

• Decoupling → the payment service doesn't know or care about Analytics
• Resilience → failure in one consumer doesn't cascade to the payment service
• Eventual consistency → Analytics data will be correct eventually (after catchup), not necessarily in real time

This is contrasted with synchronous (direct) calls: if the Payment Service called Analytics via HTTP, a slow or crashed Analytics service would make payment processing slow or fail too.

Architecture vocabulary: producer, consumer, event, topic, queue, backlog, eventual consistency, decoupling