How snacsnoc/grocery-app works
Project Type and Purpose
• This is a full-stack Flask web application that accepts user search queries, calls multiple undocumented grocer search APIs in parallel, caches geolocation lookups, normalizes results, and presents them via server-rendered templates and client-side JS.
File Structure
• Top-level:
• app.py, routes.py – Flask application entry and routing (Controller)
• services.py, supermarket.py, product_data_parser.py – service layer / domain logic (Model)
• helpers.py, location_lookupc.py – utility modules (e.g., disk cache for postal→lat/long)
• templates/, static/ – server-side views and frontend assets
• config.py, error_handlers.py – configuration and centralized error handling
• Procfile, railway.json – deployment descriptors
• Pattern: MVC within Flask, plus a simple file-based cache, and parallel external API calls.
README for Insights
• Key flows:
• User enters postal code + query → Flask route
• Parallel HTTP requests to each grocer API
• Cache postal→coordinates on disk
• Normalize and aggregate product data
• Render templates and expose data to frontend JS for sorting/display
• Tech stack: Python 3.11, Flask, Bootstrap, custom JS, simple file cache
a. Client Side
• Browser UI: HTML templates + Bootstrap CSS + custom JS
b. Web Server (Flask App)
• Controller Layer: routes.py, app.py
• Service Layer: services.py (orchestrator), supermarket.py (API wrappers), product_data_parser.py (parsing/normalization)
• Utilities: helpers.py, location_lookupc.py (disk cache)
• Error Handlers & Config
c. Data Store
• Local file system cache for geocoding lookups
d. External Services
• Grocer APIs (Presidents Choice, Safeway, SaveOnFoods, Walmart)
• (Optional) Geocoding API for postal → lat/long if not fully self-contained
e. Deployment
• Railway / Heroku via Procfile, railway.json
Relationships & Interactions
1. Browser → Flask Controller (HTTP GET search)
2. Controller → Service Layer
3. Service Layer → Parallel calls to each Grocer API
4. Service Layer → Local cache read/write (postal→coordinates)
5. Grocer API responses → product_data_parser → aggregated result
6. Controller → Template Renderer → HTML + inlined JSON
7. Browser JS consumes JSON, sorts/displays results
• Error path: errors bubbled to error_handlers.py
Architectural Patterns & Principles
• MVC: clear separation of concerns between routing (Controller), business logic (Model/Service), and presentation (View)
• Parallelism: asynchronous or threaded requests to external APIs for speed
• Caching: disk-based caching of postal code lookups to reduce external calls
• Modular design: each grocer integration lives in its own wrapper (supermarket.py)
Essential Elements
• Labels: component names, ports/endpoints (e.g., /search)
• Notes on caching strategy & error handling middleware