SIOMS — Smart Inventory & Order Management System

A full-stack web application for managing product catalogues, monitoring stock levels, processing customer orders, and tracking fulfilment workflows from a single real-time dashboard.

Live Demo: sioms-frontend-chi.vercel.app API: sioms-backend-yxq9.onrender.com

Demo credentials: admin@sioms.app / Admin@1234 (Admin) or demo@sioms.app / Demo@1234 (Manager)

---

Features

Core Business Logic

• Order Management — Create orders with automatic stock deduction, conflict detection (duplicate products, insufficient stock, inactive items), and sequential order numbering (ORD-0001, ORD-0002, ...)
• Order Status Workflow — Enforced status transitions: Pending → Confirmed → Shipped → Delivered, with cancellation support that automatically restores stock
• Inventory Tracking — Real-time stock levels with automatic status management (active ↔ out_of_stock) based on quantity changes
• Restock Queue — Automatic low-stock detection with priority tiers (HIGH / MEDIUM / LOW) based on configurable thresholds, sorted by urgency
• Activity Log — Append-only audit trail recording all system events (order creation, status changes, stock updates, user registrations)

Dashboard & Analytics

• KPI Cards — Orders today, pending orders, completed orders, revenue today, low stock count
• 7-Day Trend Chart — Dual-axis bar chart showing order count and revenue over the past week (Recharts)
• Product Stock Summary — Color-coded table (green/amber/red) showing all products sorted by stock level
• Activity Feed — Recent system events displayed in real-time

Authentication & Authorization

• JWT Authentication — Short-lived access tokens (15 min) with refresh token rotation (7 days)
• Role-Based Access Control — Admin and Manager roles with different permissions
  • Admin — Full access: create/edit/delete products, categories, and orders
  • Manager — Can view everything, create orders, update order status, and restock products
• Demo Login — One-click demo credential fill for quick testing

Product & Category Management

• CRUD Operations — Full create, read, update, delete for products and categories
• Search & Filtering — Search by name, filter by category and status, with pagination
• Validation — Category name uniqueness (case-insensitive), delete protection when products are assigned
• Auto Status — Product status automatically derived from stock quantity (never manually set)

Conflict Detection

Conflict	Response
Product already in order	409 — "This product is already added to the order."
Product inactive / out of stock	422 — "This product is currently unavailable."
Requested qty exceeds stock	409 — "Only X items available in stock."
Invalid status transition	422 — "Cannot move order from X to Y."
Category has products on delete	409 — "Category has associated products."
Duplicate category name	409 — "A category with this name already exists."

---

Tech Stack

Layer	Technology	Purpose
Frontend	React 19 (Vite)	Component-based UI with concurrent rendering
Routing	TanStack Router v1	Type-safe file-based routing with auth guards
Server State	TanStack Query v5	Intelligent caching, background refetch, query invalidation
Forms	TanStack Form + Zod	Schema-driven validation with headless form state
Styling	Tailwind CSS v4	Utility-first styling with dark theme
Charts	Recharts	Composable chart components for analytics
HTTP Client	Custom apiFetch	Lightweight fetch wrapper with JWT injection and auto-refresh
Backend	NestJS 11	Modular architecture with decorators, DI, guards, and pipes
ORM	MikroORM 6	Unit-of-Work pattern with native MongoDB support
Database	MongoDB (Atlas)	Flexible document model with horizontal scaling
Auth	Passport.js + JWT	Stateless authentication with refresh token rotation
Validation	class-validator	Declarative DTO validation with NestJS ValidationPipe

---

Project Structure

sioms/
├── apps/
│   ├── backend/                  # NestJS application
│   │   └── src/
│   │       ├── auth/             # JWT strategy, login/signup, guards, decorators
│   │       ├── users/            # User entity, service, password hashing
│   │       ├── categories/       # Category CRUD with uniqueness enforcement
│   │       ├── products/         # Product CRUD, auto-status management
│   │       ├── orders/           # Order lifecycle, conflict detection, stock ops
│   │       ├── restock/          # Low-stock queue, priority calculation
│   │       ├── activity-log/     # Append-only event log
│   │       ├── dashboard/        # Aggregated KPIs and analytics
│   │       ├── common/           # Global filters, interceptors
│   │       └── seed/             # Database seed script
│   │
│   └── frontend/                 # React application
│       └── src/
│           ├── routes/           # TanStack Router (file-based)
│           │   ├── login.tsx
│           │   ├── signup.tsx
│           │   └── app/          # Auth-guarded routes
│           │       ├── dashboard.tsx
│           │       ├── products/
│           │       ├── orders/
│           │       └── restock/
│           ├── api/              # apiFetch client with JWT handling
│           ├── hooks/            # TanStack Query hooks per domain
│           ├── lib/              # Auth helpers, query client, query keys
│           └── types/            # Shared TypeScript interfaces
│
├── package.json                  # npm workspaces root
└── .gitignore

