DonateNow - NGO Donation Management System

A full-stack web application for managing donations to NGOs with PayPal integration, user authentication, email verification, and comprehensive admin dashboard.

📋 Table of Contents

• Features
• Tech Stack
• Prerequisites
• Installation
• Configuration
• Running the Application
• Usage Guide
• Project Structure
• API Endpoints
• Security Features
• Troubleshooting

✨ Features

User Features

• Secure Registration & Login with email verification
• Email Verification via OTP (One-Time Password)
• Password Management - Change password anytime, Reset via email
• PayPal Integration for secure donations (Sandbox & Live)
• Donation History with receipt download (PDF)
• Profile Management - Update personal information
• Dark Mode Support for better user experience

Admin Features

• User Management - View, search, and export user data
• Donation Management - Monitor all donations with filters
• Analytics Dashboard - Visual insights with charts
• Campaign Tracking - Track fundraising goals and progress
• CSV Export - Export user and donation data
• PDF Reports - Generate campaign reports
• Receipt Management - Download receipts for user donations

🛠 Tech Stack

Frontend

• React 18+ with TypeScript
• Vite for fast development
• Tailwind CSS for styling
• Recharts for data visualization
• PayPal SDK for payment integration
• jsPDF for receipt generation
• Lucide React for icons
• date-fns for date formatting

Backend

• Node.js with Express
• TypeScript for type safety
• MongoDB with Mongoose ODM
• JWT for authentication
• bcryptjs for password hashing
• Nodemailer for email services
• express-validator for input validation
• express-rate-limit for API protection

📋 Prerequisites

Before you begin, ensure you have the following installed:

• Node.js (v16 or higher)
• npm or yarn
• MongoDB Atlas account (or local MongoDB)
• PayPal Developer account
• Gmail account (for sending emails)

📦 Installation

1. Clone the Repository

git clone <repository-url>
cd donatenow

2. Install Dependencies

Backend:

cd server
npm install

Frontend:

cd ..
npm install

⚙️ Configuration

1. MongoDB Setup

1. Go to MongoDB Atlas
2. Create a free cluster
3. Create a database user
4. Whitelist your IP address (or use 0.0.0.0/0 for development)
5. Get your connection string

2. PayPal Setup

1. Go to PayPal Developer Dashboard
2. Create a Sandbox account
3. Create a REST API app
4. Copy your Client ID and Secret

3. Gmail Setup (for Email Notifications)

1. Go to Google Account Security
2. Enable 2-Step Verification
3. Go to App Passwords
4. Create a new app password for "Mail"
5. Copy the generated password (16 characters)

4. Environment Variables

Create a .env file in the server directory:

# Server Configuration
PORT=5000
NODE_ENV=development

# MongoDB Connection
MONGODB_URI=your_mongodb_connection_string_here

# JWT Secret (generate a random string)
JWT_SECRET=your_secure_random_jwt_secret_here

# Admin Secret Code (for admin registration)
ADMIN_SECRET_CODE=ADMIN2026

# PayPal Configuration
PAYPAL_CLIENT_ID=your_paypal_client_id_here
PAYPAL_CLIENT_SECRET=your_paypal_client_secret_here
PAYPAL_MODE=sandbox

# Email Configuration (Gmail)
EMAIL_SERVICE=gmail
EMAIL_USER=your_gmail_address@gmail.com
EMAIL_PASS=your_16_character_app_password
EMAIL_FROM=DonateNow <your_gmail_address@gmail.com>

Important Notes:

• Replace all your_*_here values with your actual credentials
• Never commit the .env file to version control
• Use PAYPAL_MODE=live for production
• For JWT_SECRET, use a long random string (e.g., generated via openssl rand -hex 64)

🚀 Running the Application

Development Mode

Terminal 1 - Backend:

cd server
npm run dev

Server will start on http://localhost:5000

Terminal 2 - Frontend:

npm run dev

Frontend will start on http://localhost:3000 or http://localhost:3001

Production Build

Frontend:

npm run build
npm run preview

Backend:

cd server
npm run build
npm start

📖 Usage Guide

For Users

1. Registration

1. Navigate to the registration page
2. Fill in your details:
   • Full Name
   • Email
   • Mobile Number
   • City
   • Password (min 4 characters)
3. Submit the form
4. Check your email for a 6-digit OTP
5. Enter the OTP on the verification page (valid for 10 minutes)
6. Account created successfully!

2. Login

