StockMaster - Inventory Management System

A full-stack inventory management system built with Node.js/Express backend and React frontend, featuring role-based access control, real-time stock tracking, and comprehensive movement history.

Features

• User Authentication: JWT-based login with role-based access (Manager/Staff)
• Inventory Management: Track products, categories, and stock levels
• Stock Operations: Record IN, OUT, TRANSFER, and ADJUSTMENT movements
• Real-time Monitoring: KPI dashboard with key metrics
• Audit Trail: Complete movement history with user tracking
• Responsive UI: Modern, mobile-friendly interface with Tailwind CSS

Project Structure

odoo-hackathon-K-main/
├── backend/
│   ├── server.js                 # Main Express server
│   ├── package.json              # Backend dependencies
│   ├── .env                      # Environment variables
│   ├── schema.sql                # Database schema
│   ├── config/
│   │   └── db.js                # MySQL database configuration
│   ├── middleware/
│   │   ├── authMiddleware.js    # JWT authentication
│   │   └── roleMiddleware.js    # Role-based authorization
│   └── routes/
│       ├── authRoutes.js         # User registration/login
│       ├── productRoutes.js      # Product CRUD operations
│       └── inventoryRoutes.js    # Stock movement operations
│
├── frontend/
│   ├── index.html                # HTML entry point
│   ├── package.json              # Frontend dependencies
│   ├── vite.config.js            # Vite configuration
│   ├── src/
│   │   ├── main.jsx              # React entry point
│   │   ├── App.jsx               # Main App component
│   │   ├── index.css             # Global styles with Tailwind
│   │   ├── components/
│   │   │   ├── Layout.jsx        # Protected layout wrapper
│   │   │   ├── Sidebar.jsx       # Navigation sidebar
│   │   │   ├── KPICard.jsx       # Dashboard metric cards
│   │   │   └── Table.jsx         # Reusable table component
│   │   ├── pages/
│   │   │   ├── Login.jsx         # Login page
│   │   │   ├── Dashboard.jsx     # Overview dashboard
│   │   │   ├── Inventory.jsx     # Product inventory view
│   │   │   ├── Operations.jsx    # Stock movement form
│   │   │   └── History.jsx       # Movement audit trail
│   │   ├── context/
│   │   │   └── AuthContext.jsx   # Auth state management
│   │   └── utils/
│   │       └── axiosObs.js       # API client with auth token
│   └── public/                   # Static assets
│
└── README.md                     # Project documentation

Tech Stack

Backend

• Express.js: Web framework
• MySQL2/Promise: Database with async support
• bcryptjs: Password hashing
• jsonwebtoken: JWT authentication
• cors: Cross-origin resource sharing
• dotenv: Environment variable management

Frontend

• React 18: UI library
• React Router v6: Navigation
• Axios: HTTP client
• Tailwind CSS: Utility-first CSS framework
• Lucide React: Icon library
• Vite: Build tool & dev server

Setup Instructions

Prerequisites

• Node.js (v16+)
• MySQL Server (v5.7+)
• npm or yarn

Backend Setup

1. Navigate to backend directory

cd backend

2. Install dependencies

npm install

3. Setup environment variables Create .env file with:

DB_HOST=localhost
DB_USER=root
DB_PASS=your_password
DB_NAME=stockmaster
JWT_SECRET=your_secret_key_change_in_production
PORT=5000

4. Initialize database

mysql -u root -p < schema.sql

5. Start backend server

npm start         # Production mode
npm run dev      # Development mode with nodemon

Server will run on http://localhost:5000

Frontend Setup

1. Navigate to frontend directory

cd frontend

2. Install dependencies

npm install

3. Start development server

npm run dev

Application will open on http://localhost:5173

API Endpoints

Authentication

• POST /api/auth/register - Register new user
• POST /api/auth/login - Login and get JWT token

Products

• GET /api/products - List all products (requires auth)
• POST /api/products - Create product (manager only)

Inventory

• POST /api/inventory/move - Record stock movement
• GET /api/inventory/history - Get movement history

Demo Credentials

Manager Account:

• Email: manager@test.com
• Password: password123

Staff Account:

• Email: staff@test.com
• Password: password123

Database Schema

Tables

• users: User accounts with roles
• categories: Product categories
• products: Product master data
• locations: Storage locations/warehouses
• stock_levels: Current inventory at each location
• movements: Complete audit trail of all stock movements

Features Detail

Dashboard

• Real-time KPI metrics
• Total products count
• Total stock quantity
• Low stock alerts
• Recent movements summary

Inventory Management

• View all products with current stock levels
• Create new products (Manager only)
• Search and filter products
• Stock level indicators

Stock Operations

• IN: Receive stock from vendors
• OUT: Deliver stock to customers
• TRANSFER: Move stock between locations
• ADJUSTMENT: Correct stock discrepancies

History/Audit Trail

• Complete movement ledger
• User tracking for accountability
• Movement type indicators
• Location-to-location tracking
• Timestamp and reference tracking

Security Features

• JWT-based stateless authentication
• Password hashing with bcryptjs
• Role-based authorization
• CORS protection
• HTTP-only token storage (recommended)
• SQL injection prevention with prepared statements

Error Handling

• Comprehensive error messages
• Input validation
• Transaction rollback on database errors
• User-friendly error notifications

Performance Optimizations

• MySQL connection pooling
• Indexed database queries
• Memoized API calls
• Lazy loading of routes
• Efficient state management

Troubleshooting

Database Connection Issues

Error: connect ECONNREFUSED

• Ensure MySQL is running
• Verify DB credentials in .env
• Check database exists

CORS Errors

• Verify backend is running on port 5000
• Check CORS configuration in server.js

Token Expired

• Clear localStorage and login again
• JWT expires in 24 hours by default

Future Enhancements

• Advanced analytics and reporting
• Barcode/QR code scanning
• Multi-warehouse support
• Supplier management
• Email notifications
• Mobile app
• Real-time notifications via WebSocket

License

ISC License

Support

For issues and questions, please check the documentation or contact the development team.

---

Version: 1.0.0
Last Updated: January 2026