📦 StockMaster

Next-Generation Inventory Management System with Dynamic data

---

🎯 Transform Your Warehouse Operations

A powerful, real-time inventory management solution built for modern businesses. Replace manual registers and Excel sheets with a centralized, intelligent system that streamlines every stock operation.

Built for Odoo Hackathon Virtual Round 🏆

---

✨ Why StockMaster?

📊 Real-Time Tracking	🔄 Automated Workflows	👥 Multi-Role Support	⚡ Lightning Fast
Live stock updates across all warehouses	Automated receipt, delivery & transfer processing	Manager & Staff role-based access	Instant updates with Socket.IO
Multi-location inventory	Smart low-stock alerts	Task assignment & tracking	Optimized performance
Complete audit trail	Auto-calculated stock levels	Activity monitoring	Real-time notifications

---

🎯 Core Features

🏢 Comprehensive Inventory Management

📦 Product Management

• ➕ Smart Product Creation - SKU generation, categorization, and unit management
• 📍 Multi-Location Tracking - Track stock across multiple warehouses and locations
• 📊 Stock Availability - Real-time stock levels per location
• 🔄 Reordering Rules - Automated low-stock alerts and reorder suggestions
• 🔍 Advanced Search - SKU-based search with smart filters

📥 Receipt Operations (Incoming Stock)

• 📋 Supplier Management - Track vendors and purchase orders
• ✅ Quick Validation - Fast receipt processing with barcode support
• 📈 Auto Stock Updates - Automatic inventory adjustments
• 📝 Receipt History - Complete audit trail of all incoming goods
• 🔔 Real-time Notifications - Instant updates on new receipts

📤 Delivery Operations (Outgoing Stock)

• 🎯 Pick & Pack Workflow - Streamlined order fulfillment
• 📦 Batch Processing - Handle multiple deliveries efficiently
• 📉 Auto Deduction - Automatic stock reduction on validation
• 🚚 Delivery Tracking - Monitor outgoing shipments
• ✔️ Quality Checks - Built-in validation steps

🔄 Internal Transfers

• 🏭 Inter-Warehouse Moves - Transfer stock between locations
• 📍 Rack Management - Organize inventory by racks and zones
• 🔍 Movement Tracking - Complete visibility of stock movements
• ⚡ Instant Updates - Real-time location changes
• 📊 Transfer Reports - Detailed movement history

🔧 Stock Adjustments

• 📊 Physical Count - Easy stock counting interface
• 🔄 Auto Reconciliation - Automatic variance calculation
• 📝 Adjustment Logging - Complete audit trail
• 🔍 Discrepancy Reports - Identify and resolve mismatches
• 📈 Trend Analysis - Track adjustment patterns

👥 Role-Based Access Control

👨‍💼 Inventory Manager

• 📊 Comprehensive Dashboard - Real-time KPIs and metrics
• 👥 Staff Management - Assign and monitor warehouse staff
• 📈 Analytics & Reports - Detailed inventory insights
• ⚙️ System Configuration - Warehouse and location setup
• 🔍 Complete Visibility - Access to all operations

👷 Warehouse Staff

• 📋 Task Dashboard - Assigned tasks and priorities
• ⚡ Quick Actions - Fast receipt and picking workflows
• 📦 Stock Counting - Mobile-friendly counting interface
• 📊 Activity History - Personal work log
• 🔔 Task Notifications - Real-time task updates

📊 Advanced Analytics

🎯 Dashboard KPIs

• 📦 Total Products in Stock - Overall inventory value
• ⚠️ Low Stock Alerts - Items requiring attention
• 📥 Pending Receipts - Awaiting validation
• 📤 Pending Deliveries - Orders to fulfill
• 🔄 Scheduled Transfers - Upcoming movements

📈 Smart Filtering

• 📋 Document Type - Filter by receipts, deliveries, transfers, adjustments
• ✅ Status-Based - Draft, waiting, ready, done, canceled
• 🏢 Location Filter - By warehouse or specific location
• 📁 Category Filter - By product category
• 📅 Date Range - Time-based filtering

