docs/architecture/transaction-sequence.md

@@ -0,0 +1,39 @@
+```mermaid
+sequenceDiagram
+    participant Controller
+    participant Service
+    participant Repository
+    participant Domain
+    participant Integration
+
+    Controller->>Service: processPayment()
+    Service->>Repository: savePayment()
+    Repository-->>Service: paymentSaved
+    Service-->>Controller: paymentProcessed
+
+    alt External API call
+        Service->>Integration: sendPaymentRequest()
+        Integration-->>Service: paymentResponse
+    end
+
+    opt Within DB transaction
+        Service->>Repository: beginTransaction()
+        Repository-->>Service: transactionStarted
+        Service->>Repository: commitTransaction()
+    end
+    Note over Service: Success (commit)
+
+    opt External Failure
+        Service->>Integration: sendPaymentRequest()
+        Integration-->>Service: paymentFailure
+        Service->>Repository: rollbackTransaction()
+        Repository-->>Service: transactionRolledBack
+    end
+
+    opt DB Failure
+        Service->>Repository: throwException()
+        Repository-->>Service: exceptionOccurred
+        Service->>Repository: rollbackTransaction()
+        Repository-->>Service: transactionRolledBack
+    end
+```