🏪 SmartShelf - AI-Powered Warehouse Inventory Management System

A comprehensive warehouse management solution with real-time tracking, FEFO ordering, and demand forecasting

Features • Tech Stack • Installation • API Documentation • Contributors

📋 Table of Contents

About
Features
Tech Stack
System Architecture
Installation
Configuration
Usage
API Documentation
Project Structure
Screenshots
Contributors
License

🎯 About

SmartShelf is an intelligent warehouse inventory management system designed to optimize warehouse operations through automation, predictive analytics, and real-time monitoring. It addresses critical challenges in modern warehouse management including:

❌ Inventory discrepancies and manual errors
❌ Product expiry and waste management
❌ Inefficient task allocation
❌ Lack of predictive capabilities
❌ Limited real-time visibility

✨ Features

🔐 Authentication & Authorization

Secure JWT-based authentication
Role-based access control (Admin, Manager, Worker)
Password encryption using bcrypt
Session management

📦 Inventory Management

Real-time tracking of inventory items
CRUD operations with full data validation
Category-based filtering and search
Multi-field search (product name, SKU, supplier)
Inventory analytics with KPIs

📊 FEFO Ordering System

First Expired, First Out algorithm implementation
Automatic prioritization based on expiry dates
Urgency levels: Critical (≤3 days), High (≤7 days), Medium (≤14 days), Low (>14 days)
Visual indicators for quick identification

📈 Demand Forecasting

7-day demand projections based on historical data
Daily consumption rate calculations
Trend indicators: Stable, Normal, Critical
Product-wise forecast visualization
Interactive forecast graphs

🔔 Alert System

Real-time notifications for critical events
Live alert feed with human-readable messages
Alert categories:
- 🔴 Expired items
- 🟠 Expiring soon (within 7 days)
- 🟡 Low stock (below threshold)
- ⚫ Out of stock

✅ Task Management

Task creation and assignment to workers
Status tracking: Pending → In Progress → Completed
Real-time task updates
Task completion analytics
Worker-specific task views

📱 Dashboard Analytics

Admin Dashboard: System-wide overview and user management
Manager Dashboard: Live alerts, forecasting, FEFO ordering, top products
Worker Dashboard: Assigned tasks with quick status updates
Responsive design with dark mode support

🎨 User Interface

Modern, intuitive interface built with React + TypeScript
Tailwind CSS for responsive design
Dark mode support
Mobile-friendly layouts
Smooth animations and transitions

🛠️ Tech Stack

Frontend

React 18 - UI library with hooks
TypeScript - Type safety
Tailwind CSS - Utility-first styling
Vite - Fast build tool
React Context API - State management

Backend

Node.js - Runtime environment
Express.js - Web framework
MongoDB - NoSQL database
Mongoose - ODM for MongoDB
JWT - Authentication
bcrypt - Password hashing

Development Tools

Git - Version control
VS Code - Code editor
Postman - API testing
MongoDB Compass - Database management

🏗️ System Architecture

┌─────────────────────────────────────────────────────────────┐
│                        CLIENT TIER                          │
│  ┌─────────────────────────────────────────────────────┐   │
│  │         React + TypeScript Frontend (SPA)          │   │
│  │  • Component-based architecture                     │   │
│  │  • React Context for state management              │   │
│  │  • Tailwind CSS for styling                        │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                           ↕ HTTP/HTTPS
┌─────────────────────────────────────────────────────────────┐
│                     APPLICATION TIER                        │
│  ┌─────────────────────────────────────────────────────┐   │
│  │        Node.js + Express.js Backend (API)          │   │
│  │  • RESTful API endpoints                           │   │
│  │  • JWT authentication middleware                   │   │
│  │  • Role-based authorization                        │   │
│  │  • Business logic & algorithms                     │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                           ↕ Mongoose ODM
┌─────────────────────────────────────────────────────────────┐
│                         DATA TIER                           │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              MongoDB Database (NoSQL)              │   │
│  │  • Collections: Users, Inventory, Tasks            │   │
│  │  • Indexes for query optimization                  │   │
│  │  • Document-based storage                          │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

🚀 Installation

Prerequisites

Ensure you have the following installed:

Node.js (v18 or higher) - Download
MongoDB (v6 or higher) - Download
Git - Download
npm or yarn package manager

Clone Repository

git clone https://github.com/namish18/SmartShelf.git
cd SmartShelf

Backend Setup

# Navigate to backend directory
cd backend

# Install dependencies
npm install

# Create .env file
cp .env.example .env

# Edit .env with your configuration
# Add MongoDB connection string and JWT secret

# Start development server
npm run dev

Frontend Setup

# Navigate to frontend directory (from root)
cd ../frontend

