# snacsnoc/grocery-app architecture

> Architecture diagram of the GitHub repository snacsnoc/grocery-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/snacsnoc/grocery-app
- Repository: https://github.com/snacsnoc/grocery-app

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend" 
        direction TB
        UI["Browser UI<br>(HTML Templates + JS)"]:::ui
    end

    %% Backend Layer
    subgraph "Flask App" 
        direction TB
        Controller["Flask Controller<br>(app.py, routes.py)"]:::internal
        Orchestrator["Service Layer Orchestrator<br>(services.py)"]:::internal
        Wrappers["Grocer API Wrappers<br>(supermarket.py)"]:::internal
        Parser["Data Parsing & Normalization<br>(product_data_parser.py)"]:::internal
        Helpers["General Helpers<br>(helpers.py)"]:::internal
        CacheUtil["Disk Cache Utility<br>(location_lookupc.py)"]:::internal
        ErrorHandler["Error Handling Middleware<br>(error_handlers.py)"]:::internal
        Config["Configuration<br>(config.py)"]:::internal
    end

    %% Data Store
    subgraph "Data Store"
        direction TB
        DiskCache[(Postal→Coordinates Cache)]:::data
    end

    %% External Services
    subgraph "External Grocer APIs"
        direction TB
        PC((Presidents Choice API)):::external
        SW((Safeway API)):::external
        SO((SaveOnFoods API)):::external
        WM((Walmart API)):::external
    end

    %% Deployment
    subgraph "Deployment"
        direction TB
        ProcfileFile["Procfile"]:::internal
        RailwayFile["railway.json"]:::internal
    end

    %% Connections
    UI -->|GET /search?q| Controller
    Controller -->|calls| Orchestrator
    Orchestrator -->|read/write| DiskCache
    Orchestrator -->|invoke wrapper| Wrappers
    Wrappers -->|HTTP JSON| PC
    Wrappers -->|HTTP JSON| SW
    Wrappers -->|HTTP JSON| SO
    Wrappers -->|HTTP JSON| WM
    PC -->|response JSON| Wrappers
    SW -->|response JSON| Wrappers
    SO -->|response JSON| Wrappers
    WM -->|response JSON| Wrappers
    Wrappers -->|raw data| Parser
    Parser -->|normalized data| Orchestrator
    Orchestrator -->|aggregated result| Controller
    Controller -->|render templates| UI
    UI -->|consume JSON via JS| UI
    Controller -->|errors| ErrorHandler

    Controller --> Config
    Controller --> Helpers
    Orchestrator --> Helpers
    Orchestrator --> CacheUtil

    ProcfileFile --> RailwayFile

    %% Click Events
    click UI "https://github.com/snacsnoc/grocery-app/tree/main/templates/"
    click UI "https://github.com/snacsnoc/grocery-app/tree/main/static/assets/bootstrap/css/"
    click UI "https://github.com/snacsnoc/grocery-app/blob/main/static/assets/js/bold-and-bright.js"
    click Controller "https://github.com/snacsnoc/grocery-app/blob/main/app.py"
    click Controller "https://github.com/snacsnoc/grocery-app/blob/main/routes.py"
    click Orchestrator "https://github.com/snacsnoc/grocery-app/blob/main/services.py"
    click Wrappers "https://github.com/snacsnoc/grocery-app/blob/main/supermarket.py"
    click Parser "https://github.com/snacsnoc/grocery-app/blob/main/product_data_parser.py"
    click Helpers "https://github.com/snacsnoc/grocery-app/blob/main/helpers.py"
    click CacheUtil "https://github.com/snacsnoc/grocery-app/blob/main/location_lookupc.py"
    click ErrorHandler "https://github.com/snacsnoc/grocery-app/blob/main/error_handlers.py"
    click Config "https://github.com/snacsnoc/grocery-app/blob/main/config.py"
    click ProcfileFile "https://github.com/snacsnoc/grocery-app/tree/main/Procfile"
    click RailwayFile "https://github.com/snacsnoc/grocery-app/blob/main/railway.json"

    %% Styles
    classDef ui fill:#FDEBD0,stroke:#E67E22,color:#000
    classDef internal fill:#D6EAF8,stroke:#3498DB,color:#000
    classDef data fill:#FCF3CF,stroke:#F1C40F,color:#000
    classDef external fill:#D5F5E3,stroke:#27AE60,color:#000
```
