docs/architecture/transaction-sequence.md

@@ -0,0 +1,37 @@
+```mermaid
+sequenceDiagram
+    participant User as User
+    participant Checkout as Checkout Service
+    participant Payment as Payment Gateway
+    participant DB as Database
+
+    %% Normal flow
+    User->>Checkout: Initiate Checkout
+    Checkout->>DB: Save Order
+    DB-->>Checkout: Order Confirmation
+    Checkout->>Payment: Process Payment
+    Payment-->>Checkout: Payment Success
+    Checkout->>User: Payment Successful
+
+    %% External failure
+    User->>Checkout: Initiate Checkout
+    Checkout->>DB: Save Order
+    DB-->>Checkout: Order Confirmation
+    Checkout->>Payment: Process Payment
+    Payment-->>Checkout: Payment Failure
+    Checkout->>DB: Rollback Order
+    DB-->>Checkout: Order Rollback
+    Checkout->>User: Payment Failed
+
+    %% DB failure
+    User->>Checkout: Initiate Checkout
+    Checkout->>DB: Save Order
+    DB-->>Checkout: Order Confirmation
+    Checkout->>Payment: Process Payment
+    Payment-->>Checkout: Payment Success
+    Checkout->>DB: Commit Order
+    DB-->>Checkout: Error
+    Checkout->>DB: Rollback Order
+    DB-->>Checkout: Order Rollback
+    Checkout->>User: Payment Successful, Order Error
+```