1. Enter your email and password
2. Click "Forgot Password?" if you forgot your password
3. Access your dashboard

3. Make a Donation

1. From your dashboard, select or enter an amount
2. Add an optional message
3. Click "Donate Now"
4. Complete payment via PayPal Sandbox
5. Download your receipt after successful payment

4. Change Password

1. Go to your profile section
2. Click "Change Password"
3. Enter current password and new password
   • Must be at least 12 characters
   • Include uppercase, lowercase, and special character
4. Save changes

For Administrators

1. Admin Registration

1. Use the regular registration form
2. Enter the admin secret code: ADMIN2026
3. Complete email verification
4. Login to access admin dashboard

2. Admin Dashboard Features

• Overview Tab: View key metrics and charts
• Users Tab: Manage users, search, filter, export CSV
• Donations Tab: Monitor donations with filters by status and date
• Download Reports: Generate PDF campaign reports
• Change Password: Update admin password securely

📁 Project Structure

donatenow/
├── server/                 # Backend Express server
│   ├── src/
│   │   ├── models/        # Mongoose models
│   │   ├── routes/        # API routes
│   │   ├── services/      # Business logic (email, etc.)
│   │   ├── middleware/    # Auth middleware
│   │   └── server.ts      # Server entry point
│   ├── .env              # Environment variables
│   └── package.json
│
├── pages/                 # React pages/components
│   ├── Home.tsx
│   ├── Login.tsx
│   ├── Register.tsx
│   ├── VerifyEmail.tsx
│   ├── UserDashboard.tsx
│   └── AdminDashboard.tsx
│
├── components/           # Reusable components
│   ├── ui/              # UI components
│   └── ChangePasswordModal.tsx
│
├── services/            # Frontend services
│   └── apiService.ts    # API calls
│
└── types.ts             # TypeScript types

🔌 API Endpoints

Authentication

• POST /api/auth/register - Register new user
• POST /api/auth/login - User login
• GET /api/auth/me - Get current user

Email Verification

• POST /api/verification/verify-otp - Verify OTP and create account
• POST /api/verification/resend-otp - Resend OTP

Password Management

• POST /api/password-reset/request - Request password reset
• POST /api/change-password/change-password - Change password

Donations

• GET /api/donations - Get user donations
• POST /api/donations - Create donation
• PATCH /api/donations/:id/status - Update donation status

PayPal

• POST /api/paypal/create-order - Create PayPal order
• POST /api/paypal/capture-payment - Capture payment

Admin

• GET /api/users - Get all users
• PUT /api/users/:id - Update user
• DELETE /api/users/:id - Delete user
• GET /api/campaign - Get campaign data

🔒 Security Features

• Password Hashing: bcrypt with salt rounds
• JWT Authentication: Secure token-based auth
• Email Verification: OTP-based account verification
• Rate Limiting: Protect against brute force attacks
• Input Validation: Server-side validation with express-validator
• XSS Protection: Sanitized inputs
• CORS: Configured for security
• Environment Variables: Sensitive data not in code

🛠 Troubleshooting

Email Not Sending

Issue: Verification emails not arriving

Solutions:

1. Verify Gmail App Password is correct
2. Check spam/junk folder
3. Ensure 2-Step Verification is enabled on Gmail
4. Verify EMAIL_USER and EMAIL_PASS in .env
5. Restart the backend server after changing .env

PayPal Payment Fails

Issue: Payment not processing

Solutions:

1. Verify PayPal credentials in .env
2. Check if using Sandbox account for testing
3. Ensure PAYPAL_MODE=sandbox for development
4. Check PayPal Developer Dashboard for errors

MongoDB Connection Error

Issue: Cannot connect to database

Solutions:

1. Check MongoDB URI is correct
2. Verify IP whitelist in MongoDB Atlas
3. Ensure database user credentials are correct
4. Check network connectivity

Port Already in Use

Issue: Port 5000 or 3000 already occupied

Solutions:

# Windows
netstat -ano | findstr :5000
taskkill /PID <PID> /F

# Change port in server/.env or vite.config.ts

📝 License

This project is for educational purposes.

🤝 Support

For issues or questions:

1. Check this README
2. Review error logs in terminal
3. Verify environment variables
4. Check MongoDB and PayPal dashboards

🎯 Development Tips

• Use PayPal Sandbox for testing
• Test email verification with a real email
• Check browser console for frontend errors
• Monitor server terminal for backend logs
• Use MongoDB Compass to view database

---

Made with ❤️ for making donations simple and transparent