Lead Management System (LMS)

A full-stack Lead Management System built with the MERN stack (MongoDB, Express.js, React, Node.js) to help businesses capture, manage, track, and convert leads into customers.

🚀 Features

Core Features

• Authentication & Authorization: JWT-based authentication with role-based access control
• Lead Management: Complete CRUD operations for leads with advanced filtering and search
• Lead Scoring: Automatic lead scoring based on various factors
• Status Pipeline: Customizable lead status workflow (New → Contacted → Qualified → Negotiation → Closed Won/Lost)
• User Management: Team member management with different roles (Admin, Sales Manager, Sales Executive)
• Communication Tracking: Log and track all interactions with leads
• Analytics Dashboard: Visual insights and performance metrics
• Role-based Permissions: Different access levels based on user roles

Advanced Features

• Lead Assignment: Assign leads to team members
• Bulk Operations: Bulk assign leads to users
• Overdue Tracking: Track overdue follow-ups and tasks
• Real-time Notifications: In-app notifications for important events
• Responsive Design: Mobile-friendly interface
• Data Export: Export leads and reports

🛠️ Tech Stack

Backend

• Node.js - Runtime environment
• Express.js - Web framework
• MongoDB - Database
• Mongoose - ODM for MongoDB
• JWT - Authentication
• bcryptjs - Password hashing
• express-validator - Input validation
• cors - Cross-origin resource sharing
• dotenv - Environment variables

Frontend

• React - UI library
• Vite - Build tool
• Redux Toolkit - State management
• React Router - Routing
• Tailwind CSS - Styling
• shadcn/ui - UI components
• Lucide React - Icons
• React Hook Form - Form handling
• Zod - Schema validation
• Axios - HTTP client
• Sonner - Toast notifications

📁 Project Structure

lead-management-system/
├── backend/
│   ├── config/
│   │   └── database.js
│   ├── controllers/
│   │   ├── authController.js
│   │   ├── leadController.js
│   │   ├── userController.js
│   │   └── interactionController.js
│   ├── middleware/
│   │   ├── auth.js
│   │   └── validation.js
│   ├── models/
│   │   ├── User.js
│   │   ├── Lead.js
│   │   └── Interaction.js
│   ├── routes/
│   │   ├── auth.js
│   │   ├── users.js
│   │   ├── leads.js
│   │   └── interactions.js
│   ├── utils/
│   ├── uploads/
│   ├── .env
│   ├── server.js
│   └── package.json
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   ├── ui/
│   │   │   ├── Layout.jsx
│   │   │   ├── AuthLayout.jsx
│   │   │   ├── Sidebar.jsx
│   │   │   └── Header.jsx
│   │   ├── pages/
│   │   │   ├── auth/
│   │   │   │   ├── Login.jsx
│   │   │   │   └── Register.jsx
│   │   │   ├── leads/
│   │   │   ├── users/
│   │   │   ├── Dashboard.jsx
│   │   │   ├── Profile.jsx
│   │   │   └── Analytics.jsx
│   │   ├── store/
│   │   │   ├── slices/
│   │   │   │   ├── authSlice.js
│   │   │   │   ├── leadSlice.js
│   │   │   │   ├── userSlice.js
│   │   │   │   └── interactionSlice.js
│   │   │   └── store.js
│   │   ├── hooks/
│   │   ├── lib/
│   │   ├── App.jsx
│   │   └── main.jsx
│   ├── .env
│   ├── package.json
│   └── vite.config.js
└── README.md

🚦 Getting Started

Prerequisites

• Node.js (v18 or higher)
• MongoDB (local or MongoDB Atlas)
• npm or pnpm

Installation

1. Clone the repository

   git clone <repository-url>
   cd lead-management-system

2. Backend Setup

   cd backend
   npm install
   
   # Create .env file
   cp .env.example .env
   # Edit .env with your configuration
   
   # Start the server
   npm run dev

3. Frontend Setup

   cd frontend
   pnpm install
   
   # Create .env file
   echo "VITE_API_URL=http://localhost:5000/api" > .env
   
   # Start the development server
   pnpm run dev

Environment Variables

Backend (.env)

NODE_ENV=development
PORT=5000
MONGODB_URI=mongodb://localhost:27017/lead_management_system
JWT_SECRET=your_jwt_secret_key_here
JWT_EXPIRE=30d
CLIENT_URL=http://localhost:3000

# Email Configuration (SendGrid)
SENDGRID_API_KEY=your_sendgrid_api_key_here
FROM_EMAIL=[email protected]