---

API Endpoints

Auth

Method	Endpoint	Auth	Description
POST	/api/auth/signup	Public	Register new user
POST	/api/auth/login	Public	Login, returns tokens + user
POST	/api/auth/refresh	Token	Exchange refresh for new access token
POST	/api/auth/logout	JWT	Invalidate refresh token
GET	/api/auth/me	JWT	Get current user profile

Categories

Method	Endpoint	Auth	Description
POST	/api/categories	Admin	Create category (unique name)
GET	/api/categories	JWT	List all categories
GET	/api/categories/:id	JWT	Get single category
PATCH	/api/categories/:id	Admin	Update category
DELETE	/api/categories/:id	Admin	Delete (blocked if products assigned)

Products

Method	Endpoint	Auth	Description
POST	/api/products	Admin	Create product
GET	/api/products	JWT	List with ?search= ?category= ?status= ?page= ?limit=
GET	/api/products/:id	JWT	Get single product
PATCH	/api/products/:id	Admin	Update product
DELETE	/api/products/:id	Admin	Delete (blocked if on active orders)

Orders

Method	Endpoint	Auth	Description
POST	/api/orders	JWT	Create order with stock deduction
GET	/api/orders	JWT	List with ?status= ?from= ?to= ?search= ?page= ?limit=
GET	/api/orders/:id	JWT	Get single order
PATCH	/api/orders/:id/status	JWT	Update status (validates transitions)
DELETE	/api/orders/:id	Admin	Delete (only cancelled orders)

Restock Queue

Method	Endpoint	Auth	Description
GET	/api/restock	JWT	List queue sorted by priority
PATCH	/api/restock/:id/restock	JWT	Add stock, auto-resolve if above threshold
DELETE	/api/restock/:id	Admin	Remove from queue

Dashboard

Method	Endpoint	Auth	Description
GET	/api/dashboard	JWT	KPI summary
GET	/api/dashboard/analytics	JWT	7-day order & revenue trend
GET	/api/activity-log	JWT	Latest activity entries (?limit=)

---

Getting Started (Local Development)

Prerequisites

• Node.js 20+
• MongoDB (local or Atlas)

Setup

# Clone
git clone https://github.com/ProgrammerShahJalal/sioms.git
cd sioms

# Install all dependencies
npm install

# Configure backend environment
cp apps/backend/.env.example apps/backend/.env
# Edit apps/backend/.env with your MongoDB URI and secrets

# Seed the database
npm run seed

# Start backend (terminal 1)
npm run backend:dev

# Start frontend (terminal 2)
npm run frontend:dev

Frontend runs at http://localhost:5173, backend at http://localhost:3000.

Environment Variables

Backend (apps/backend/.env):

PORT=3000
MONGODB_URI=mongodb://localhost:27017/sioms
JWT_ACCESS_SECRET=your-secret-here
JWT_REFRESH_SECRET=your-other-secret-here
JWT_ACCESS_EXPIRY=15m
JWT_REFRESH_EXPIRY=7d
CORS_ORIGIN=http://localhost:5173
DEMO_EMAIL=demo@sioms.app
DEMO_PASSWORD=Demo@1234

Frontend (apps/frontend/.env):

VITE_API_URL=http://localhost:3000/api

---

Deployment

Service	Platform	Configuration
Frontend	Vercel	Root: apps/frontend, Framework: Vite
Backend	Render	Root: apps/backend, Build: npm install && npm run build, Start: node dist/main
Database	MongoDB Atlas	Free M0 cluster

---

Order Status Workflow

┌─────────┐    ┌───────────┐    ┌─────────┐    ┌───────────┐
│ Pending  │───→│ Confirmed │───→│ Shipped │───→│ Delivered │
└────┬─────┘    └─────┬─────┘    └─────────┘    └───────────┘
     │                │
     └───────┬────────┘
             ▼
      ┌────────────┐
      │ Cancelled  │  ← stock restored
      └────────────┘

---

License

This project is for educational and demonstration purposes.