🔔 Real-Time Features

• ⚡ Live Updates - Socket.IO powered real-time synchronization
• 🔄 Instant Notifications - Push notifications for all operations
• 👥 Collaborative Workflows - Multiple users working simultaneously
• 📊 Live Dashboard - Auto-updating metrics and KPIs
• 🎯 Task Assignment - Real-time task distribution

---

🏗️ System Architecture

flowchart LR
  %% Layout LR for a wide, presentation-friendly diagram

  subgraph FRONTEND["Frontend Layer"]
    direction TB
    A[React 19 + TypeScript]
    B[Redux Toolkit]
    C[Tailwind CSS]
    D[Socket.IO Client]
  end

  subgraph BACKEND["Backend Layer"]
    direction TB
    E[Node.js + Express]
    F[Socket.IO Server]
    G[RESTful API]
    H[JWT Authentication]
  end

  subgraph DATA["Data Layer"]
    direction TB
    I[MongoDB Atlas]
    J[Mongoose ODM]
    K[Real-time Subscriptions]
  end

  subgraph SEC["Security & Performance"]
    direction LR
    L[Rate Limiting]
    M[Helmet Security]
    N[Compression]
    O[Error Handling]
  end

  %% Primary flow (left -> right)
  A -->|API calls| E
  B -.->|state -> api| G
  D -->|ws| F

  %% Backend -> data
  E -->|reads/writes| I
  G --> J
  F --> K

  %% Cross-cutting concerns
  H --> E
  L --> E
  M --> E
  N --> E
  O --> E

  %% Styling (GitHub-friendly)
  classDef frontend fill:#0ea5a4,stroke:#065f46,color:white,stroke-width:1px;
  classDef backend fill:#2563eb,stroke:#1e40af,color:white,stroke-width:1px;
  classDef data fill:#f59e0b,stroke:#92400e,color:black,stroke-width:1px;
  classDef security fill:#ef4444,stroke:#7f1d1d,color:white,stroke-width:1px;

  class A,B,C,D frontend;
  class E,F,G,H backend;
  class I,J,K data;
  class L,M,N,O security;

Loading

---

📁 Project Structure