# Twilio Configuration (SMS/WhatsApp)
TWILIO_ACCOUNT_SID=your_twilio_account_sid_here
TWILIO_AUTH_TOKEN=your_twilio_auth_token_here
TWILIO_PHONE_NUMBER=your_twilio_phone_number_here

Frontend (.env)

VITE_API_URL=http://localhost:5000/api

🔐 User Roles & Permissions

Admin

• Full system access
• User management (create, update, delete users)
• All lead operations
• System analytics and reports
• Role assignment

Sales Manager

• User management (create, update users)
• All lead operations
• Team analytics and reports
• Lead assignment
• View all team activities

Sales Executive

• Personal lead management
• View assigned leads only
• Create and update own interactions
• Personal performance metrics

📚 API Documentation

Authentication Endpoints

POST /api/auth/register

Register a new user

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "[email protected]",
  "password": "password123",
  "role": "Sales Executive",
  "phone": "+1234567890",
  "department": "Sales"
}

POST /api/auth/login

Login user

{
  "email": "[email protected]",
  "password": "password123"
}

GET /api/auth/me

Get current user profile (Protected)

PUT /api/auth/profile

Update user profile (Protected)

PUT /api/auth/change-password

Change password (Protected)

Lead Endpoints

GET /api/leads

Get all leads with filtering and pagination (Protected) Query parameters:

• page: Page number
• limit: Items per page
• search: Search term
• status: Lead status
• source: Lead source
• priority: Lead priority
• assignedTo: Assigned user ID

POST /api/leads

Create new lead (Protected)

{
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "[email protected]",
  "phone": "+1234567890",
  "company": "ABC Corp",
  "source": "Website",
  "assignedTo": "user_id"
}

GET /api/leads/:id

Get single lead (Protected)

PUT /api/leads/:id

Update lead (Protected)

DELETE /api/leads/:id

Delete lead (Admin/Manager only)

GET /api/leads/stats

Get lead statistics (Protected)

GET /api/leads/overdue

Get overdue leads (Protected)

PUT /api/leads/bulk-assign

Bulk assign leads (Admin/Manager only)

User Endpoints

GET /api/users

Get all users (Admin/Manager only)

POST /api/users

Create new user (Admin/Manager only)

GET /api/users/:id

Get single user (Protected)

PUT /api/users/:id

Update user (Protected)

DELETE /api/users/:id

Delete user (Admin only)

GET /api/users/stats

Get user statistics (Admin/Manager only)

Interaction Endpoints

GET /api/interactions

Get all interactions (Protected)

POST /api/interactions

Create new interaction (Protected)

GET /api/interactions/:id

Get single interaction (Protected)

PUT /api/interactions/:id

Update interaction (Protected)

DELETE /api/interactions/:id

Delete interaction (Protected)

GET /api/interactions/lead/:leadId

Get interactions for specific lead (Protected)

GET /api/interactions/upcoming

Get upcoming tasks (Protected)

GET /api/interactions/overdue

Get overdue tasks (Protected)

GET /api/interactions/stats

Get interaction statistics (Protected)

🎨 UI Components

The application uses a modern, responsive design with:

• Dark/Light theme support
• Mobile-first responsive design
• Accessible components
• Consistent design system
• Professional color palette
• Smooth animations and transitions

🚀 Deployment

Backend Deployment

1. Set up MongoDB Atlas or your preferred MongoDB hosting
2. Configure environment variables for production
3. Deploy to platforms like Heroku, Railway, or AWS
4. Ensure CORS is configured for your frontend domain

Frontend Deployment

1. Build the production version:

   pnpm run build

2. Deploy the dist folder to platforms like Vercel, Netlify, or AWS S3
3. Configure environment variables for production API URL

🧪 Testing

Backend Testing

cd backend
npm test

Frontend Testing

cd frontend
pnpm test

📈 Performance Optimizations

• Database indexing for faster queries
• Pagination for large datasets
• Lazy loading for React components
• Memoization for expensive calculations
• Optimized bundle size with code splitting
• Caching strategies for API responses

🔒 Security Features

• JWT token authentication
• Password hashing with bcrypt
• Input validation and sanitization
• CORS protection
• Rate limiting (recommended for production)
• Environment variable protection
• Role-based access control

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

This project is licensed under the MIT License.

🆘 Support

For support and questions:

• Create an issue in the repository
• Contact the development team
• Check the documentation

🗺️ Roadmap

Upcoming Features

• Email integration (SendGrid)
• SMS/WhatsApp integration (Twilio)
• Advanced analytics and reporting
• CSV import/export functionality
• Kanban board for lead pipeline
• Calendar integration
• Mobile app (React Native)
• API rate limiting
• Advanced search with Elasticsearch
• Real-time notifications with WebSocket

---

Built with ❤️ using the MERN stack