Xin Yi WMS® - Intelligent Food Warehouse Management 🥗

AI-powered warehouse management system designed for fresh food logistics with FEFO (First Expired, First Out) intelligence

A comprehensive warehouse management platform built for HeySalad's fresh food operations, featuring real-time inventory tracking, expiration management, and AI-driven insights.

✨ Key Features

📊 Real-Time Dashboard

Live inventory statistics and KPIs
7-day trend analysis with interactive charts
Category distribution visualization
Top 10 stock items tracking
Auto-refresh every 30 seconds

⏰ FEFO Intelligence

First Expired, First Out logic for stock-out operations
Expiration alerts (configurable threshold)
Lot-based inventory tracking
Spoilage rate monitoring
Temperature breach logging

🔍 Product Management

Detailed product views with images
Transaction history tracking
Real-time stock levels
Safety stock monitoring
Multi-language support (English | 中文)

🤖 AI Integration

Multi-provider AI chat (OpenAI, Anthropic, Gemini, DeepSeek)
Natural language inventory queries
Recipe suggestions for expiring ingredients
Automated reporting

💳 Payment & Communication

Stripe payment processing
SendGrid email notifications
Twilio SMS alerts
Webhook handling

📱 Screenshots

Dashboard	Product Details	Inventory List	FEFO Alerts

Real-time warehouse management with beautiful, intuitive interface

🛠 Technical Stack

Backend

Framework: Flask 3.1+ with modular blueprints
Database: Supabase (PostgreSQL) with real-time subscriptions
API: RESTful endpoints with CORS support
Authentication: JWT tokens with role-based access
Deployment: Raspberry Pi + Cloudflare Tunnel

Frontend

Core: Vanilla JavaScript (ES6+)
Charts: ECharts 5.4+ for data visualization
Styling: Custom CSS with HeySalad® branding
Deployment: Cloudflare Pages with CI/CD
Domain: xinyi.heysalad.app

Architecture

Frontend (Cloudflare Pages)
    ↓ HTTPS
Backend API (wms.heysalad.app)
    ↓ PostgreSQL
Database (Supabase)

🚀 Quick Start

Prerequisites

Python 3.12+
uv package manager
Supabase account
Node.js 18+ (for frontend deployment)

Installation

# Clone repository
git clone https://github.com/Hey-Salad/Xin-Yi.git
cd Xin-Yi

# Install dependencies
uv sync

# Configure environment
cp .env.example .env
# Edit .env with your credentials

# Initialize database
# Run the SQL migrations in backend/migrations/

# Start backend
uv run python backend/app_platform.py

# Start frontend (in new terminal)
cd frontend
python3 server.py

Access

Frontend: http://localhost:2125
Backend API: http://localhost:2124
API Docs: http://localhost:2124/

🌐 API Endpoints

Dashboard

GET /api/wms/dashboard/stats          # Dashboard statistics
GET /api/wms/dashboard/category-distribution  # Category pie chart
GET /api/wms/dashboard/weekly-trend   # 7-day trend data
GET /api/wms/dashboard/top-stock      # Top 10 items

Inventory Management

GET  /api/wms/materials/all           # All inventory items
GET  /api/wms/materials/info?name=X   # Single product details
GET  /api/wms/materials/product-stats?name=X  # Product statistics
GET  /api/wms/materials/product-trend?name=X  # 7-day trend
GET  /api/wms/materials/product-records?name=X # Transaction history
POST /api/wms/stock/in                # Stock-in operation
POST /api/wms/stock/out               # Stock-out (FEFO)

FEFO & Alerts

GET /api/wms/fefo-alerts?hours=48     # Expiring items
GET /api/wms/spoilage-rate?days=30    # Waste statistics

AI Services

POST /api/ai/chat                     # Multi-provider AI chat
POST /api/ai/image/generate           # Image generation
GET  /api/ai/providers                # Available AI providers

📊 Database Schema

Materials Table

