Overview • Features • Tech Stack • Architecture • Getting Started • API Reference • Contributing

---

📖 Overview

ExpireX is a full-stack MERN (MongoDB, Express, React, Node.js) application that helps individuals and small businesses keep track of perishable or time-sensitive inventory — food, medicine, cosmetics, documents, anything with a shelf life.

The app automatically flags items that are fresh, expiring soon, or expired, sends email reminders on a schedule, and gives you a clean dashboard with charts to visualize your inventory health at a glance.

💡 Built with a clean MVC (Model–View–Controller) architecture on the backend and a modern component-based React frontend — designed to be easy to read, extend, and deploy.

🔗 Live Demo  ·  API Base URL

🎥 Tip: Record a 10–15s screen capture of the dashboard/add-item flow, convert it to a GIF (ScreenToGif / Kap), drop it in a docs/ or .github/assets/ folder, and embed it below — a live animated preview is the single highest-impact thing you can add for recruiters skimming your repo.

![ExpireX demo](./.github/assets/demo.gif)

---

✨ Features

🔐 Auth	JWT-based register/login, forgot & reset password via email
📦 Inventory CRUD	Add, edit, delete, and search items with category & quantity tracking
⏰ Expiry Intelligence	Auto-classification into Fresh, Expiring Soon, and Expired
🔔 Notifications	In-app notification bell + automated email reminders via cron jobs
🗑️ Auto Cleanup	Scheduled job archives expired items and removes stale entries
📊 Dashboard	Bar & pie charts (Chart.js) showing category distribution and status breakdown
🌗 Theming	Light/dark mode via React Context
📱 Responsive UI	TailwindCSS + Framer Motion for a smooth, mobile-friendly experience
🚀 CI/CD Ready	GitHub Actions workflow to install, build, and test on every push

---

🛠 Tech Stack

Layer	Technology
Frontend	React 19, Vite, React Router 7, TailwindCSS, Chart.js, Axios, Framer Motion, React Hot Toast
Backend	Node.js, Express 4, JWT, Bcrypt.js
Database	MongoDB with Mongoose ODM
Scheduling	node-cron
Email	Nodemailer (Gmail transport)
CI/CD	GitHub Actions
Deployment	Render (API) · Vercel (Client)

---

🏗 Architecture & MVC Workflow

ExpireX is split into two independent apps that talk to each other over a REST API:

ExpireX/
├── backend/     → Node + Express API (MVC pattern)
└── frontend/    → React + Vite SPA (Component/Context pattern)

Backend — MVC breakdown

backend/
├── models/          # M — Mongoose schemas (data + validation)
│   ├── User.js
│   ├── Item.js
│   ├── ExpiredItem.js
│   └── Notification.js
│
├── controllers/      # C — Business logic that talks to Models
│   ├── authController.js         (register, login, profile , password reset)
│   ├── itemController.js         (CRUD for inventory items)
│   ├── expiredController.js      (fetch archived/expired items)
│   ├── notificationController.js (list, read, delete notifications)
│   └── dashboardController.js    (aggregate stats for charts)
│
├── routes/            # HTTP endpoints → wire URLs to Controllers
│   ├── authRoutes.js        → /api/auth
│   ├── itemRoutes.js        → /api/items
│   ├── expiredRoutes.js     → /api/expired
│   ├── notificationRoutes.js→ /api/notifications
│   └── dashboardRoutes.js   → /api/dashboard
│
├── middleware/
│   ├── authMiddleware.js    # protects routes via JWT (req.user)
│   └── errorMiddleware.js   # centralized error handler
│
├── services/
│   └── emailService.js      # nodemailer templates (welcome, reminder, reset)
│
├── cron/
│   ├── expiryReminderCron.js # daily job → emails users about items expiring soon
│   └── deleteExpiredCron.js  # daily job → archives/removes expired items
│
├── config/
│   ├── db.js           # MongoDB connection
│   └── mailConfig.js    # Nodemailer transporter setup
│
├── app.js       # Express app: middleware + route mounting
└── server.js    # Entry point: connects DB, starts cron jobs, starts server

Request lifecycle (the "V" is the JSON response consumed by React):

Client (React)
   │  axios request + JWT
   ▼
Route  ──▶  Middleware (authMiddleware)  ──▶  Controller  ──▶  Model (Mongoose)  ──▶  MongoDB
   ▲                                                                                     │
   └────────────────────────── JSON response ◀── errorMiddleware ◀───────────────────────┘

ℹ️ Note: expiredRoutes.js exists in the codebase to expose expired-item history; make sure it's mounted in app.js (app.use("/api/expired", expiredRoutes)) if you want that endpoint active.

