MERN Spare Parts POS - Full Stack

A comprehensive spare-parts shop management system built on the MERN stack. It features a modern React frontend and a robust Node.js (Express) backend, designed for efficiency and ease of use. The application includes detailed inventory management, a point-of-sale (POS) interface, expense tracking, order history, and a secure authentication system with role-based access control.

Key Features

• Secure Authentication: Employs a secure login system using JSON Web Tokens (JWT) for session management and bcryptjs for password hashing.
• Role-Based Access Control (RBAC): Differentiates user permissions between Admins and Staff, ensuring data integrity and security.
• Interactive Dashboard: Provides an at-a-glance overview of key metrics like today's sales, gross profit, expenses, and low-stock alerts.
• Advanced Inventory Management: Full CRUD functionality for parts, with features like stock history tracking, bulk actions (activate, deactivate, delete), dynamic filtering, and sorting.
• Point of Sale (POS) Interface: A user-friendly interface to quickly search for products, manage a cart with discounts, and process sales.
• Comprehensive Order History: A detailed log of all past orders, allowing users to view items, totals, and dates for each transaction.
• Expense Tracking: A dedicated module for logging and managing business expenses with full CRUD capabilities.
• Dual Theme: Seamlessly switch between dark and light modes for optimal user comfort.
• Responsive Design: A clean, modern UI built with Tailwind CSS that works beautifully across desktops, tablets, and mobile devices.

Roles and Permissions

Feature	Admin	Staff
Dashboard	✅	✅
Inventory (View)	✅	✅
Inventory (Add/Edit/Delete)	✅	❌
POS System	✅	✅
View Orders	✅	✅
Expenses (View)	✅	✅
Expenses (Add/Edit/Delete)	✅	❌
View Reports	✅	✅
Access Settings	✅	❌

Tech Stack

• Frontend: React, TypeScript, Tailwind CSS, React Router
• Backend: Node.js, Express, MongoDB (with Mongoose)
• Authentication: JSON Web Tokens (JWT), bcryptjs

---

Project Structure

.
├── backend/
│   ├── models/         # Mongoose schemas (Part, Order, User, etc.)
│   ├── routes/         # API endpoint definitions
│   ├── middleware/     # Custom middleware (e.g., auth)
│   ├── utils/          # Utility functions (e.g., JWT generation)
│   ├── db.js           # Database connection logic
│   ├── server.js       # Main Express server entry point
│   └── seed.js         # Script to seed database with initial users
│
├── components/
│   ├── icons/          # SVG icon components
│   └── *.tsx           # Reusable React components (Modal, Sidebar, etc.)
│
├── contexts/           # React Context providers (Auth, Theme, POS)
├── pages/              # Top-level page components for each route
├── services/           # API call handlers (partApi, orderApi, etc.)
├── App.tsx             # Main application component with routing
├── index.html          # Main HTML entry point
├── index.tsx           # React root renderer
└── README.md           # You are here

---

Project Setup

Prerequisites

• Node.js (v16 or later recommended)
• npm or yarn
• MongoDB: A local or cloud-based MongoDB instance.

---

1. Backend Setup

a. Navigate to the backend directory:

cd backend

b. Install dependencies:

npm install

c. Configure Environment Variables: Create a new file named .env in the backend directory and add the following content. Be sure to replace the MONGO_URI with your actual MongoDB connection string.

# backend/.env

# Your MongoDB connection string
MONGO_URI=mongodb://localhost:27017/spareparts_pos

# Port for the backend server (optional, defaults to 5000)
PORT=5000

# Secret key for signing JWTs (use a long, random string in production)
JWT_SECRET=a-very-secret-key

d. Seed the database with default users: This crucial step creates an Admin and a Staff user for you to log in with.

npm run seed

This will create two users:

• Username: admin / Password: 123456 (Role: Admin)
• Username: staff / Password: 123456 (Role: Staff)

e. Start the backend server:

npm start

The server will now be running on http://localhost:5000.

---

2. Frontend Setup

In a new terminal window:

a. Navigate to the project's root directory (where index.html is located).

b. Install a simple static server package (if you don't have one): This project uses a static file setup with import maps, so a simple server is sufficient.

npm install -g serve

c. Start the frontend server: The -s flag ensures that it works correctly with single-page application routing.

serve -s .

d. Open the application: Navigate to the URL provided by serve (usually http://localhost:3000). You will be greeted by the login page.

---

API Endpoints

All endpoints are prefixed with /api. Protected routes require a valid JWT in the Authorization header.

Endpoint	Method	Description	Access
/users/login	POST	Authenticate a user and get a token	Public
/parts	GET	Get all inventory parts	Authenticated
/parts	POST	Add a new part	Admin
/parts/:id	PUT	Update an existing part	Admin
/parts/:id	DELETE	Delete a part	Admin
/parts/bulk-action	POST	Perform bulk actions on parts	Admin
/orders	GET	Get all orders	Authenticated
/orders	POST	Create a new order (from POS)	Authenticated
/expenses	GET	Get all expenses	Authenticated
/expenses	POST	Add a new expense	Admin
/expenses/:id	PUT	Update an existing expense	Admin
/expenses/:id	DELETE	Delete an expense	Admin