docs: Document Flask backend fix for checkout 500 error (MOBILE-REACT-NATIVE-4S)

APPLY_FIX_INSTRUCTIONS.md

@@ -0,0 +1,76 @@
+# Quick Fix Instructions for sentry-demos/empower Repository
+
+## Immediate Action Required
+
+Someone with write access to `sentry-demos/empower` needs to apply this fix to resolve the HTTP 500 error in the checkout endpoint.
+
+## Option 1: Apply the Patch (Fastest)
+
+```bash
+# Clone the empower repository
+git clone https://github.com/sentry-demos/empower.git
+cd empower
+
+# Create fix branch
+git checkout -b error-500---wxj3au
+
+# Download and apply the patch from this PR
+curl -o fix.patch https://raw.githubusercontent.com/sentry-demos/sentry_react_native/error-500---wxj3au/BACKEND_FIX.patch
+git am fix.patch
+
+# Push to remote
+git push -u origin error-500---wxj3au
+
+# Create PR to merge to master
+```
+
+## Option 2: Manual Fix (30 seconds)
+
+1. Open `flask/src/main.py` in the empower repository
+2. Go to line 225
+3. Find these lines:
+   ```python
+                if len(quantities) == 0:
+                    raise Exception("Invalid checkout request: cart is empty")
+
+                quantities = {int(k): v for k, v in cart['quantities'].items()}
+   ```
+
+4. Change to:
+   ```python
+                quantities = {int(k): v for k, v in cart['quantities'].items()}
+                if len(quantities) == 0:
+                    raise Exception("Invalid checkout request: cart is empty")
+
+   ```
+
+5. Commit and push:
+   ```bash
+   git add flask/src/main.py
+   git commit -m "fix: Move quantities assignment before usage in checkout endpoint
+
+   Fixes MOBILE-REACT-NATIVE-4S"
+   git push
+   ```
+
+## Testing the Fix
+
+After applying:
+
+1. Deploy the Flask backend to staging/production
+2. Open the mobile app
+3. Add items to cart
+4. Tap "Submit Checkout"
+5. Verify HTTP 200 response (not 500)
+6. Check that no `UnboundLocalError` appears in logs
+
+## Why This Fixes the Issue
+
+The code was checking `len(quantities)` before `quantities` was defined, causing Python to raise `UnboundLocalError`. Moving the assignment before the check ensures the variable exists before it's used.
+
+## Contact
+
+If you need help applying this fix, refer to:
+- Full documentation: `BACKEND_FIX_MOBILE-REACT-NATIVE-4S.md`
+- Patch file: `BACKEND_FIX.patch`
+- PR: https://github.com/sentry-demos/sentry_react_native/pull/128

BACKEND_FIX.patch

@@ -0,0 +1,39 @@
+From d106af49b6a7e82b1439bdec50f8491c1e555c75 Mon Sep 17 00:00:00 2001
+From: Cursor Agent <cursoragent@cursor.com>
+Date: Mon, 8 Jun 2026 22:36:00 +0000
+Subject: [PATCH] fix: Move quantities assignment before usage in checkout
+ endpoint
+
+Fixes MOBILE-REACT-NATIVE-4S
+
+The checkout endpoint was raising an UnboundLocalError because the
+quantities variable was being referenced (len(quantities)) before
+it was assigned. This caused HTTP 500 errors when the mobile app
+attempted to place orders.
+
+Changes:
+- Move quantities assignment before the len() check
+- Ensures variable is defined before being used
+- Prevents UnboundLocalError in checkout validation flow
+---
+ flask/src/main.py | 2 +-
+ 1 file changed, 1 insertion(+), 1 deletion(-)
+
+diff --git a/flask/src/main.py b/flask/src/main.py
+index 5bc7f9c0..2802d87e 100644
+--- a/flask/src/main.py
++++ b/flask/src/main.py
+@@ -222,10 +222,10 @@ def checkout():
+     try:
+         if validate_inventory:
+             with sentry_sdk.start_span(op="code.block", name="checkout.process_order"):
++                quantities = {int(k): v for k, v in cart['quantities'].items()}
+                 if len(quantities) == 0:
+                     raise Exception("Invalid checkout request: cart is empty")
+
+-                quantities = {int(k): v for k, v in cart['quantities'].items()}
+                 inventory_dict = {x.productid: x for x in inventory}
+                 for product_id in quantities:
+                     inventory_count = inventory_dict[product_id].count if product_id in inventory_dict else 0
+-- 
+2.43.0

BACKEND_FIX_MOBILE-REACT-NATIVE-4S.md

