Inventory Management System

Table of Contents

• Project Overview

• Features

• Tech Stack

• Architecture

• Getting Started

  • Prerequisites
  • Clone & Install
  • Environment Variables
  • Database Setup
  • Run (Development)
  • Build & Run (Production)

• API Endpoints

• Data Models (Summary)

• Authentication & Authorization

• Testing

• Deployment

• CI / CD Suggestions

• Contributing

• License

---

Project Overview

An Inventory Management System (IMS) to manage products, stock levels, suppliers, purchase orders, and sales. Built as a modern full-stack application with a RESTful API backend and a React-based frontend. The system supports role-based access control (Admin, Manager, Staff), audit logging, and basic reporting.

This README assumes a development stack of React for the frontend and Node.js + Express for the backend with MongoDB (Mongoose) as the database.

Features

• Product CRUD (create, read, update, delete)
• Stock management (incoming purchases, outgoing sales, stock adjustments)
• Supplier and category management
• Purchase Orders & Sales Orders
• Role-Based Access Control (Admin, User, Supplier)
• JWT authentication with refresh tokens
• Search, filters, and pagination on listings

Tech Stack

• Frontend: React, TypeScript, Tailwind CSS
• Backend: Node.js, Express, TypeScript (optional), Mongoose (MongoDB)
• Auth: JWT (access + refresh tokens) stored with httpOnly cookies (recommended)
• Dev tooling: Jest for tests, ESLint, Prettier
• Dev deploy: Docker / docker-compose (optional)

Architecture

• Client (Next.js) — UI, authentication flows, calls API endpoints.
• Server (Express) — REST API, business logic, validation, rate limiting, logging.
• Database (MongoDB) — collections: users, products, suppliers, orders, logs.

---

Getting Started

Prerequisites

• Node.js (v18+ recommended)
• npm or yarn
• MongoDB (local or cloud: MongoDB Atlas)
• (Optional) Docker & docker-compose

Clone & Install

# clone
git clone https://github.com/your-username/inventory-management-system.git
cd inventory-management-system

# install backend
cd server
npm install

# install frontend
cd ../client
npm install

Environment Variables

Create .env files for server (and optionally client). Example for server (server/.env):

PORT=5000
MONGO_URI=mongodb://localhost:27017/inventory_db
JWT_ACCESS_SECRET=your_access_secret_here
JWT_REFRESH_SECRET=your_refresh_secret_here
ACCESS_TOKEN_EXPIRES=15m
REFRESH_TOKEN_EXPIRES=7d
NODE_ENV=development

Keep secrets out of source control. Use .env.example with placeholder values for reference.

Database Setup

• If using local MongoDB: make sure mongod is running and MONGO_URI points to it.
• If using MongoDB Atlas: create a cluster and use the connection string.

You can seed sample data using the provided seed script (if available):

# from server
npm run seed

Run (Development)

Run server and client in parallel (two terminals) or use a single monorepo script.

# backend
cd server
npm run dev

# frontend
cd ../client
npm run dev

Typical ports:

• Backend: http://localhost:5000
• Frontend: http://localhost:3000

Build & Run (Production)

# server (example)
cd server
npm run build
npm start

# client (Next.js)
cd client
npm run build
npm start

---

API Endpoints (Summary)

This is a short map — update routes to reflect your implementation.

Auth

• POST /api/auth/register - register user
• POST /api/auth/login - login (returns access token)
• POST /api/auth/refresh - refresh token
• POST /api/auth/logout - logout (revoke refresh token)

Users (Admin)

• GET /api/users - list users
• GET /api/users/:id - get user
• PUT /api/users/:id - update user / role
• DELETE /api/users/:id - remove user

Products

• GET /api/products - list with filters, search, pagination
• GET /api/products/:id - product details
• POST /api/products - create product (Admin/Manager)
• PUT /api/products/:id - update product
• DELETE /api/products/:id - delete product

Suppliers

• GET /api/suppliers
• POST /api/suppliers

Orders

• POST /api/purchases - record incoming stock
• POST /api/sales - record sale (reduce stock)
• GET /api/orders - list orders

Reports

• GET /api/reports/stock - current stock levels
• GET /api/reports/low-stock - low stock items

Add proper validation and secure routes with middleware.

---

Data Models (Summary)

• User: { _id, name, email, passwordHash, role, createdAt, updatedAt }
• Product: { _id, sku, name, description, price, cost, quantity, category, supplierId, reOrderLevel, createdAt }
• Supplier: { _id, name, contact, address, notes }
• Order (Purchase/Sale): { _id, type, items: [{ productId, qty, unitPrice }], total, createdBy, supplierId?, status }
• AuditLog: { _id, action, resourceType, resourceId, userId, metadata, timestamp }

---

Authentication & Authorization

• Use JWT for stateless auth. Issue short-lived access tokens (e.g., 15m) and long-lived refresh tokens stored in httpOnly secure cookies.
• Implement role-based middleware to guard routes (Admin, Manager, Staff).
• Consider token revocation/storage for refresh tokens (e.g., Redis or DB store) to allow logout and forced invalidation.

---

Testing

• Unit tests with Jest for core services and utility functions.
• Integration tests for critical API flows (auth, product create/update, order flow).
• Use a test MongoDB database (or in-memory MongoDB) to run test suites.

# run tests (server)
cd server
npm test

---

Deployment

• Use environment variables for all secrets and DB connections.
• Recommended platforms: Render / Railway / Heroku for backend; Vercel for Next.js frontend.

---

CI / CD Suggestions

• Run linting and tests on PRs (GitHub Actions example).
• On main branch merge, run build and deploy steps.

---

License

MIT License — update if you prefer another license.

---

Useful Notes & TODOs (ideas for future implement)

• Real-Time Stock Updates using WebSockets or Socket.IO

• AI‑Powered Demand Forecasting to predict stock shortages

• SMS / Email Alerts for low stock or new orders

• Barcode & QR Code Integration for scanning items in/out

• Bulk Product Import (CSV / Excel) with validation

• Multi-Warehouse Support to track stock across multiple locations

• Supplier Performance Tracking (delivery time, reliability, cost trends)

• Role-Based Dashboard Widgets (Admin, Manager, Staff views)

• Advanced Reports (profit margins, stock aging, reorder suggestions)

• Scheduled Automated Reports emailed daily/weekly

• Soft Delete for Products & Users with restore options

• Product Variants Support (size, color, model)

• Activity Timeline for each product (who updated price, stock changes, etc.)

• Audit Log Filtering + Export (Admin panel)

• API Rate Limiting + IP Whitelist for security

• Redis Cache Layer for frequently accessed data (products, stock counts)

• Webhook Integrations for third‑party ERP or POS systems

• Cloudinary Integration for product images