# Install dependencies
npm install

# Create .env file
cp .env.example .env

# Edit .env with backend API URL

# Start development server
npm run dev

The application will be available at:

Frontend: http://localhost:5173
Backend: http://localhost:5000

⚙️ Configuration

Backend Environment Variables

Create a .env file in the backend directory:

# Server Configuration
PORT=5000
NODE_ENV=development

# Database Configuration
MONGODB_URI=mongodb://localhost:27017/smartshelf
# Or use MongoDB Atlas:
# MONGODB_URI=mongodb+srv://username:[email protected]/smartshelf

# JWT Configuration
JWT_SECRET=your_super_secret_jwt_key_here_minimum_32_characters
JWT_EXPIRE=24h

# CORS Configuration
ALLOWED_ORIGINS=http://localhost:5173,http://localhost:3000

Frontend Environment Variables

Create a .env file in the frontend directory:

# API Configuration
VITE_API_URL=http://localhost:5000/api

MongoDB Setup

Option 1: Local MongoDB

# Start MongoDB service
# Windows
net start MongoDB

# macOS/Linux
sudo systemctl start mongod

Option 2: MongoDB Atlas (Cloud)

Create account at MongoDB Atlas
Create a cluster
Get connection string
Update MONGODB_URI in backend .env

💻 Usage

User Roles & Permissions

Feature	Admin	Manager	Worker
Dashboard Overview	✅	✅	✅
View Inventory	✅	✅	✅
Add/Edit Inventory	✅	✅	❌
Delete Inventory	✅	✅	❌
User Management	✅	❌	❌
Create Tasks	✅	✅	❌
View All Tasks	✅	✅	❌
View My Tasks	-	-	✅
Update Task Status	✅	✅	✅
View Analytics	✅	✅	❌
FEFO Ordering	✅	✅	❌
Demand Forecast	✅	✅	❌

📚 API Documentation

Base URL

http://localhost:5000/api

Authentication

All authenticated endpoints require a JWT token in the Authorization header:

Authorization: Bearer <your_jwt_token>

API Endpoints Overview

🔐 Authentication APIs

Method	Endpoint	Description	Auth
POST	`/auth/register`	Register new user	❌
POST	`/auth/login`	Login user	❌
GET	`/auth/me`	Get current user	✅
POST	`/auth/logout`	Logout user	✅

👥 User Management APIs

Method	Endpoint	Description	Auth	Role
GET	`/users`	Get all users	✅	Admin
POST	`/users`	Create user	✅	Admin
PUT	`/users/:id`	Update user	✅	Admin
DELETE	`/users/:id`	Delete user	✅	Admin
GET	`/users/workers`	Get all workers	✅	Manager/Admin

📦 Inventory Management APIs

Method	Endpoint	Description	Auth	Role
GET	`/inventory`	Get all items	✅	All
GET	`/inventory/:id`	Get item by ID	✅	All
POST	`/inventory`	Create item	✅	Manager/Admin
PUT	`/inventory/:id`	Update item	✅	Manager/Admin
DELETE	`/inventory/:id`	Delete item	✅	Manager/Admin
GET	`/inventory/analytics/summary`	Get inventory summary	✅	All
GET	`/inventory/analytics/by-category`	Get category analytics	✅	All

✅ Task Management APIs

Method	Endpoint	Description	Auth	Role
GET	`/tasks`	Get all tasks	✅	Manager/Admin
GET	`/tasks/my-tasks`	Get my tasks	✅	Worker
POST	`/tasks`	Create task	✅	Manager/Admin
PUT	`/tasks/:id`	Update task	✅	Manager/Admin
PATCH	`/tasks/:id/status`	Update status	✅	Worker/Manager/Admin
DELETE	`/tasks/:id`	Delete task	✅	Manager/Admin

🔔 Alert System APIs

Method	Endpoint	Description	Auth
GET	`/alerts/low-stock`	Get low stock alerts	✅
GET	`/alerts/expiring-soon`	Get expiring soon alerts	✅
GET	`/alerts/critical`	Get critical alerts	✅
GET	`/alerts/summary`	Get alert summary	✅

📈 Analytics & Forecast APIs

Method	Endpoint	Description	Auth	Role
GET	`/analytics/demand-forecast`	Get demand forecast	✅	Manager/Admin
GET	`/analytics/fefo-ordering`	Get FEFO ordering	✅	Manager/Admin
GET	`/analytics/top-selling`	Get top selling products	✅	Manager/Admin
GET	`/analytics/notification-alerts`	Get notification alerts	✅	Manager/Admin

Example API Requests

Register User

POST /api/auth/register
Content-Type: application/json

{
  "name": "John Doe",
  "email": "[email protected]",
  "password": "password123",
  "role": "Worker"
}

