diff --git a/docs/compare_hands_flowchart.md b/docs/compare_hands_flowchart.md
new file mode 100644
index 0000000..7d530bf
--- /dev/null
+++ b/docs/compare_hands_flowchart.md
@@ -0,0 +1,29 @@
+# Game.compare_hands() flowchart
+
+```mermaid
+graph TD
+A[Start: Compare Hands] --> B{Player BUST?};
+
+B -- Yes --> L1[Result: Player LOSES (Chips - Bet)];
+B -- No --> C1{Dealer BUST?};
+
+C1 -- Yes --> W1[Result: Player WINS (Chips + 1:1)];
+C1 -- No --> D1{Player BJ AND NOT Dealer BJ?};
+ 
+D1 -- Yes --> W2[Result: Player WINS (Chips + 3:2)];
+D1 -- No --> E1{Dealer BJ?};
+
+E1 -- Yes --> F1{Player also BJ?};
+F1 -- Yes --> T1[Result: PUSH / Tie (Chips 0)];
+F1 -- No --> L1; 
+ 
+E1 -- No --> G1{Player Value > Dealer Value?};
+
+G1 -- Yes --> W1;
+G1 -- No --> H1{Player Value = Dealer Value?};
+
+H1 -- Yes --> T1;
+H1 -- No --> L1;
+
+L1 & W1 & W2 & T1 --> Z[End: Chip Balances Updated]
+```