stockhub-sms 1.0.0

package/.gitignore

@@ -0,0 +1,35 @@
+# Dependencies
+node_modules/
+package-lock.json
+yarn.lock
+
+# Environment variables
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# Build outputs
+build/
+dist/
+*.log
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+coverage/
+
+# Misc
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

package/README.md

@@ -0,0 +1,303 @@
+# Stock Management System (SMS)
+
+## Project Overview
+A comprehensive web-based Stock Management System developed for StockHub Ltd, Kigali, Rwanda. This system digitizes and automates stock movement tracking, inventory management, and report generation.
+
+## Technology Stack
+
+### Backend
+- **Runtime**: Node.js
+- **Framework**: Express.js
+- **Database**: MongoDB
+- **ODM**: Mongoose
+- **Authentication**: JWT (JSON Web Tokens)
+- **Password Hashing**: bcryptjs
+
+### Frontend
+- **Framework**: React.js 18
+- **Routing**: React Router DOM v6
+- **Styling**: Tailwind CSS
+- **HTTP Client**: Axios
+- **Build Tool**: React Scripts
+
+## Features
+
+### 1. Authentication System
+- User registration and login
+- JWT-based authentication
+- Protected routes
+- Session management
+
+### 2. Product Management
+- Add new products with details (code, name, category, quantity, price, supplier, date)
+- View all products in a responsive table
+- Real-time stock quantity tracking
+- Low stock alerts (products with quantity < 10)
+
+### 3. Warehouse Management
+- Create warehouses with code, name, and location
+- View all warehouses in a card-based layout
+- Track warehouse information
+
+### 4. Stock Transaction Management
+- Record stock IN and stock OUT transactions
+- Link transactions to products and warehouses
+- Automatic inventory quantity updates
+- Full CRUD operations (Create, Read, Update, Delete)
+- Transaction validation (prevent negative stock)
+
+### 5. Reports & Analytics
+- **Dashboard**: Overview with key metrics, low stock alerts, recent transactions
+- **Available Stock Report**: Current inventory with total values
+- **Stock IN Report**: Filtered by daily, weekly, monthly, or custom date range
+- **Stock OUT Report**: Filtered by daily, weekly, monthly, or custom date range
+- Print-friendly report layouts
+- Summary statistics (total quantity, total value, transaction count)
+
+### 6. Responsive Design
+- Mobile-friendly interface
+- Adaptive layouts for all screen sizes
+- Touch-friendly navigation
+
+## Project Structure
+
+```
+├── backend-project/
+│   ├── config/
+│   │   ├── database.js          # Database connection
+│   │   └── initDatabase.js      # Database initialization
+│   ├── middleware/
+│   │   └── auth.js              # JWT authentication middleware
+│   ├── routes/
+│   │   ├── auth.js              # Authentication routes
+│   │   ├── products.js          # Product routes
+│   │   ├── warehouses.js        # Warehouse routes
+│   │   ├── transactions.js      # Transaction routes
+│   │   └── reports.js           # Report routes
+│   ├── .env                     # Environment variables
+│   ├── package.json             # Backend dependencies
+│   └── server.js                # Express server entry point
+│
+├── frontend-project/
+│   ├── public/
+│   │   └── index.html           # HTML template
+│   ├── src/
+│   │   ├── components/
+│   │   │   ├── Auth/
+│   │   │   │   ├── Login.js
+│   │   │   │   └── Register.js
+│   │   │   ├── Dashboard/
+│   │   │   │   └── Dashboard.js
+│   │   │   ├── Layout/
+│   │   │   │   └── Layout.js
+│   │   │   ├── Products/
+│   │   │   │   └── Products.js
+│   │   │   ├── Warehouses/
+│   │   │   │   └── Warehouses.js
+│   │   │   ├── Transactions/
+│   │   │   │   └── Transactions.js
+│   │   │   └── Reports/
+│   │   │       └── Reports.js
+│   │   ├── services/
+│   │   │   └── api.js           # API service layer
+│   │   ├── App.js               # Main app component
+│   │   ├── index.js             # React entry point
+│   │   └── index.css            # Global styles
+│   ├── package.json             # Frontend dependencies
+│   ├── tailwind.config.js       # Tailwind configuration
+│   └── postcss.config.js        # PostCSS configuration
+│
+├── ERD_DESIGN.md                # Entity Relationship Diagram documentation
+└── README.md                    # This file
+```
+
+## Database Schema
+
+### Collections
+1. **User**: User authentication
+2. **Product**: Product inventory
+3. **Warehouse**: Warehouse locations
+4. **StockTransaction**: Stock movement records
+
+See `ERD_DESIGN.md` for detailed schema and relationships.
+
+## Installation & Setup
+
+### Prerequisites
+- Node.js (v14 or higher)
+- MongoDB Server (v4.4 or higher)
+- npm or yarn package manager
+
+### Backend Setup
+
+1. Navigate to backend directory:
+```bash
+cd backend-project
+```
+
+2. Install dependencies:
+```bash
+npm install
+```
+
+3. Configure environment variables in `.env`:
+```env
+PORT=5000
+MONGODB_URI=mongodb://localhost:27017/SMS
+JWT_SECRET=your_secret_key
+```
+
+4. Start MongoDB server and ensure it's running
+
+5. Start the backend server:
+```bash
+npm start
+```
+
+The backend will:
+- Connect to MongoDB
+- Create the SMS database if it doesn't exist
+- Create all required collections automatically
+- Start listening on port 5000
+
+### Frontend Setup
+
+1. Navigate to frontend directory:
+```bash
+cd frontend-project
+```
+
+2. Install dependencies:
+```bash
+npm install
+```
+
+3. Start the development server:
+```bash
+npm start
+```
+
+The frontend will open automatically at `http://localhost:3000`
+
+## Usage Guide
+
+### First Time Setup
+
+1. **Register a User Account**
+   - Navigate to the registration page
+   - Create a username and password
+   - Login with your credentials
+
+2. **Add Warehouses**
+   - Go to Warehouses page
+   - Click "+ Add Warehouse"
+   - Fill in warehouse details
+
+3. **Add Products**
+   - Go to Products page
+   - Click "+ Add Product"
+   - Enter product information
+
+4. **Record Transactions**
+   - Go to Transactions page
+   - Click "+ Add Transaction"
+   - Select product, warehouse, date, quantity, and type (IN/OUT)
+   - Submit to update inventory
+
+5. **View Reports**
+   - Go to Reports page
+   - Select report type
+   - Apply filters for date ranges
+   - Print reports as needed
+
+## API Endpoints
+
+### Authentication
+- `POST /api/auth/register` - Register new user
+- `POST /api/auth/login` - Login user
+
+### Products
+- `GET /api/products` - Get all products
+- `GET /api/products/:productCode` - Get single product
+- `POST /api/products` - Create product
+
+### Warehouses
+- `GET /api/warehouses` - Get all warehouses
+- `GET /api/warehouses/:warehouseCode` - Get single warehouse
+- `POST /api/warehouses` - Create warehouse
+
+### Transactions
+- `GET /api/transactions` - Get all transactions
+- `GET /api/transactions/:id` - Get single transaction
+- `POST /api/transactions` - Create transaction
+- `PUT /api/transactions/:id` - Update transaction
+- `DELETE /api/transactions/:id` - Delete transaction
+
+### Reports
+- `GET /api/reports/available-stock` - Available stock report
+- `GET /api/reports/stock-in` - Stock IN report (with filters)
+- `GET /api/reports/stock-out` - Stock OUT report (with filters)
+- `GET /api/reports/dashboard` - Dashboard summary
+
+## Security Features
+
+- Password hashing with bcrypt
+- JWT token-based authentication
+- Protected API routes
+- Input validation
+- SQL injection prevention (parameterized queries)
+- CORS enabled for frontend-backend communication
+
+## Business Logic
+
+### Stock Transaction Rules
+1. **Stock IN**: Increases product quantity
+2. **Stock OUT**: Decreases product quantity
+3. **Validation**: Prevents negative stock levels
+4. **Atomicity**: Uses database transactions for data consistency
+5. **Cascade Delete**: Removing products/warehouses removes related transactions
+
+## Future Enhancements
+
+- User roles and permissions (Admin, Manager, Staff)
+- Product categories management
+- Barcode scanning integration
+- Email notifications for low stock
+- Advanced analytics and charts
+- Export reports to PDF/Excel
+- Multi-warehouse stock transfer
+- Supplier management module
+- Purchase order tracking
+
+## Troubleshooting
+
+### Backend Issues
+- **Database connection error**: Check MongoDB is running and URI in `.env` is correct
+- **Port already in use**: Change PORT in `.env` file
+- **Module not found**: Run `npm install` in backend-project
+
+### Frontend Issues
+- **Cannot connect to API**: Ensure backend is running on port 5000
+- **Module not found**: Run `npm install` in frontend-project
+- **Tailwind styles not working**: Restart the development server
+
+## Development Team
+
+Developed as part of the Integrated Assessment Project for StockHub Ltd.
+
+## License
+
+This project is developed for educational purposes.
+
+## Support
+
+For issues or questions, please refer to the project documentation or contact the development team.
+
+---
+
+**Note**: This system successfully addresses StockHub Ltd's challenges by:
+- Eliminating manual paper-based processes
+- Reducing errors through automated calculations
+- Providing real-time stock visibility
+- Enabling quick report generation
+- Improving operational efficiency

