Architecture: Data Flow — mcd-tracker
Architecture: Data Flow — mcd-tracker
Purpose
What happens when? How information moves through the system at runtime. These flows map directly to API endpoints and frontend screens.
Flow 1: Scan Receipt + Extract Survey Code
Flow 2: Complete Survey + Save BOGO Code
Flow 3: Redeem BOGO at Counter
Flow 4: Check Slot Availability (Dashboard)
Flow 5: Auto-Detect Location (GPS)
Flow 6: Slot Limit Rejection
Auth Flow (Keycloak OIDC)
Key Observations
- Receipt-first workflow. The user journey starts with a receipt photo, not a form. Camera → OCR → survey → BOGO code → save. The app optimizes for speed at the McDonald's counter.
- Two codes, two entities. Survey code (on receipt, extracted by OCR) and BOGO code (from survey, user enters). Receipt holds one, CouponUsage holds the other. Linked by receipt_id.
- GPS is the UX unlock. Auto-detecting which McDonald's the user is at removes the biggest friction: typing a location name. Combined with the camera, the entire scan-to-save flow can be nearly zero-input.
- Photo as proof. Receipt photos serve as proof of purchase. Over time, this builds a trail that could let users stop carrying physical receipts.
- 409 for slot limit. Same as before — semantically correct for "this would conflict with current state."
- Survey completion is tracked. A receipt can exist without a BOGO code (user scanned but didn't finish the survey). This prevents double-counting.
Related
arch-domain-mcd-tracker— entity model these flows operate onarch-deployment-mcd-tracker— where these services runproject-mcd-tracker— project page