📦 StockMaster/
├── 📋 README.md                      # You are here!
├── 📦 package.json                   # Root dependencies
├── 🚀 .gitignore                     # Git ignore rules
│
├── 🔙 Backend/                       # Node.js + Express API
│   ├── 📦 package.json              # Backend dependencies
│   ├── 🌍 .env                      # Environment variables
│   ├── 🚀 server.js                 # Express server entry
│   ├── ⚙️ config/
│   │   ├── 🗄️ database.js          # MongoDB connection
│   │   └── 🔑 jwt.js               # JWT configuration
│   ├── 🎛️ controllers/
│   │   ├── 🔐 authController.js
│   │   ├── 📦 productController.js
│   │   ├── 📥 receiptController.js
│   │   ├── 📤 deliveryController.js
│   │   ├── 🔄 transferController.js
│   │   ├── 🔧 adjustmentController.js
│   │   ├── 🏢 warehouseController.js
│   │   ├── 📊 dashboardController.js
│   │   └── 📝 historyController.js
│   ├── 📚 models/
│   │   ├── 👤 User.js
│   │   ├── 📦 Product.js
│   │   ├── 🏢 Warehouse.js
│   │   ├── 📥 Receipt.js
│   │   ├── 📤 Delivery.js
│   │   ├── 🔄 Transfer.js
│   │   ├── 🔧 Adjustment.js
│   │   └── 📝 StockHistory.js
│   ├── 🛣️ routes/
│   │   ├── 🔐 authRoutes.js
│   │   ├── 📦 productRoutes.js
│   │   ├── 📥 receiptRoutes.js
│   │   ├── 📤 deliveryRoutes.js
│   │   ├── 🔄 transferRoutes.js
│   │   ├── 🔧 adjustmentRoutes.js
│   │   ├── 🏢 warehouseRoutes.js
│   │   ├── 📊 dashboardRoutes.js
│   │   └── 📝 historyRoutes.js
│   ├── 🛡️ middlewares/
│   │   ├── 🔒 auth.js              # JWT verification
│   │   ├── 👮 roleCheck.js         # Role-based access
│   │   ├── ✅ validation.js        # Input validation
│   │   └── ⚠️ errorHandler.js     # Global error handler
│   └── 🔧 utils/
│       ├── 📧 notifications.js     # Socket.IO helpers
│       ├── 🔢 stockCalculator.js   # Stock calculations
│       └── 📊 logger.js            # Custom logger
│
└── 🎨 Frontend/                      # React + TypeScript SPA
    ├── 📦 package.json              # Frontend dependencies
    ├── 🌍 .env                      # Environment variables
    ├── ⚡ vite.config.ts            # Vite configuration
    ├── 🎯 tsconfig.json             # TypeScript config
    ├── 🎨 tailwind.config.js        # Tailwind CSS config
    ├── 🗂️ src/
    │   ├── 🚀 main.tsx              # Application entry
    │   ├── 📱 App.tsx               # Root component
    │   ├── 🎨 index.css             # Global styles
    │   ├── 🧩 components/
    │   │   ├── 🔐 Auth/
    │   │   │   ├── 🚪 LoginPage.tsx
    │   │   │   └── 📝 SignupPage.tsx
    │   │   ├── 🖼️ Layout/
    │   │   │   ├── 📐 Layout.tsx
    │   │   │   ├── 🔝 Header.tsx
    │   │   │   ├── 📊 Sidebar.tsx
    │   │   │   └── 🔔 Notifications.tsx
    │   │   ├── 🛡️ ProtectedRoute.tsx
    │   │   └── 🎨 ui/               # Reusable components
    │   ├── 📄 pages/
    │   │   ├── 📊 Dashboard.tsx
    │   │   ├── 🏢 WarehouseDashboard.tsx
    │   │   ├── 👥 StaffManagement.tsx
    │   │   ├── 📋 MyTasks.tsx
    │   │   ├── 📦 Products.tsx
    │   │   ├── 🔄 operations/
    │   │   │   ├── 📥 Receipts.tsx
    │   │   │   ├── 📤 Deliveries.tsx
    │   │   │   └── 🔧 Adjustments.tsx
    │   │   ├── 📝 MoveHistory.tsx
    │   │   ├── ⚙️ Settings.tsx
    │   │   ├── ⚡ QuickReceive.tsx  # Staff
    │   │   ├── 🎯 QuickPick.tsx     # Staff
    │   │   ├── 📊 StockCount.tsx    # Staff
    │   │   └── 📈 MyActivity.tsx    # Staff
    │   ├── 🔄 store/                # Redux Toolkit
    │   │   ├── 📦 index.ts
    │   │   └── 🗂️ slices/
    │   │       ├── 🔐 authSlice.ts
    │   │       ├── 📦 productSlice.ts
    │   │       ├── 📥 receiptSlice.ts
    │   │       ├── 📤 deliverySlice.ts
    │   │       ├── 🔄 transferSlice.ts
    │   │       ├── 🔧 adjustmentSlice.ts
    │   │       └── 🔔 notificationSlice.ts
    │   ├── 🔌 services/
    │   │   ├── 🌐 api.ts            # Axios configuration
    │   │   └── ⚡ socket.ts         # Socket.IO client
    │   ├── 🎣 hooks/
    │   │   ├── 🔐 useAuth.ts
    │   │   ├── ⚡ useSocket.ts
    │   │   └── 🔔 useNotifications.ts
    │   ├── 📝 types/
    │   │   └── 📋 index.ts          # TypeScript types
    │   └── 🔧 utils/
    │       ├── 📅 dateFormatter.ts
    │       ├── 💰 numberFormatter.ts
    │       └── ✅ validators.ts
    └── 🎯 public/
        ├── 🖼️ logo.svg
        └── 📱 favicon.ico

---

