🔍 ShrinkWatch

A Node.js web application to track shrinkflation, price changes, and nutrition modifications in consumer products.

Features

• Product Management: Enter or select product name, package size, form factor, flavor, and price
• Image Upload: Upload photos of nutrition facts, products, and packaging (5MB limit per image)
• AI-Powered Parsing: Use Azure Computer Vision AI to automatically extract nutrition information from images
• Version Control: Automatically detect changes and save new versions when nutrition, size, or price differs
• Analytics Dashboard: Track price changes, size reductions (shrinkflation), and nutrition modifications
• Product Search: Easily find and filter products
• MongoDB Support: Works with MongoDB or Azure Cosmos DB (MongoDB API)
• Dark Mode: Automatic dark mode support based on device preference
• Containerized: Ready to deploy with Docker

Tech Stack

• Backend: Node.js, Express.js
• Frontend: Preact, Vite
• Database: MongoDB / Azure Cosmos DB
• AI: Azure Computer Vision API (OCR)
• Styling: CSS with dark mode support
• File Upload: Multer 2.x
• Deployment: Docker & Docker Compose

Quick Start with Docker

The easiest way to run ShrinkWatch is using Docker:

# Clone the repository
git clone https://github.com/zeroClearAmerican/shrinkwatch.git
cd shrinkwatch

# Start the application with Docker Compose
docker-compose up -d

# Access the application
# Open http://localhost:3000 in your browser

This will start both the application and MongoDB automatically.

To stop the application:

docker-compose down

Manual Installation

Prerequisites

• Node.js (v20 or higher)
• MongoDB (local installation or MongoDB Atlas account)
• Azure Computer Vision API key (optional, for AI parsing)

Installation Steps

1. Clone the repository

git clone https://github.com/zeroClearAmerican/shrinkwatch.git
cd shrinkwatch

2. Install dependencies

npm install

3. Configure environment variables

Copy the example environment file:

cp .env.example .env

Edit .env and configure:

# Server Configuration
PORT=3000

# MongoDB Configuration
# For local MongoDB:
MONGODB_URI=mongodb://localhost:27017/shrinkwatch

# For MongoDB Atlas:
# MONGODB_URI=mongodb+srv://<username>:<password>@cluster.mongodb.net/shrinkwatch

# For Azure Cosmos DB with MongoDB API:
# MONGODB_URI=mongodb://<account-name>:<password>@<account-name>.mongo.cosmos.azure.com:10255/?ssl=true&replicaSet=globaldb&retrywrites=false&maxIdleTimeMS=120000

# Azure AI Vision Configuration (Optional - for OCR nutrition parsing)
AZURE_VISION_ENDPOINT=https://your-resource.cognitiveservices.azure.com/
AZURE_VISION_KEY=your-api-key-here

# File Upload Configuration
MAX_FILE_SIZE=5242880

4. Set up MongoDB

Option A: Local MongoDB

• Install MongoDB Community Edition
• Start MongoDB service: mongod

Option B: MongoDB Atlas (Cloud)

• Create a free account at MongoDB Atlas
• Create a cluster and get the connection string
• Update MONGODB_URI in .env

Option C: Azure Cosmos DB

• Create a Cosmos DB account with MongoDB API
• Get the connection string from Azure Portal
• Update MONGODB_URI in .env

5. Set up Azure Computer Vision (Optional)

If you want AI-powered nutrition parsing:

• Create an Azure account at Azure Portal
• Create a Computer Vision resource
• Copy the endpoint and API key to .env

Note: The app will work without Azure Vision using mock OCR results for testing.

Running the Application

Development Mode

For development, you'll need to run both the backend server and the Vite dev server:

Terminal 1 - Backend API Server:

npm run dev

Terminal 2 - Vite Frontend Dev Server:

npm run dev:vite

Then open http://localhost:5173 in your browser (Vite dev server with HMR).

Production Mode

Build the frontend and run the backend:

npm run build
npm start

The application will be available at http://localhost:3000

Deployment with Docker

Building and Running

Build the Docker image:

docker build -t shrinkwatch .

Run the container:

docker run -d -p 3000:3000 \
  -e MONGODB_URI=mongodb://your-mongo-host:27017/shrinkwatch \
  -v $(pwd)/public/img:/app/public/img \
  shrinkwatch

Using Docker Compose (Recommended)

Docker Compose will start both the app and MongoDB:

# Start services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

# Stop and remove volumes
docker-compose down -v

Deployment Behind Cloudflare

The containerized app can be directly exposed to web traffic behind Cloudflare:

1. Configure your Cloudflare DNS to point to your server
2. Set up Cloudflare SSL/TLS (Flexible or Full)
3. Enable Cloudflare features (DDoS protection, WAF, caching)
4. Run the container on port 3000 (or configure as needed)
5. Cloudflare will handle SSL termination and security

The app includes rate limiting and security best practices for production use.

Architecture

Frontend (Preact + Vite)

The frontend is built with Preact for a lightweight, performant user experience:

• Component-Based: Modular Preact components for each feature
• State Management: React hooks (useState, useEffect) for component state
• Fast Refresh: Vite HMR for instant updates during development
• Optimized Build: Vite produces highly optimized production bundles
• Dark Mode: CSS custom properties with prefers-color-scheme support

Component Structure:

src/
├── components/
│   ├── App.jsx              # Main app container
│   ├── Header.jsx           # Header with branding
│   ├── TabNavigation.jsx    # Tab switching interface
│   ├── AddProductForm.jsx   # Product entry form
│   ├── ViewProducts.jsx     # Product listing and search
│   └── Analytics.jsx        # Analytics dashboard
└── main.jsx                 # App entry point

Backend (Express + MongoDB)

RESTful API server with:

• Express.js for routing and middleware
• MongoDB with Mongoose ODM for data persistence
• Rate limiting for API protection
• Multer for file upload handling
• Azure Computer Vision integration for OCR

The backend serves the compiled Vite build in production and provides API endpoints for all data operations.

Usage Guide

Adding a Product

1. Navigate to the "Add/Update Product" tab
2. Fill in product information (name, brand, category, etc.)
3. Upload a photo of the nutrition facts label
4. Optionally click "Preview AI Parsing" to see extracted nutrition data
5. Add additional product/packaging images if desired
6. Click "Submit Product"

Automatic Version Detection

The system automatically creates new versions when it detects:

• Changes in nutrition facts (calories, fat, sodium, etc.)
• Changes in package size
• Changes in price
• Changes in form factor or flavor

Viewing Products

• Click the "View Products" tab to see all tracked products
• Use the search box to filter products
• Products with multiple versions will show a warning indicator

Analytics Dashboard

The analytics tab provides insights:

• Overview: Total products, versions, and products with changes
• Price Changes: Products with price increases/decreases
• Size Changes: Products affected by shrinkflation
• Top Offenders: Products with the most detected changes

API Endpoints

Products

• GET /api/products - Get all products
• GET /api/products/:id - Get a specific product
• GET /api/products/:id/versions - Get all versions of a product
• POST /api/products - Create or update a product (with file upload)
• POST /api/products/parse-nutrition - Parse nutrition from image
• DELETE /api/products/:id - Delete a product
• GET /api/products/search/:query - Search products

Analytics

• GET /api/analytics/overview - Get overview statistics
• GET /api/analytics/price-changes - Get price change data
• GET /api/analytics/size-changes - Get size change data (shrinkflation)
• GET /api/analytics/nutrition-changes - Get nutrition change data
• GET /api/analytics/top-offenders - Get products with most changes

Project Structure

shrinkwatch/
├── models/
│   └── Product.js          # MongoDB schemas
├── routes/
│   ├── products.js         # Product API routes
│   └── analytics.js        # Analytics API routes
├── services/
│   └── nutritionParser.js  # AI nutrition parsing service
├── public/
│   ├── css/
│   │   └── style.css       # Styles
│   └── js/
│       └── app.js          # Frontend JavaScript
├── views/
│   └── index.ejs           # Main HTML template
├── uploads/                # Uploaded images
├── server.js               # Express server
├── package.json
└── .env                    # Environment variables

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

ISC

Support

For issues and questions, please open an issue on GitHub.