Frontend — component structure

frontend/src/
├── pages/          # Route-level screens (Dashboard, ItemList, Login, Profile...)
├── components/
│   ├── common/      # Reusable UI: Button, InputField, Loader, ExpiryBadge...
│   ├── layout/      # Navbar, Sidebar, Footer, DashboardLayout
│   └── dashboard/    # ItemCard, ItemForm, BarChartCard, PieChartCard...
├── context/         # AuthContext, ThemeContext, NotificationContext
├── services/        # api.js (axios instance) + authService/itemService/...
├── hooks/           # useFetch, useDebounce, usePagination, useLocalStorage...
├── routes/          # AppRoutes.jsx — route definitions + ProtectedRoute
└── utils/           # constants, validators, expiryUtils, helpers

---

🚀 Getting Started

Prerequisites

• Node.js ≥ 18 (project tested with Node 20)
• MongoDB — local instance or a free MongoDB Atlas cluster
• A Gmail account (with an App Password) for sending emails — or swap mailConfig.js for another provider

1. Clone the repository

git clone https://github.com/<your-username>/ExpireX.git
cd ExpireX

2. Backend setup

cd backend
npm install

Create a .env file inside backend/:

PORT=5000
MONGO_URI=your_mongodb_connection_string
JWT_SECRET=your_super_secret_jwt_key
EMAIL_USER=your_gmail_address@gmail.com
EMAIL_PASS=your_gmail_app_password
FRONTEND_URL=http://localhost:5173
NODE_ENV=development

Run the API:

npm run dev     # nodemon, hot-reload
# or
npm start        # plain node

The server boots on http://localhost:5000, connects to MongoDB, and starts both cron jobs (expiry reminders + expired-item cleanup).

3. Frontend setup

Open a new terminal:

cd frontend
npm install

Create/update .env inside frontend/:

VITE_API_URL=http://localhost:5000/api

Run the client:

npm run dev

Visit http://localhost:5173 in your browser. 🎉

4. Build for production

# frontend
cd frontend
npm run build      # outputs to frontend/dist

# backend — just run
cd backend
npm start

---

⏱ Automated Jobs

Cron Job	File	What it does
Expiry Reminder	cron/expiryReminderCron.js	Runs daily, scans items nearing their expiry date, and emails the owner a reminder
Expired Cleanup	cron/deleteExpiredCron.js	Runs daily, moves items past their expiry date into the ExpiredItem archive and cleans active listings

---

📡 API Reference

Base URL: http://localhost:5000/api

🔐 Auth — /auth

Method	Endpoint	Description	Auth
POST	/auth/register	Register a new user	❌
POST	/auth/login	Log in, receive JWT	❌
GET	/auth/profile	Get current user profile	✅
PUT	/auth/profile	Update profile	✅
PUT	/auth/change-password	Change password	✅
POST	/auth/forgot-password	Request password reset email	❌
POST	/auth/reset-password/:token	Reset password with token	❌

📦 Items — /items

Method	Endpoint	Description	Auth
POST	/items	Add a new item	✅
GET	/items	List all items for the user	✅
GET	/items/:id	Get a single item	✅
PUT	/items/:id	Update an item	✅
DELETE	/items/:id	Delete an item	✅

🗑️ Expired — /expired

Method	Endpoint	Description	Auth
GET	/expired	List archived/expired items	✅

🔔 Notifications — /notifications

Method	Endpoint	Description	Auth
GET	/notifications	List notifications	✅
PUT	/notifications/read-all	Mark all as read	✅
PUT	/notifications/:id	Mark one as read	✅
DELETE	/notifications/:id	Delete a notification	✅

📊 Dashboard — /dashboard

Method	Endpoint	Description	Auth
GET	/dashboard/stats	Aggregate stats: total items, fresh/expiring/expired counts, category distribution	✅

✅ = requires Authorization: Bearer <token> header (set automatically by the frontend AuthContext after login).

---

🔄 CI/CD

A GitHub Actions workflow (.github/workflows/ci-cd.yml) runs on every push to main:

1. Checks out the code
2. Installs backend dependencies + runs tests (if present)
3. Installs frontend dependencies
4. Builds the frontend
5. Reports pipeline success ✅

---

🗺 Roadmap

• Barcode/QR scanning for quick item entry
• Push notifications (Web Push / mobile)
• Multi-user households / shared inventories
• Export inventory reports (CSV/PDF)
• Unit & integration test suite

---

🤝 Contributing

Contributions are what make the open-source community amazing! Any contributions are greatly appreciated.

1. Fork the project
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

📄 License

Distributed under the MIT License. See LICENSE for more information.

---

⬆ Back to top