package/backend-project/.env

@@ -0,0 +1,3 @@
+PORT=5000
+MONGODB_URI=mongodb://localhost:27017/SMS
+JWT_SECRET=your_jwt_secret_key_here_change_in_production

package/backend-project/.env.example

@@ -0,0 +1,3 @@
+PORT=5000
+MONGODB_URI=mongodb://localhost:27017/SMS
+JWT_SECRET=your_jwt_secret_key_here_change_in_production

package/backend-project/config/database.js

@@ -0,0 +1,13 @@
+const mongoose = require('mongoose');
+
+const connectDB = async () => {
+  try {
+    await mongoose.connect(process.env.MONGODB_URI);
+    console.log('MongoDB connected successfully');
+  } catch (error) {
+    console.error('MongoDB connection error:', error);
+    process.exit(1);
+  }
+};
+
+module.exports = connectDB;

package/backend-project/controllers/authController.js

@@ -0,0 +1,70 @@
+const bcrypt = require('bcryptjs');
+const jwt = require('jsonwebtoken');
+const User = require('../models/User');
+
+exports.register = async (req, res) => {
+  try {
+    const { username, password } = req.body;
+
+    if (!username || !password) {
+      return res.status(400).json({ message: 'Username and password are required' });
+    }
+
+    const existingUser = await User.findOne({ username });
+
+    if (existingUser) {
+      return res.status(400).json({ message: 'Username already exists' });
+    }
+
+    const hashedPassword = await bcrypt.hash(password, 10);
+
+    const user = new User({
+      username,
+      password: hashedPassword
+    });
+
+    await user.save();
+
+    res.status(201).json({ message: 'User registered successfully' });
+  } catch (error) {
+    console.error('Registration error:', error);
+    res.status(500).json({ message: 'Server error during registration' });
+  }
+};
+
+exports.login = async (req, res) => {
+  try {
+    const { username, password } = req.body;
+
+    if (!username || !password) {
+      return res.status(400).json({ message: 'Username and password are required' });
+    }
+
+    const user = await User.findOne({ username });
+
+    if (!user) {
+      return res.status(401).json({ message: 'Invalid credentials' });
+    }
+
+    const isValidPassword = await bcrypt.compare(password, user.password);
+
+    if (!isValidPassword) {
+      return res.status(401).json({ message: 'Invalid credentials' });
+    }
+
+    const token = jwt.sign(
+      { userId: user._id, username: user.username },
+      process.env.JWT_SECRET,
+      { expiresIn: '24h' }
+    );
+
+    res.json({
+      message: 'Login successful',
+      token,
+      user: { userId: user._id, username: user.username }
+    });
+  } catch (error) {
+    console.error('Login error:', error);
+    res.status(500).json({ message: 'Server error during login' });
+  }
+};