CREATE TABLE materials (
    id UUID PRIMARY KEY,
    name TEXT NOT NULL,
    sku TEXT UNIQUE NOT NULL,
    category TEXT NOT NULL,
    quantity INTEGER DEFAULT 0,
    unit TEXT DEFAULT 'unit',
    safe_stock INTEGER DEFAULT 20,
    location TEXT,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

Inventory Lots Table (FEFO Tracking)

CREATE TABLE inventory_lots (
    id UUID PRIMARY KEY,
    material_id UUID REFERENCES materials(id),
    lot_number TEXT NOT NULL,
    expiration_date DATE NOT NULL,
    quantity INTEGER NOT NULL,
    catch_weight DECIMAL(10,2),
    status TEXT DEFAULT 'active',
    received_at TIMESTAMPTZ DEFAULT NOW()
);

Inventory Records Table

CREATE TABLE inventory_records (
    id UUID PRIMARY KEY,
    material_id UUID REFERENCES materials(id),
    type TEXT CHECK (type IN ('in', 'out')),
    quantity INTEGER NOT NULL,
    operator TEXT DEFAULT 'System',
    reason TEXT,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

🔧 Configuration

Environment Variables

# Database
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your-anon-key
SUPABASE_SERVICE_KEY=your-service-key

# Backend
BACKEND_PORT=2124
FRONTEND_PORT=2125
FLASK_ENV=production

# AI Providers (optional)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=...

# Payment (optional)
STRIPE_SECRET_KEY=sk_live_...
STRIPE_PUBLIC_KEY=pk_live_...

# Communication (optional)
SENDGRID_API_KEY=SG....
TWILIO_ACCOUNT_SID=AC...
TWILIO_AUTH_TOKEN=...

🚢 Deployment

Frontend (Cloudflare Pages)

# Install Wrangler
npm install -g wrangler

# Login
wrangler login

# Deploy
./deploy-to-cloudflare.sh

Or use CI/CD:

Add GitHub secrets: CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID
Push to main branch
Automatic deployment via GitHub Actions

Backend (Raspberry Pi + Cloudflare Tunnel)

# On Raspberry Pi
cd ~/Xin-Yi
git pull origin main

# Set up systemd service
sudo cp scripts/heysalad-backend.service /etc/systemd/system/
sudo systemctl enable heysalad-backend
sudo systemctl start heysalad-backend

# Configure Cloudflare Tunnel
cloudflared tunnel create xinyi-wms
cloudflared tunnel route dns xinyi-wms wms.heysalad.app
cloudflared tunnel run xinyi-wms

🧪 Testing

# Run all tests
./test/run_all_tests.sh

# Test specific components
python3 test/test_api.py          # API endpoints
python3 test/test_mcp.py           # MCP integration
python3 test/test_fefo.py          # FEFO logic

# Test platform
./test_platform.sh

🤝 Contributing

We welcome contributions! Here's how:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Guidelines

Follow PEP 8 for Python code
Use TypeScript for new frontend features
Add tests for new functionality
Update documentation
Maintain bilingual support (EN | 中文)

Get Help with Claude AI

Install the GitHub App: Run /install-github-app to add Claude to this repository for automated code reviews and PR assistance!

Once installed, tag @claude in issues and PRs for AI assistance!

📚 Documentation

API Documentation - Complete API reference
Deployment Guide - Production deployment
Frontend Guide - Frontend development
Code Walkthrough - Architecture deep dive
Testing Guide - Testing procedures
Cloudflare Setup - CI/CD configuration

🎯 Roadmap

Phase 1: Core Features ✅

Real-time dashboard
Inventory management
Product detail views
Multi-language support

Phase 2: FEFO Intelligence 🚧

Phase 3: AI Integration 🔜

Natural language queries
Recipe suggestions
Demand forecasting
Automated reordering

Phase 4: Mobile App 📱

React Native app
Barcode scanning
Offline mode
Push notifications

⚖️ License

This project is licensed under the MIT License - see the LICENSE file for details.

HeySalad® (UK Trademark Registration No. UK00004063403) is a registered trademark of SALADHR TECHNOLOGY LTD.

🙏 Acknowledgments

Supabase for excellent PostgreSQL hosting and real-time features
Cloudflare for global CDN and Pages deployment
ECharts for beautiful data visualization
Open Source Community for countless libraries and inspiration

📞 Contact & Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Email: peter@heysalad.io
Website: heysalad.io

☕ Support Us

If you find Xin Yi WMS useful, consider supporting HeySalad!

⚠️ Disclaimer

This software is provided "as is" without warranties. Always test thoroughly before using in production environments. For food safety compliance, consult with regulatory experts in your jurisdiction.

Built with ❤️ by HeySalad

Making food logistics smarter, one warehouse at a time

⭐ Star this repo • 🐛 Report Issues • 💬 Discussions

Let's make every meal count! 🌱✨

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.github/workflows		.github/workflows
backend		backend
frontend-next		frontend-next
frontend		frontend
heysalad_xiao_og		heysalad_xiao_og
mcp		mcp
scripts		scripts
sensecap_watcher_xinyi		sensecap_watcher_xinyi
test		test
.env.example		.env.example
.gitignore		.gitignore
.python-version		.python-version
BILINGUAL_TRANSLATION_COMPLETE.md		BILINGUAL_TRANSLATION_COMPLETE.md
CLAUDE_DESKTOP_CONFIG.md		CLAUDE_DESKTOP_CONFIG.md
CLOUDFLARE_DEPLOYMENT.md		CLOUDFLARE_DEPLOYMENT.md
CLOUDFLARE_PAGES_SETUP.md		CLOUDFLARE_PAGES_SETUP.md
CODE_WALKTHROUGH.md		CODE_WALKTHROUGH.md
COMPLETE_LAURA_INTEGRATION.md		COMPLETE_LAURA_INTEGRATION.md
DEPLOYMENT_FIX.md		DEPLOYMENT_FIX.md
DEPLOYMENT_GUIDE.md		DEPLOYMENT_GUIDE.md
DEVELOPMENT_PROMPTS.md		DEVELOPMENT_PROMPTS.md
DOCUMENT_GENERATION_SUMMARY.md		DOCUMENT_GENERATION_SUMMARY.md
FINAL_UPDATES_SUMMARY.md		FINAL_UPDATES_SUMMARY.md
FRONTEND_GUIDE.md		FRONTEND_GUIDE.md
FRONTEND_LOADING_FIX.md		FRONTEND_LOADING_FIX.md
FRONTEND_UPDATES_SUMMARY.md		FRONTEND_UPDATES_SUMMARY.md
GET_CLOUDFLARE_CREDENTIALS.md		GET_CLOUDFLARE_CREDENTIALS.md
GITHUB_PREP.md		GITHUB_PREP.md
HARDWARE_ANALYSIS.md		HARDWARE_ANALYSIS.md
IMPLEMENTATION_SUMMARY.md		IMPLEMENTATION_SUMMARY.md
LAURA_DASHBOARD_GUIDE.md		LAURA_DASHBOARD_GUIDE.md
LICENSE		LICENSE
NEXT_STEPS.md		NEXT_STEPS.md
PROFESSIONAL_DOCUMENTS_SUMMARY.md		PROFESSIONAL_DOCUMENTS_SUMMARY.md
README.md		README.md
README_DEVICES.md		README_DEVICES.md
README_EN.md		README_EN.md
README_PLATFORM.md		README_PLATFORM.md
RECAMERA_TROUBLESHOOTING_SUMMARY.md		RECAMERA_TROUBLESHOOTING_SUMMARY.md
RPI_TESTING_GUIDE.md		RPI_TESTING_GUIDE.md
SENSECAP_SETUP.md		SENSECAP_SETUP.md
SIGNATURE_INTEGRATION.md		SIGNATURE_INTEGRATION.md
TEST_IMAGES.md		TEST_IMAGES.md
WMS_DEPLOYMENT.md		WMS_DEPLOYMENT.md
WMS_DOCUMENTS_GUIDE.md		WMS_DOCUMENTS_GUIDE.md
check_recamera.sh		check_recamera.sh
deploy-to-cloudflare.sh		deploy-to-cloudflare.sh
main.py		main.py
pyproject.toml		pyproject.toml
recamera_auto_configure.py		recamera_auto_configure.py
recamera_usb_gadget_fix.md		recamera_usb_gadget_fix.md
run_backend.py		run_backend.py
sensecap_quickstart.sh		sensecap_quickstart.sh
start.sh		start.sh
start_frontend.sh		start_frontend.sh
test_doc_gen.py		test_doc_gen.py
test_documents.py		test_documents.py
test_logo_alignment.pdf		test_logo_alignment.pdf
test_platform.sh		test_platform.sh
test_stock_status.pdf		test_stock_status.pdf
verify_before_push.sh		verify_before_push.sh
wrangler.toml		wrangler.toml
仓管 prompt 记录.md		仓管 prompt 记录.md

Uh oh!

Folders and files

Latest commit

History

Repository files navigation