🚀 Quick Start Guide

📋 Prerequisites

Requirement	Version	Download
🟢 Node.js	18+	Download
📦 npm	Latest	Included with Node.js
🗄️ MongoDB	6.0+	MongoDB Atlas

⚡ Installation

# 1️⃣ Clone the repository
git clone https://github.com/yourusername/stockmaster.git
cd stockmaster

# 2️⃣ Install Backend Dependencies
cd Backend
npm install

# 3️⃣ Install Frontend Dependencies
cd ../Frontend
npm install

# 4️⃣ Set up Backend environment
cd ../Backend
cp .env.example .env
# Edit .env with your MongoDB URI and JWT secret

# 5️⃣ Set up Frontend environment
cd ../Frontend
cp .env.example .env
# Edit .env with your backend API URL

# 6️⃣ Start Backend Server
cd ../Backend
npm run dev

# 7️⃣ Start Frontend (in new terminal)
cd Frontend
npm run dev

🌍 Environment Configuration

Backend (.env)

# Server Configuration
PORT=5000
NODE_ENV=development
FRONTEND_URL=http://localhost:5173

# MongoDB Configuration
MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/stockmaster

# JWT Configuration
JWT_SECRET=your_super_secret_jwt_key_here
JWT_EXPIRE=7d

# Socket.IO
SOCKET_CORS_ORIGIN=http://localhost:5173

Frontend (.env)

# Backend API
VITE_API_URL=http://localhost:5000/api
VITE_SOCKET_URL=http://localhost:5000

# App Configuration
VITE_APP_NAME=StockMaster

🌐 Access Points

Service	URL	Description
🎨 Frontend	http://localhost:5173	Main application
🔙 Backend API	http://localhost:5000/api	REST API
🏥 Health Check	http://localhost:5000/api/health	Server status

---

🛠️ Technology Stack

🎨 Frontend Technologies

🔙 Backend Technologies

🔧 Development & Security

---

📚 API Documentation

🔐 Authentication

Method	Endpoint	Description	Auth Required
POST	/api/auth/signup	Register new user	❌
POST	/api/auth/login	User login	❌
GET	/api/auth/me	Get current user	✅
POST	/api/auth/logout	User logout	✅
POST	/api/auth/reset-password	OTP-based reset	❌

📦 Product Management

Method	Endpoint	Description	Auth Required
GET	/api/products	List all products	✅
POST	/api/products	Create product	✅
GET	/api/products/:id	Get product details	✅
PUT	/api/products/:id	Update product	✅
DELETE	/api/products/:id	Delete product	✅
GET	/api/products/:id/stock	Get stock by location	✅

📥 Receipt Operations

Method	Endpoint	Description	Auth Required
GET	/api/receipts	List all receipts	✅
POST	/api/receipts	Create receipt	✅
PUT	/api/receipts/:id	Update receipt	✅
POST	/api/receipts/:id/validate	Validate receipt	✅
DELETE	/api/receipts/:id	Cancel receipt	✅

📤 Delivery Operations

Method	Endpoint	Description	Auth Required
GET	/api/deliveries	List all deliveries	✅
POST	/api/deliveries	Create delivery	✅
PUT	/api/deliveries/:id	Update delivery	✅
POST	/api/deliveries/:id/validate	Validate delivery	✅
DELETE	/api/deliveries/:id	Cancel delivery	✅

🔄 Transfer Operations

Method	Endpoint	Description	Auth Required
GET	/api/transfers	List all transfers	✅
POST	/api/transfers	Create transfer	✅
PUT	/api/transfers/:id	Update transfer	✅
POST	/api/transfers/:id/validate	Validate transfer	✅

🔧 Adjustment Operations

Method	Endpoint	Description	Auth Required
GET	/api/adjustments	List all adjustments	✅
POST	/api/adjustments	Create adjustment	✅
POST	/api/adjustments/:id/validate	Validate adjustment	✅

📊 Dashboard & Reports