package/backend-project/controllers/productController.js

@@ -0,0 +1,58 @@
+const Product = require('../models/Product');
+
+exports.getAll = async (req, res) => {
+  try {
+    const products = await Product.find().sort({ productName: 1 });
+    res.json(products);
+  } catch (error) {
+    console.error('Error fetching products:', error);
+    res.status(500).json({ message: 'Error fetching products' });
+  }
+};
+
+exports.getOne = async (req, res) => {
+  try {
+    const product = await Product.findOne({ productCode: req.params.productCode });
+
+    if (!product) {
+      return res.status(404).json({ message: 'Product not found' });
+    }
+
+    res.json(product);
+  } catch (error) {
+    console.error('Error fetching product:', error);
+    res.status(500).json({ message: 'Error fetching product' });
+  }
+};
+
+exports.create = async (req, res) => {
+  try {
+    const { productCode, productName, category, quantityInStock, unitPrice, supplierName, dateReceived } = req.body;
+
+    if (!productCode || !productName || !category || quantityInStock === undefined || !unitPrice || !supplierName || !dateReceived) {
+      return res.status(400).json({ message: 'All fields are required' });
+    }
+
+    const existing = await Product.findOne({ productCode });
+    if (existing) {
+      return res.status(400).json({ message: 'Product code already exists' });
+    }
+
+    const product = new Product({
+      productCode,
+      productName,
+      category,
+      quantityInStock,
+      unitPrice,
+      supplierName,
+      dateReceived
+    });
+
+    await product.save();
+
+    res.status(201).json({ message: 'Product created successfully' });
+  } catch (error) {
+    console.error('Error creating product:', error);
+    res.status(500).json({ message: 'Error creating product' });
+  }
+};

