FreshGuard

FreshGuard is a smart inventory and waste-reduction platform with a Flask backend, a React frontend, and data-driven features for cart management, expiry awareness, loyalty rewards, and environmental impact tracking.

What it does

FreshGuard connects live inventory data to a shopper-facing experience that can surface near-expiry items, suggest alternatives, apply dynamic pricing logic, track loyalty points, and report savings and impact. The frontend also includes an admin area and built-in test routes for validating API behavior during development.

Key features

• Smart inventory browsing with grouping and filtering
• Cart workflows with add, remove, clear, checkout, and replacement handling
• Expiry alerts and freshness-aware product logic
• Loyalty and redeemable rewards flows
• Environmental impact and waste reduction tracking
• Shelf-life prediction and supporting ML utilities
• Admin pages for operations and oversight

Project layout

• backend/api/app.py is the main Flask application.
• backend/api/loyalty_routes.py contains the loyalty blueprint.
• backend/scripts/ holds CLI helpers and data utilities.
• backend/models/ stores training code and serialized model artifacts.
• frontend/src/App.js defines the React routes and app shell.
• frontend/src/pages/ contains the main user-facing screens.
• frontend/src/components/ contains shared UI components.
• docs/ contains product and implementation documentation.

Requirements

• Python 3.10+ recommended
• Node.js 18+ recommended
• npm

Setup

Backend

cd backend
python -m pip install -r requirements.txt
python api/app.py

The API runs on port 5000 by default.

Frontend

cd frontend
npm install
npm start

The frontend runs on port 3000 and proxies API requests to http://localhost:5000 by default.

Environment configuration

• Set REACT_APP_API_URL if you want the frontend to talk to a different backend URL.
• Keep the backend and frontend running in separate terminals during local development.

Verification

curl http://localhost:5000/health
python verify_discount_system.py
python verify_discount_display.py
python update_impact_demo.py

If you want the full end-to-end flow, run the app in both terminals and walk through inventory, cart, checkout, loyalty, and alerts from the UI.

Documentation

• docs/api_reference.md
• docs/data_schema.md
• docs/implementation.markdown
• docs/workflow.markdown

Troubleshooting

• If the backend fails to start, confirm the Python environment matches backend/requirements.txt and that port 5000 is free.
• If the frontend cannot reach the API, confirm the backend is running and REACT_APP_API_URL is correct.
• If a page looks stale, restart npm start after changing environment variables.

If you want, I can also turn this into a more polished product README with badges, screenshots, and a short architecture section.