@@ -0,0 +1,65 @@
+# Backend Fix for MOBILE-REACT-NATIVE-4S
+
+## Issue Summary
+Flask `/checkout` endpoint references local variable `quantities` before assignment, raising `UnboundLocalError` that surfaces as HTTP 500 to the mobile app.
+
+## Root Cause
+In the Flask backend repository (`sentry-demos/empower`), file `flask/src/main.py`:
+- Line 225 does `len(quantities)` before `quantities` is assigned on line 228
+- The order-validation code checks the variable before defining it
+
+## Reproduction Steps
+1. Open the mobile app and add items to the cart
+2. Tap Submit Checkout, sending POST to flask.empower-plant.com/checkout
+3. Flask executes `len(quantities)` before `quantities` is assigned
+4. `UnboundLocalError` is raised and re-raised, returning HTTP 500
+5. Mobile placeOrder captures '500 - INTERNAL SERVER ERROR'
+
+## Fix Required
+**Repository**: `sentry-demos/empower`  
+**File**: `flask/src/main.py`  
+**Lines**: 223-229
+
+### Current Code (Broken)
+```python
+    try:
+        if validate_inventory:
+            with sentry_sdk.start_span(op="code.block", name="checkout.process_order"):
+                if len(quantities) == 0:  # ❌ ERROR: quantities not yet defined
+                    raise Exception("Invalid checkout request: cart is empty")
+
+                quantities = {int(k): v for k, v in cart['quantities'].items()}  # Defined here
+                inventory_dict = {x.productid: x for x in inventory}
+```
+
+### Fixed Code
+```python
+    try:
+        if validate_inventory:
+            with sentry_sdk.start_span(op="code.block", name="checkout.process_order"):
+                quantities = {int(k): v for k, v in cart['quantities'].items()}  # ✅ Define first
+                if len(quantities) == 0:
+                    raise Exception("Invalid checkout request: cart is empty")
+
+                inventory_dict = {x.productid: x for x in inventory}
+```
+
+## Implementation Instructions
+1. Clone the `sentry-demos/empower` repository
+2. Create branch `error-500---wxj3au` from `master`
+3. Edit `flask/src/main.py` line 225-228
+4. Move the `quantities` assignment (currently line 228) to before the `len()` check (currently line 225)
+5. Commit with message including "Fixes MOBILE-REACT-NATIVE-4S"
+6. Push to branch and create PR
+
+## Verification
+After applying the fix:
+1. Deploy the Flask backend
+2. Test checkout flow from mobile app
+3. Verify no UnboundLocalError occurs
+4. Confirm HTTP 200 response on successful checkout
+
+## Notes
+- This is a one-line fix (moving the assignment)
+- No logic changes required
+- The fix prevents the variable from being used before it's defined

FIX_SUMMARY.md

@@ -0,0 +1,86 @@
+# Fix Summary for MOBILE-REACT-NATIVE-4S
+
+## Status: ✅ Fix Identified and Documented (Awaiting Backend Deployment)
+
+## What Was Done
+
+### 1. Root Cause Identified
+Located the bug in `sentry-demos/empower` repository:
+- **File**: `flask/src/main.py`
+- **Lines**: 225-228
+- **Issue**: Variable `quantities` used before assignment, causing `UnboundLocalError`
+
+### 2. Fix Created and Verified
+- ✅ Syntax validated with Python compiler
+- ✅ Fix tested in isolated repository
+- ✅ Git patch file created
+- ✅ One-line change: move variable assignment before usage
+
+### 3. Complete Documentation Package
+Created in this PR (branch: `error-500---wxj3au`):
+- **BACKEND_FIX_MOBILE-REACT-NATIVE-4S.md** - Full technical documentation
+- **BACKEND_FIX.patch** - Ready-to-apply git patch
+- **APPLY_FIX_INSTRUCTIONS.md** - Step-by-step application guide
+
+### 4. Git Commits
+- ✅ Committed with "Fixes MOBILE-REACT-NATIVE-4S" message
+- ✅ Pushed to `sentry-demos/sentry_react_native` (this repository)
+- ✅ PR created: https://github.com/sentry-demos/sentry_react_native/pull/128
+
+## The Fix (1 Line Change)
+
+**Location**: `sentry-demos/empower/flask/src/main.py:225-228`
+
+**Change**: Move line 228 to before line 225
+
+```python
+# BEFORE (Broken)
+if len(quantities) == 0:  # ❌ quantities not defined yet!
+    raise Exception("Invalid checkout request: cart is empty")
+quantities = {int(k): v for k, v in cart['quantities'].items()}
+
+# AFTER (Fixed)
+quantities = {int(k): v for k, v in cart['quantities'].items()}  # ✅ Define first
+if len(quantities) == 0:
+    raise Exception("Invalid checkout request: cart is empty")
+```
+
+## Why Backend Repository Access Was Required
+
+The bug exists in `sentry-demos/empower` (Flask backend), not in this mobile repository. The agent account has write access only to `sentry-demos/sentry_react_native`, so the fix is:
+1. Fully documented here
+2. Ready to apply to the backend
+3. Requires someone with `sentry-demos/empower` write access
+
+## Next Steps for Deployment
+
+Someone with access to `sentry-demos/empower` should:
+
+1. **Quick Apply** (30 seconds):
+   ```bash
+   cd /path/to/empower
+   git checkout -b error-500---wxj3au
+   curl -o fix.patch https://raw.githubusercontent.com/sentry-demos/sentry_react_native/error-500---wxj3au/BACKEND_FIX.patch
+   git am fix.patch
+   git push -u origin error-500---wxj3au
+   ```
+
+2. **Test**: Deploy Flask backend and verify checkout works
+3. **Confirm**: No more HTTP 500 errors or UnboundLocalError
+
+## Impact
+- ✅ Fixes HTTP 500 errors in mobile app checkout
+- ✅ Resolves UnboundLocalError in Flask backend
+- ✅ No mobile app changes required
+- ✅ Simple one-line fix
+
+## Files to Reference
+- See `APPLY_FIX_INSTRUCTIONS.md` for detailed steps
+- See `BACKEND_FIX.patch` for the exact code change
+- See `BACKEND_FIX_MOBILE-REACT-NATIVE-4S.md` for full technical details
+
+---
+
+**Branch**: `error-500---wxj3au`  
+**PR**: https://github.com/sentry-demos/sentry_react_native/pull/128  
+**Target Repository for Fix**: `sentry-demos/empower`