package/backend-project/controllers/reportController.js

@@ -0,0 +1,206 @@
+const StockTransaction = require('../models/StockTransaction');
+const Product = require('../models/Product');
+const Warehouse = require('../models/Warehouse');
+
+exports.getAvailableStock = async (req, res) => {
+  try {
+    const products = await Product.find().sort({ productName: 1 });
+
+    const productsWithValue = products.map(product => ({
+      productCode: product.productCode,
+      productName: product.productName,
+      category: product.category,
+      quantityInStock: product.quantityInStock,
+      unitPrice: product.unitPrice,
+      supplierName: product.supplierName,
+      dateReceived: product.dateReceived,
+      totalValue: product.quantityInStock * product.unitPrice
+    }));
+
+    res.json(productsWithValue);
+  } catch (error) {
+    console.error('Error fetching available stock:', error);
+    res.status(500).json({ message: 'Error fetching available stock report' });
+  }
+};
+
+exports.getStockIn = async (req, res) => {
+  try {
+    const { period, startDate, endDate } = req.query;
+    let dateFilter = { transactionType: 'IN' };
+
+    if (period === 'daily' && startDate) {
+      const date = new Date(startDate);
+      const nextDay = new Date(date);
+      nextDay.setDate(nextDay.getDate() + 1);
+      dateFilter.transactionDate = { $gte: date, $lt: nextDay };
+    } else if (period === 'weekly' && startDate) {
+      const date = new Date(startDate);
+      const weekStart = new Date(date);
+      weekStart.setDate(date.getDate() - date.getDay());
+      const weekEnd = new Date(weekStart);
+      weekEnd.setDate(weekStart.getDate() + 7);
+      dateFilter.transactionDate = { $gte: weekStart, $lt: weekEnd };
+    } else if (period === 'monthly' && startDate) {
+      const date = new Date(startDate);
+      const monthStart = new Date(date.getFullYear(), date.getMonth(), 1);
+      const monthEnd = new Date(date.getFullYear(), date.getMonth() + 1, 1);
+      dateFilter.transactionDate = { $gte: monthStart, $lt: monthEnd };
+    } else if (startDate && endDate) {
+      dateFilter.transactionDate = {
+        $gte: new Date(startDate),
+        $lte: new Date(endDate)
+      };
+    }
+
+    const transactions = await StockTransaction.find(dateFilter).sort({ transactionDate: -1 });
+
+    const enrichedTransactions = await Promise.all(
+      transactions.map(async (transaction) => {
+        const product = await Product.findOne({ productCode: transaction.productCode });
+        const warehouse = await Warehouse.findOne({ warehouseCode: transaction.warehouseCode });
+
+        return {
+          transactionId: transaction._id,
+          transactionDate: transaction.transactionDate,
+          productCode: transaction.productCode,
+          productName: product ? product.productName : 'Unknown',
+          category: product ? product.category : 'Unknown',
+          warehouseCode: transaction.warehouseCode,
+          warehouseName: warehouse ? warehouse.warehouseName : 'Unknown',
+          quantityMoved: transaction.quantityMoved,
+          unitPrice: product ? product.unitPrice : 0,
+          totalValue: product ? transaction.quantityMoved * product.unitPrice : 0
+        };
+      })
+    );
+
+    const summary = {
+      totalQuantity: enrichedTransactions.reduce((sum, t) => sum + t.quantityMoved, 0),
+      totalValue: enrichedTransactions.reduce((sum, t) => sum + parseFloat(t.totalValue), 0),
+      transactionCount: enrichedTransactions.length
+    };
+
+    res.json({ transactions: enrichedTransactions, summary });
+  } catch (error) {
+    console.error('Error fetching stock in report:', error);
+    res.status(500).json({ message: 'Error fetching stock in report' });
+  }
+};
+
+exports.getStockOut = async (req, res) => {
+  try {
+    const { period, startDate, endDate } = req.query;
+    let dateFilter = { transactionType: 'OUT' };
+
+    if (period === 'daily' && startDate) {
+      const date = new Date(startDate);
+      const nextDay = new Date(date);
+      nextDay.setDate(nextDay.getDate() + 1);
+      dateFilter.transactionDate = { $gte: date, $lt: nextDay };
+    } else if (period === 'weekly' && startDate) {
+      const date = new Date(startDate);
+      const weekStart = new Date(date);
+      weekStart.setDate(date.getDate() - date.getDay());
+      const weekEnd = new Date(weekStart);
+      weekEnd.setDate(weekStart.getDate() + 7);
+      dateFilter.transactionDate = { $gte: weekStart, $lt: weekEnd };
+    } else if (period === 'monthly' && startDate) {
+      const date = new Date(startDate);
+      const monthStart = new Date(date.getFullYear(), date.getMonth(), 1);
+      const monthEnd = new Date(date.getFullYear(), date.getMonth() + 1, 1);
+      dateFilter.transactionDate = { $gte: monthStart, $lt: monthEnd };
+    } else if (startDate && endDate) {
+      dateFilter.transactionDate = {
+        $gte: new Date(startDate),
+        $lte: new Date(endDate)
+      };
+    }
+
+    const transactions = await StockTransaction.find(dateFilter).sort({ transactionDate: -1 });
+
+    const enrichedTransactions = await Promise.all(
+      transactions.map(async (transaction) => {
+        const product = await Product.findOne({ productCode: transaction.productCode });
+        const warehouse = await Warehouse.findOne({ warehouseCode: transaction.warehouseCode });
+
+        return {
+          transactionId: transaction._id,
+          transactionDate: transaction.transactionDate,
+          productCode: transaction.productCode,
+          productName: product ? product.productName : 'Unknown',
+          category: product ? product.category : 'Unknown',
+          warehouseCode: transaction.warehouseCode,
+          warehouseName: warehouse ? warehouse.warehouseName : 'Unknown',
+          quantityMoved: transaction.quantityMoved,
+          unitPrice: product ? product.unitPrice : 0,
+          totalValue: product ? transaction.quantityMoved * product.unitPrice : 0
+        };
+      })
+    );
+
+    const summary = {
+      totalQuantity: enrichedTransactions.reduce((sum, t) => sum + t.quantityMoved, 0),
+      totalValue: enrichedTransactions.reduce((sum, t) => sum + parseFloat(t.totalValue), 0),
+      transactionCount: enrichedTransactions.length
+    };
+
+    res.json({ transactions: enrichedTransactions, summary });
+  } catch (error) {
+    console.error('Error fetching stock out report:', error);
+    res.status(500).json({ message: 'Error fetching stock out report' });
+  }
+};
+
+exports.getDashboard = async (req, res) => {
+  try {
+    const totalProducts = await Product.countDocuments();
+
+    const totalWarehouses = await Warehouse.countDocuments();
+
+    const products = await Product.find();
+    const totalStockValue = products.reduce((sum, p) => sum + (p.quantityInStock * p.unitPrice), 0);
+
+    const today = new Date();
+    today.setHours(0, 0, 0, 0);
+    const tomorrow = new Date(today);
+    tomorrow.setDate(tomorrow.getDate() + 1);
+
+    const todayTransactions = await StockTransaction.countDocuments({
+      transactionDate: { $gte: today, $lt: tomorrow }
+    });
+
+    const lowStock = await Product.find({ quantityInStock: { $lt: 10 } })
+      .sort({ quantityInStock: 1 })
+      .limit(5);
+
+    const recentTransactionsData = await StockTransaction.find()
+      .sort({ transactionDate: -1, createdAt: -1 })
+      .limit(5);
+
+    const recentTransactions = await Promise.all(
+      recentTransactionsData.map(async (transaction) => {
+        const product = await Product.findOne({ productCode: transaction.productCode });
+        const warehouse = await Warehouse.findOne({ warehouseCode: transaction.warehouseCode });
+
+        return {
+          ...transaction.toObject(),
+          productName: product ? product.productName : 'Unknown',
+          warehouseName: warehouse ? warehouse.warehouseName : 'Unknown'
+        };
+      })
+    );
+
+    res.json({
+      totalProducts,
+      totalWarehouses,
+      totalStockValue,
+      todayTransactions,
+      lowStockProducts: lowStock,
+      recentTransactions
+    });
+  } catch (error) {
+    console.error('Error fetching dashboard data:', error);
+    res.status(500).json({ message: 'Error fetching dashboard data' });
+  }
+};