A sophisticated inventory management simulation game with real-time analytics, decision support system, and economic order quantity (EOQ) calculations.
Stock Management Game is an educational business simulation where you manage inventory, unlock new products, respond to market events, and optimize your supply chain to maximize profits.
- 🏪 13 Products: 3 starter items + 10 unlockable products across 4 categories
- 📊 Real-time Analytics: Budget evolution, stock levels, and performance metrics
- 🎲 Random Events: Market dynamics including demand spikes, supplier discounts, and spoilage
- 🎯 Decision Support System (DSS): AI-powered recommendations for optimal restocking
- 📈 Economic Order Quantity (EOQ): Industry-standard inventory optimization
- 🏆 Game Over Conditions: Bankruptcy (-$100) or supply failure (3+ stockouts for 3 days)
- 📋 Comprehensive Reports: Daily financial summaries with export functionality
DSS_project/
├── backend/
│ ├── app.py # Flask API server
│ ├── game.py # StockGame class with full logic
│ ├── game_data.py # Product catalog and event definitions
│ └── inventory_optimization.py # EOQ calculations
├── frontend/
│ ├── game.html # Main game interface
│ ├── game-style.css # Complete styling (1000+ lines)
│ └── game-script.js # Game logic and API integration (700+ lines)
├── venv/ # Python virtual environment
├── README.md # This file
├── requirements.txt # Python dependencies
├── start_game.bat # Windows launch script
└── start_game.sh # Linux/Mac launch script
- Python 3.8+ installed
- Modern web browser (Chrome, Firefox, Edge, Safari)
- Internet connection (for Chart.js CDN)
cd C:\Users\djell\OneDrive\سطح المكتب\DSS_projectWindows:
python -m venv venvLinux/Mac:
python3 -m venv venvWindows:
.\venv\Scripts\activate
pip install -r requirements.txtLinux/Mac:
source venv/bin/activate
pip install -r requirements.txtSimply double-click start_game.bat or run:
.\start_game.batMake it executable first:
chmod +x start_game.sh
./start_game.shThe script will:
- ✅ Activate the virtual environment
- ✅ Start the Flask backend server
- ✅ Open the game in your default browser
- ✅ Keep the server running
Open a terminal/PowerShell in the project directory:
Windows:
.\venv\Scripts\activate
python backend\app.pyLinux/Mac:
source venv/bin/activate
python backend/app.pyYou should see:
* Running on http://127.0.0.1:5000
* Running on http://192.168.X.X:5000
Keep this terminal open! The server must stay running.
Option A: Double-click frontend/game.html in File Explorer
Option B: Run in terminal:
# Windows
start frontend/game.html
# Linux
xdg-open frontend/game.html
# Mac
open frontend/game.html- Click "🎮 New Game" in the header
- You'll start with a random budget between $120-$300
- 3 starter products are in your inventory:
- Office Chair
- Desk Lamp
- Water Bottle
- View all unlocked products
- See stock levels, demand, and costs
- Restock products using the Buy buttons
- Monitor Reorder Points and EOQ recommendations
- Track days of stock remaining
- Browse 10 unlockable products in 4 categories:
- 📱 Electronics (Smartphone, Laptop, Headphones)
- 🍔 Food & Beverage (Energy Drink, Snack Box, Coffee)
- 📝 Office Supplies (Notebook Set, Pen Pack)
- 🎁 Premium (Designer Watch, Gaming Console)
- Filter by category using the dropdown
- Unlock products when you have enough budget
- Best to Restock: Priority recommendations
- Highest Profit: Top revenue-generating products
- Cost Breakdown: Storage, restock, and unlock costs
- High-Risk Items: Products with critical stock levels
- High Storage Cost: Optimize expensive items
- Performance Metrics: ROI, profit margin, revenue, net profit
- Budget Evolution: Track your financial performance over time
- Stock Levels: Monitor inventory trends for all products
- Statistics: Budget trend, stock health, peak performance day
- Financial summary (revenue, costs, net change)
- Sales breakdown by product
- Active alerts and recommendations
- Export to CSV for external analysis
- Review Alerts - Check the 🔔 notification icon
- Restock Low Items - Buy inventory before stockouts
- Unlock New Products - Expand your catalog when profitable
- Click "⏭️ Next Day" - Advance to the next day
- 📈 Demand Spike (+20% demand)
- 💰 Supplier Discount (-10-20% restock costs)
⚠️ Spoilage (5-15% stock loss on random product)- 😴 Calm Day (-20% demand)
- 🎯 Maintain stock above Reorder Points
- 💡 Use EOQ recommendations for optimal order sizes
- 💰 Take advantage of Supplier Discount events
- 🏪 Unlock high-profit items early
- 📊 Monitor DSS Panel for insights
- 💵 Keep a budget buffer for emergencies
❌ Bankruptcy: Budget falls to -$100 or lower ❌ Supply Failure: 3+ products out of stock for 3 consecutive days
Progressive warnings will alert you before game over!
The Flask backend provides these RESTful endpoints:
| Endpoint | Method | Description |
|---|---|---|
/start_game |
GET | Create new game instance |
/next_day |
POST | Advance to next day |
/restock |
POST | Purchase inventory |
/unlock_item |
POST | Unlock store product |
/get_state |
GET | Get current game state |
/get_daily_report |
GET | Get last day's summary |
/health |
GET | API health check |
| Endpoint | Method | Description |
|---|---|---|
/recommend |
POST | Get EOQ recommendations |
/simulate |
POST | Run scenario analysis |
EOQ = √((2 × Annual Demand × Restock Cost) / Storage Cost per Unit)
ROP = Daily Demand × Lead Time
Lead Time = 3 days (default)
Days Left = Current Stock ÷ Daily Demand
ROI = ((Current Budget - Initial Budget) / Initial Budget) × 100%
Profit Margin = (Net Profit / Total Revenue) × 100%
Solution:
pip install -r requirements.txtSolution:
- Check if port 5000 is already in use
- Try changing the port in
backend/app.py:app.run(debug=True, port=5001)
Solution:
- Ensure backend is running (check terminal)
- Check browser console for errors (F12)
- Verify you're opening
game.htmlnotindex.html
Solution:
- Check internet connection (Chart.js loads from CDN)
- Open browser developer console (F12) to check for errors
Solution:
- Restart the backend server to ensure latest code is loaded
- Clear browser cache (Ctrl + Shift + Del)
- Python 3.8+
- Flask 3.0 - Web framework
- Flask-CORS - Cross-origin resource sharing
- Dataclasses - Type-safe data structures
- HTML5 - Semantic structure
- CSS3 - Modern styling with animations
- Vanilla JavaScript - No frameworks
- Chart.js 4.4 - Data visualization
- Fetch API - Asynchronous requests
- 13 Total Products (3 base + 10 unlockable)
- 4 Product Categories
- 4 Daily Event Types
- 6 DSS Analysis Panels
- 2 Interactive Charts
- 5 Main Game Tabs
- Multiple Game Over Conditions
This is an educational project. Feel free to:
- Add new products in
backend/game_data.py - Create new event types
- Enhance the UI/UX
- Add new DSS analysis panels
- Improve formulas and calculations
This project is created for educational purposes.
Created as part of a Decision Support Systems (DSS) course project.
This game teaches:
- Inventory management principles
- Economic Order Quantity (EOQ) theory
- Supply chain optimization
- Financial decision-making
- Risk management
- Data-driven analytics
If you encounter issues:
- Check this README thoroughly
- Review the troubleshooting section
- Check browser console for errors (F12)
- Verify backend terminal for error messages
Enjoy managing your virtual inventory empire! Remember: the key to success is balancing costs, avoiding stockouts, and making data-driven decisions.
Good luck, and may your profits soar! 📈💰
Last Updated: November 14, 2025 Version: 3.0 Status: Production Ready ✅