Bapple Finder Architecture

• Frontend: Next.js App Router application
• Presentation Layer: /bapple-finder page with a client-side Leaflet map and ZIP/city/state/retailer search
• Scan Layer: scripts/scanBuschLightApple.js checks Busch Light Apple availability across US ZIP codes
• Source Data: Busch locator backend GraphQL endpoint used by busch.com/locator
• Transformation Layer: scripts/syncBappleFinderData.js converts found.log into a committed JSON dataset
• Static Data Layer: lib/bapple/finder-data.json deployed with the site
• Automation: scripts/refreshBappleData.sh runs on a scheduled every-2-hour refresh cadence
• Source Control: GitLab (gitlab.com/daburritoking_project_group/personal-site)
• CI/CD & Hosting: Vercel (vercel.com/daburritoking-projects/personal-site)

• Code is committed to GitLab and merged into main via standard Git workflows
• Vercel is connected directly to the GitLab repository
• Pushes to main trigger production deployments automatically
• Branches and merge requests generate preview deployments (when enabled)
• A scheduled task runs every 2 hours to scan ZIP-code availability, rebuild the JSON snapshot, commit it, and push it to GitLab
• That scheduled GitLab push triggers a fresh Vercel deployment so the public map updates from the new JSON snapshot
• Build step runs dependency installation and next build before deploy

1. Scheduled automation runs the Bapple refresh task every 2 hours
2. The scanner checks US ZIP codes against Busch's locator backend for BUSCH LT APPLE
3. The scan writes structured results, including found.log for ZIPs with reported availability
4. The sync script converts found.log into lib/bapple/finder-data.json
5. The refreshed JSON snapshot is committed and pushed to GitLab
6. GitLab triggers a Vercel deployment that publishes the updated dataset
7. User visits the Bapple Finder page
8. Browser fetches the deployed Next.js app and serialized Bapple dataset from Vercel
9. The client-side map renders ZIP markers and lets the user search or inspect retailer details

• The expensive nationwide scan is separated from the user-facing request path so the site stays fast
• The page is built around coverage discovery and retailer lookup instead of forcing users through Busch's one-ZIP-at-a-time locator flow
• Availability results are deduplicated by ZIP and packaged into a deployment-safe JSON snapshot for Vercel
• Search works across ZIP, city, state, and retailer labels so the page is useful for both local lookup and broad exploration
• Map markers represent ZIP centroids derived from scan data, which keeps the interface legible without pretending to show exact shelf locations
• The refresh loop keeps the site current without making every visitor wait on a live upstream scan

Upstream Isolation

• User page views never call Busch's locator backend directly from the browser
• The heavy scan runs in automation rather than during public requests
• Vercel serves a committed snapshot instead of live-scanning on demand
• The deployed map exposes only the curated JSON dataset needed for the experience

Data Handling Controls

• Only valid US 5-digit ZIP codes are scanned
• Availability is split into found, missing, and error logs for operational clarity
• 429 status code rate limits and transient upstream failures are retried with bounded backoff
• The sync step normalizes retailer summaries into a cleaner JSON structure before deployment

Operational Discipline

• Dataset changes move through the same GitLab + Vercel workflow as application code
• The refresh cadence is explicit and repeatable rather than ad hoc
• Committed JSON snapshots make deployments traceable and rollback-friendly

Bapple Finder works best when the slow, failure-prone, upstream lookup process is treated as a background data pipeline and the public page is treated as a fast, static-first browsing experience. That separation is what makes the feature feel simple to users while still doing a lot of work behind the scenes.

• Smarter incremental refreshes instead of always scanning the full ZIP universe
• A small operator dashboard for scan health, retry counts, and refresh timestamps
• Historical change tracking to show where availability is expanding or shrinking over time
• Clustered or density-based map views for easier large-scale browsing
• Drink Bapple with friends