Method	Endpoint	Description	Auth Required
GET	/api/dashboard/kpis	Get dashboard KPIs	✅
GET	/api/dashboard/low-stock	Get low stock items	✅
GET	/api/history	Get stock movement history	✅
GET	/api/history/product/:id	Get product history	✅

---

🎮 Usage Guide

👨‍💼 For Inventory Managers

1. 📊 Monitor Dashboard

   • View real-time KPIs
   • Check low stock alerts
   • Monitor pending operations

2. 👥 Manage Staff

   • Assign warehouse staff
   • Monitor task completion
   • Track staff performance

3. 📦 Oversee Operations

   • Review all receipts, deliveries, transfers
   • Validate high-value transactions
   • Generate reports

👷 For Warehouse Staff

1. 📋 Check Tasks

   • View assigned tasks
   • Prioritize urgent items
   • Update task status

2. ⚡ Quick Operations

   • Fast receipt processing
   • Quick pick & pack
   • Stock counting

3. 📊 Track Activity

   • View personal work history
   • Monitor performance metrics

---

🔒 Security Features

Feature	Implementation	Benefit
🔑 JWT Authentication	Token-based auth with expiry	Secure session management
🛡️ Helmet Security	HTTP headers protection	Prevents common attacks
⏱️ Rate Limiting	100 requests/15min per IP	DDoS protection
🔐 Role-Based Access	Manager & Staff roles	Data isolation
📝 Audit Trail	Complete operation logging	Accountability
🔒 CORS Protection	Restricted origins	Cross-origin security

---

🚨 Troubleshooting

🔴 MongoDB Connection Failed

Problem: MongoNetworkError: failed to connect to server

Solutions:

1. Check MongoDB Atlas connection string
2. Verify IP whitelist in Atlas
3. Ensure network connectivity
4. Check username/password in URI

🔑 JWT Token Invalid

Problem: 401 Unauthorized or JsonWebTokenError

Solutions:

1. Verify JWT_SECRET in backend .env
2. Check token expiry
3. Clear browser localStorage
4. Re-login to get new token

⚡ Socket.IO Not Connecting

Problem: Real-time updates not working

Solutions:

1. Check CORS configuration
2. Verify Socket.IO URLs match
3. Check browser console for errors
4. Restart both servers

🎨 Frontend Build Errors

Problem: TypeScript or build errors

Solutions:

1. Delete node_modules and reinstall
2. Clear Vite cache: rm -rf node_modules/.vite
3. Check TypeScript version compatibility
4. Run npm run type-check

---

📈 Performance Optimizations

Feature	Technology	Impact
⚡ Real-time Updates	Socket.IO	Instant synchronization
🗜️ Response Compression	Express Compression	70% smaller payloads
🚀 Code Splitting	Vite + React.lazy	Faster initial load
📦 State Management	Redux Toolkit	Optimized re-renders
🔄 Connection Pooling	Mongoose	Efficient DB queries
🎯 Lazy Loading	React Suspense	On-demand components

---

🤝 Contributing

We welcome contributions! Here's how you can help:

1. 🍴 Fork the repository
2. 🌿 Create a feature branch: git checkout -b feature/amazing-feature
3. 💾 Commit your changes: git commit -m 'Add amazing feature'
4. 📤 Push to the branch: git push origin feature/amazing-feature
5. 🔄 Submit a Pull Request

📝 Contribution Guidelines

• Follow existing code style
• Write meaningful commit messages
• Add tests for new features
• Update documentation
• Keep PRs focused and small

---

📄 License

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

---

🏆 Built For

Odoo Hackathon - Virtual Round

Demonstrating next-generation inventory management capabilities

---

🙏 Acknowledgments

Special thanks to:

• 🚀 Odoo for the hackathon opportunity
• ⚛️ React Team for the amazing framework
• 🗄️ MongoDB for the powerful database
• ⚡ Socket.IO for real-time capabilities
• 🎨 Tailwind CSS for beautiful styling

---

💡 Built with ❤️ for Modern Warehouse Management

Transform your inventory operations today!

---

📞 Questions? Reach out!