Create Inventory Item

POST /api/inventory
Authorization: Bearer <token>
Content-Type: application/json

{
  "productName": "Fresh Milk",
  "category": "Dairy",
  "sku": "DA-001",
  "quantity": 150,
  "purchaseDate": "2025-11-01",
  "expiryDate": "2025-11-15",
  "supplier": "Local Dairy Farm"
}

Create Task

POST /api/tasks
Authorization: Bearer <token>
Content-Type: application/json

{
  "description": "Inspect expired items in dairy section",
  "assignedTo": "673ab12c5f8e9a001234abcd"
}

For complete API documentation, refer to the API Documentation Chapter in the project report.

📁 Project Structure

SmartShelf/
├── backend/
│   ├── src/
│   │   ├── controllers/          # Request handlers
│   │   │   ├── authController.js
│   │   │   ├── userController.js
│   │   │   ├── inventoryController.js
│   │   │   ├── taskController.js
│   │   │   ├── alertController.js
│   │   │   ├── forecastController.js
│   │   │   └── analyticsController.js
│   │   ├── models/                # Database models
│   │   │   ├── User.js
│   │   │   ├── Inventory.js
│   │   │   └── Task.js
│   │   ├── routes/                # API routes
│   │   │   ├── authRoutes.js
│   │   │   ├── userRoutes.js
│   │   │   ├── inventoryRoutes.js
│   │   │   ├── taskRoutes.js
│   │   │   ├── alertRoutes.js
│   │   │   └── analyticsRoutes.js
│   │   ├── middlewares/           # Custom middleware
│   │   │   ├── authMiddleware.js
│   │   │   ├── roleMiddleware.js
│   │   │   └── errorHandler.js
│   │   ├── utils/                 # Utility functions
│   │   │   ├── responseHelper.js
│   │   │   └── validators.js
│   │   ├── config/                # Configuration
│   │   │   └── database.js
│   │   └── app.js                 # Express app setup
│   ├── .env                       # Environment variables
│   ├── .env.example              # Example env file
│   ├── package.json
│   └── server.js                  # Entry point
│
├── frontend/
│   ├── components/                # Reusable components
│   │   └── Modal.tsx
│   ├── pages/                     # Page components
│   │   ├── LoginPage.tsx
│   │   ├── RegistrationPage.tsx
│   │   ├── MainLayout.tsx
│   │   ├── AdminDashboard.tsx
│   │   ├── ManagerDashboard.tsx
│   │   ├── WorkerDashboard.tsx
│   │   ├── InventoryPage.tsx
│   │   ├── UserManagementPage.tsx
│   │   └── TaskManagementPage.tsx
│   ├── contexts/                  # React contexts
│   │   └── ThemeContext.tsx
│   ├── services/                  # API services
│   │   ├── apiClient.ts
│   │   ├── authService.ts
│   │   ├── inventoryService.ts
│   │   ├── taskService.ts
│   │   ├── userService.ts
│   │   └── alertService.ts
│   ├── config/                    # Frontend config
│   │   └── api.ts
│   ├── types.ts                   # TypeScript types
│   ├── constants.tsx              # Constants & icons
│   ├── App.tsx                    # Main app component
│   ├── index.tsx                  # Entry point
│   ├── index.css                  # Global styles
│   ├── .env                       # Environment variables
│   ├── .env.example              # Example env file
│   ├── package.json
│   ├── tailwind.config.js
│   ├── tsconfig.json
│   └── vite.config.ts
│
├── docs/                          # Documentation
│   ├── API_DOCUMENTATION.md
│   └── PROJECT_REPORT.docx
│
├── .gitignore
├── LICENSE
└── README.md

🤝 Contributors

_{Namish Kumar Sahu}
_{Backend Development & API Design}

_{Turanya Mishra}
_{Frontend Development & UI/UX}

_{Shiba Prasad Gochhayat}
_{Database Design & Algorithms}

Institution

Biju Patnaik University of Technology (BPUT)
Department of Computer Science & Engineering
Center for Under Graduate & Post Graduate Studies
Rourkela, Odisha - 769015

📝 License

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

MIT License

Copyright (c) 2025 Namish Kumar Sahu, Turanya Mishra, Shiba Prasad Gochhayat

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

📞 Contact

For queries or feedback:

GitHub: @namish18
Project Repository: SmartShelf

🚧 Future Enhancements

⭐ Star this repository if you find it helpful!

Made with ❤️ by Team SmartShelf

Name		Name	Last commit message	Last commit date
Latest commit History 35 Commits
backend		backend
frontend		frontend
README.md		README.md

namish18/SmartShelf

Folders and files

Latest commit

History

Repository files navigation