Samarpan - Blood Donor Connection Platform

Connect Donors, Save Lives – A real-time blood and platelet donor connection platform that brings donors and patients together.

Live Demo • Report Bug • Request Feature

🆕 Latest Updates (January 2026)

🔧 QR Scanner System - FIXED

✅ Runtime Error Resolution: Fixed "HTML Element with id=admin-qr-reader not found" error
✅ Robust DOM Handling: Implemented proper element waiting pattern with retry logic
✅ Enhanced Camera Initialization: Added safety checks and improved cleanup with error handling
✅ Element Validation: Added validation before scanner creation with retry mechanism
✅ Production Ready: QR scanners now work reliably in both admin QR checker and event attendance scanner

🚀 Deployment System - ENHANCED

✅ Vercel Compatibility: Resolved "Cannot install with 'frozen-lockfile'" deployment error
✅ Dependency Cleanup: Removed problematic baseline-browser-mapping dependency
✅ Lockfile Management: Updated .gitignore to prevent future lockfile conflicts
✅ Build Optimization: Created fresh npm lockfile and proper .vercelignore configuration
✅ Deployment Ready: Seamless deployment to Vercel with zero configuration issues

🛠️ Comprehensive Maintenance System - NEW

✅ Beautiful Samarpan Loader: Animated blood drop with rotating rings, multiple size variants
✅ Modern Maintenance Page: Light theme design with real-time clock and duration tracking
✅ Complete Route Protection: Middleware blocks ALL routes during maintenance except admin and static assets
✅ Smart Navbar Integration: Auto-hiding navigation with maintenance indicator
✅ Priority-Based Styling: Different colors and messages for maintenance priority levels (low, medium, high, critical)
✅ Real-Time Updates: 30-second auto-refresh with connection status monitoring
✅ Mobile Responsive: Perfect experience across all devices
✅ Professional Design: Glass morphism effects with light theme consistency

🎨 Visual Enhancements

✅ Blood PNG Integration: Custom blood drop image in maintenance loader
✅ Perfect Center Alignment: Maintenance indicator absolutely centered with loader
✅ Light Theme Consistency: Maintenance page matches site's current light theme
✅ Responsive Navbar: Smart hiding of navigation elements during maintenance
✅ Professional Animations: Smooth transitions and GPU-accelerated effects

🎯 About Samarpan

Samarpan is a comprehensive blood donation management platform designed to connect donors with patients in need of blood and platelets. Built with modern web technologies, it enables real-time connections, efficient donor management, and streamlined administrative operations.

Key Features

👥 Donor & Patient Features

Real-Time Connections – Instantly connect blood donors with patients in need
User Authentication – Secure signup, login, and password management
Donation Tracking – Track your blood donation history and earn certificates
Request Management – Create and manage blood requests with priority levels
Event Participation – Join upcoming blood donation events in your area
Notifications – Real-time alerts for matching blood requests
User Dashboard – Comprehensive profile and activity management
Certificate Generation – Automatic certificate creation for donors

🛡️ Admin Features

Admin Panel – Centralized dashboard for system management
User Management – View and manage all registered users
Donation Management – Track and verify all donations
Request Management – Review and approve blood requests
Event Management – Create and manage blood donation events
QR Code Scanning – Reliable QR code scanning for event check-ins
Transportation Coordination – Manage transportation logistics
Notification System – Send bulk notifications to users
Image Management – View and manage donation images
Contact Submissions – Review and respond to user inquiries
Certificate Management – Generate and track donor certificates
Maintenance Mode – Professional maintenance system with real-time monitoring

🔧 System Administration

Maintenance System – Complete maintenance mode with route protection
Real-Time Monitoring – Auto-refresh maintenance status every 30 seconds
Priority Management – Different maintenance levels (low, medium, high, critical)
IP Whitelisting – Allow specific IPs to bypass maintenance mode
Emergency Access – Secret key bypass for emergency access
Professional UI – Beautiful maintenance page with Samarpan branding

👥 NGO Staff Guide

Getting Started as NGO Staff

Access the Admin Panel
- Visit /admin/login in your browser
- Use the default credentials:
  - Email: admin@samarpan.com
  - Password: admin@123
- Change your password immediately after first login
Understanding the Dashboard
- User Management: View and manage all registered donors
- Event Management: Create and manage blood donation events
- Donation Tracking: Monitor donation activities and certificates
- Notifications: Send bulk notifications to users
- Maintenance Mode: Enable/disable maintenance with custom messages

Key Operations for NGO Staff

Managing Events

Create Events: Go to Admin Dashboard → Events → Create New Event
Set Event Details: Title, date, location, volunteer slots needed
Monitor Registrations: View donor registrations and QR codes
QR Code Scanning: Use reliable QR scanner for event check-ins
Track Donations: Update donation status and blood test results

Managing Donors

View Donor List: Admin Dashboard → Users → View all registered users
Event Donors: Events → Select Event → View Registered Donors
QR Verification: Scan donor QR codes for attendance verification
Update Blood Types: After blood testing, update donor blood types
Generate Certificates: Automatically generate donation certificates

Maintenance Management

Enable Maintenance: Admin Dashboard → Maintenance Mode
Set Priority Level: Choose from low, medium, high, or critical
Custom Messages: Add specific maintenance messages for users
IP Whitelisting: Allow specific IPs to bypass maintenance
Emergency Access: Set secret keys for emergency bypass
Real-Time Monitoring: View maintenance duration and auto-refresh status

Blood Donation Process

Event Creation: Create event with date, time slots, and location
Donor Registration: Donors register through the public portal
Check-in Process: Use QR codes to verify donor arrival (now working reliably)
Blood Testing: Update blood types after lab results
Certificate Generation: Generate certificates for completed donations

Important Settings

Environment Variables: Ensure all required environment variables are set
Email Configuration: Set up email service for notifications
Database Backup: Regular backups of MongoDB data
Admin Permissions: Assign appropriate permissions to staff members
Maintenance Settings: Configure maintenance mode parameters

Troubleshooting

Can't access admin panel: Check login credentials and permissions
Events not showing: Verify event dates and status
QR codes not working: ✅ FIXED - QR scanners now work reliably
Email notifications failing: Check email service configuration
Maintenance mode issues: ✅ NEW - Complete maintenance system available
Deployment failures: ✅ FIXED - Vercel deployment now works seamlessly

🛠️ Tech Stack

Frontend

Framework: Next.js 16 with App Router
UI Library: React 19
Language: TypeScript 5
Styling: Tailwind CSS 4 + Radix UI components
State Management: Redux Toolkit
Form Handling: React Hook Form + Zod validation
Charts: Recharts
Icons: Lucide React
PDF Generation: PDFKit & PDF-Lib
QR Code Scanning: html5-qrcode (enhanced with robust error handling)

Backend

Runtime: Node.js (Next.js Server)
Database: MongoDB 6.20
Authentication: JWT + bcryptjs
Email: Nodemailer
Cloud Storage: AWS S3 (via AWS SDK)
PDF Processing: PDFKit
Maintenance System: Custom middleware with route protection

Development

Package Manager: npm/pnpm
Build Tool: Next.js (Turbopack)
Linting: ESLint
Environment: Node.js 18+
Deployment: Vercel (optimized configuration)

🚀 Getting Started

Prerequisites

Node.js 18+ and npm/pnpm
MongoDB instance (local or Atlas)
AWS S3 credentials (optional, for file uploads)
Email service credentials (SendGrid or similar via Nodemailer)

Installation

Clone the repository:

git clone https://github.com/yourusername/samarpan.git
cd samarpan

Install dependencies:
```
npm install
# or
pnpm install
```

Configure environment variables:

cp .env.example .env.local

Update .env.local with:

# Database
MONGODB_URL=mongodb+srv://username:password@cluster.mongodb.net/samarpan

# JWT
JWT_SECRET=your-secret-key-here

# Email Service
EMAIL_USER=your-email@gmail.com
EMAIL_PASSWORD=your-app-password

# AWS (optional)
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_S3_BUCKET=your-bucket-name
AWS_REGION=us-east-1

# Google OAuth (optional)
NEXT_PUBLIC_GOOGLE_CLIENT_ID=your-google-client-id

# Maintenance System (new)
MAINTENANCE_INTERNAL_TOKEN=your-internal-token-for-maintenance-checks

Set up the database and create super admin:
```
npm run setup:admin
```
This initializes the admin system with database indexes and creates the super admin account.

📌 For detailed admin setup instructions, see Admin Quick Start Guide
Start the development server:
```
npm run dev
```
The application will be available at http://localhost:3000

Admin System

Default Super Admin Credentials

Login at /admin/login:

Email: admin@samarpan.com
Password: admin@123

Setup Commands

npm run setup:admin      # Recommended: Sets up everything with indexes
npm run create-admin     # Interactive: Create super admin or regular admin
npx tsx create-admin.ts  # Direct: Create/update super admin

Admin Features

✅ Create and manage admin accounts with specific features/permissions
✅ Two-tier system: Super Admin (full access) and Regular Admin (limited)
✅ Granular permission control (16+ different permissions)
✅ Real-time admin dashboard with activity tracking
✅ NEW: Comprehensive maintenance mode management
✅ FIXED: Reliable QR code scanning system

For complete documentation, see:

📁 Project Structure

samarpan/
├── app/                          # Next.js App Router
│   ├── (public)/                 # Public routes
│   │   ├── page.tsx              # Home page
│   │   ├── auth/                 # Auth routes (login, signup)
│   │   ├── dashboard/            # User dashboard
│   │   ├── donate-blood/         # Blood donation requests
│   │   ├── request-blood/        # Blood request creation
│   │   ├── events/               # Event listings
│   │   ├── notifications/        # Notification center
│   │   ├── maintenance/          # 🆕 Maintenance page with blood.png
│   │   └── ...
│   ├── admin/                    # Admin routes
│   │   ├── login/                # Admin login
│   │   ├── page.tsx              # Admin dashboard
│   │   └── ...
│   ├── api/                      # API routes
│   │   ├── auth/                 # Authentication endpoints
│   │   ├── admin/                # Admin operations
│   │   │   ├── maintenance/      # 🆕 Maintenance mode API
│   │   │   └── ...
│   │   ├── blood-request/        # Blood requests API
│   │   ├── donation-requests/    # Donations API
│   │   ├── users/                # User management API
│   │   ├── events/               # Events API
│   │   ├── notifications/        # Notifications API
│   │   └── ...
│   ├── layout.tsx                # Root layout
│   └── globals.css               # Global styles
├── components/                   # React components
│   ├── ui/                       # Radix UI components
│   ├── admin-*.tsx               # Admin panel components
│   ├── admin-qr-*.tsx            # 🔧 Fixed QR scanner components
│   ├── blood-*.tsx               # Blood-related components
│   ├── samarpan-loader.tsx       # 🆕 Enhanced loader with blood.png
│   ├── maintenance-mode-manager.tsx # 🆕 Maintenance management
│   ├── navbar.tsx                # 🔧 Enhanced navbar with maintenance mode
│   ├── login-form.tsx            # Auth forms
│   └── ...
├── lib/                          # Utility functions
│   ├── auth.ts                   # Authentication utilities
│   ├── mongodb.ts                # Database connection
│   ├── email.ts                  # Email service
│   ├── store.ts                  # Redux store
│   ├── slices/                   # Redux slices
│   ├── maintenance-cache.ts      # 🆕 Maintenance caching system
│   └── utils.ts                  # Helper utilities
├── hooks/                        # Custom React hooks
│   ├── use-geolocation.ts        # Geolocation hook
│   ├── use-mobile.ts             # Mobile detection
│   └── use-toast.ts              # Toast notifications
├── public/                       # Static assets
│   ├── maintenance/              # 🆕 Maintenance assets
│   │   └── blood.png             # 🆕 Blood drop image for loader
│   └── ...
├── scripts/                      # Utility scripts
│   ├── create-admin.ts           # Admin creation script
│   └── update-admin-password.ts  # Password update script
├── styles/                       # CSS files
├── package.json                  # Dependencies (cleaned up)
├── tsconfig.json                 # TypeScript config
├── next.config.mjs               # Next.js config
├── tailwind.config.ts            # Tailwind CSS config
├── middleware.ts                 # 🔧 Enhanced middleware with maintenance
├── .vercelignore                 # 🆕 Vercel deployment config
└── MAINTENANCE_LIGHT_THEME_UPDATE.md # 🆕 Maintenance system docs

🔧 Recent Technical Improvements

QR Scanner System Enhancements

Robust DOM Element Waiting: Implemented retry logic with maximum attempts
Enhanced Safety Checks: Added element validation before scanner creation
Improved Cleanup: Better error handling and resource cleanup
Camera Initialization: Enhanced camera access with proper error handling
Production Ready: Reliable QR scanning in both admin QR checker and event scanner

Maintenance System Features

Complete Route Protection: Middleware blocks all routes during maintenance
Real-Time Monitoring: 30-second auto-refresh with connection status
Priority-Based Styling: Different colors for maintenance levels
IP Whitelisting: Allow specific IPs to bypass maintenance
Emergency Access: Secret key bypass functionality
Professional UI: Beautiful maintenance page with Samarpan branding
Mobile Responsive: Perfect experience across all devices

Deployment Optimizations

Vercel Compatibility: Fixed lockfile conflicts and dependency issues
Build Optimization: Cleaned up problematic dependencies
Configuration Management: Proper .vercelignore and build settings
Zero-Config Deployment: Seamless deployment to Vercel

UI/UX Enhancements

Light Theme Consistency: Maintenance page matches site theme
Perfect Center Alignment: Maintenance indicator aligned with loader
Smart Navbar: Auto-hiding navigation during maintenance
Blood Drop Animation: Custom blood.png in maintenance loader
Glass Morphism: Modern design with subtle effects

📚 API Documentation

Authentication Endpoints

POST /api/auth/signup – Register new user

{
  "email": "user@example.com",
  "password": "secure-password",
  "name": "John Doe",
  "phone": "+91XXXXXXXXXX",
  "bloodType": "O+"
}

POST /api/auth/login – User login

{
  "email": "user@example.com",
  "password": "password"
}

POST /api/auth/admin-login – Admin login

{
  "email": "admin@samarpan.com",
  "password": "admin-password"
}

Maintenance System Endpoints (NEW)

GET /api/admin/maintenance – Get maintenance status

{
  "enabled": false,
  "message": "Maintenance message",
  "priority": "medium",
  "enabledAt": "2026-01-02T18:00:00.000Z",
  "allowedIps": ["192.168.1.100"],
  "secretKey": "emergency-key"
}

POST /api/admin/maintenance – Update maintenance settings

{
  "enabled": true,
  "message": "We are performing scheduled maintenance...",
  "priority": "high",
  "allowedIps": ["192.168.1.100", "10.0.0.50"],
  "secretKey": "emergency-access-2026"
}

Blood Request Endpoints

GET /api/blood-request – Get all blood requests
POST /api/blood-request – Create new blood request
PUT /api/blood-request/[id] – Update blood request
DELETE /api/blood-request/[id] – Delete blood request

User Endpoints

GET /api/users – Get all users (admin only)
GET /api/users/[id] – Get user profile
PUT /api/users/[id] – Update user profile

Event Endpoints

GET /api/events – Get all events
POST /api/events – Create event (admin only)
PUT /api/events/[id] – Update event (admin only)
DELETE /api/events/[id] – Delete event (admin only)

🔐 Authentication & Security

Password Hashing: bcryptjs with salt rounds = 10
JWT Tokens: Secure token-based authentication
Protected Routes: Enhanced middleware-based route protection
Maintenance Security: IP whitelisting and emergency access keys
Environment Variables: Sensitive data stored in .env.local
HTTPS Ready: Production-ready for HTTPS deployment
CORS: Properly configured cross-origin policies

🧪 Development & Build

Available Scripts

# Start development server
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Run linting
npm run lint

# Create/Update admin account
npm run create-admin

# Initialize database
npm run db:init

# Full setup (install + create admin)
npm run setup

Environment-Specific Builds

The application uses environment-specific configurations:

Development: npm run dev – Hot reload enabled
Production: npm run build && npm start – Optimized build
Vercel: Automatic deployment with optimized configuration

📝 Environment Variables

Create a .env.local file in the project root:

# MongoDB Connection
MONGODB_URL=mongodb+srv://user:pass@cluster.mongodb.net/samarpan

# JWT Configuration
JWT_SECRET=your-secret-key-min-32-characters

# Email Service
EMAIL_USER=your-email@gmail.com
EMAIL_PASSWORD=your-app-password
EMAIL_FROM=noreply@samarpan.com

# AWS S3 (Optional)
AWS_ACCESS_KEY_ID=XXXXXXXXXXXXX
AWS_SECRET_ACCESS_KEY=XXXXXXXXXXXXX
AWS_S3_BUCKET=samarpan-uploads
AWS_REGION=us-east-1

# Google OAuth (Optional)
NEXT_PUBLIC_GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com

# Admin Credentials (for initialization)
ADMIN_EMAIL=admin@samarpan.com
ADMIN_PASSWORD=strong-password

# Maintenance System (NEW)
MAINTENANCE_INTERNAL_TOKEN=your-internal-maintenance-token

# WhatsApp (Optional)
WHATSAPP_ENABLED=true
WHATSAPP_TOKEN=your-meta-whatsapp-token
WHATSAPP_PHONE_NUMBER_ID=your-phone-number-id
WHATSAPP_DEFAULT_COUNTRY_CODE=91

WhatsApp Setup

Enable WhatsApp notifications alongside in‑app notifications and email:

Set WHATSAPP_ENABLED to true to activate WhatsApp sending.
Provide WHATSAPP_TOKEN from your Meta WhatsApp Business Cloud API.
Set WHATSAPP_PHONE_NUMBER_ID to the sender phone number ID from Meta.
Optionally set WHATSAPP_DEFAULT_COUNTRY_CODE (e.g., 91) if your users store local numbers without a country code.

When enabled, flows such as blood requests, admin broadcasts, event registrations, QR verification, donation image reviews, certificate generation, transportation creation and status updates attempt best‑effort WhatsApp delivery if the user has a phone saved.

🎨 Customization

Styling

The project uses Tailwind CSS with a custom theme. Modify theme colors in tailwind.config.ts:

theme: {
  colors: {
    primary: '#your-color',
    secondary: '#your-color',
    // ... other colors
  }
}

UI Components

All UI components are in components/ui/ and based on Radix UI. Customize them as needed:

import { Button } from "@/components/ui/button"
import { Card } from "@/components/ui/card"
import { Input } from "@/components/ui/input"

Maintenance Page Customization

The maintenance page supports custom styling and messages:

// Custom maintenance messages by priority
const priorityConfigs = {
  low: { message: 'Routine maintenance in progress' },
  medium: { message: 'Scheduled maintenance underway' },
  high: { message: 'Important system updates' },
  critical: { message: 'Critical maintenance required' }
}

🚀 Deployment

Vercel (Recommended) - ENHANCED

Push your repository to GitHub
Connect to Vercel: https://vercel.com/new
Set environment variables in Vercel dashboard:
- CRITICAL FOR PASSWORD RESET: Set NEXT_PUBLIC_APP_URL to your production domain (e.g., https://yourdomain.com)
  - Without this, password reset links will not work correctly
  - If not set, the app will try to auto-detect using VERCEL_URL, but explicitly setting it is recommended
- Include all other required variables: MONGODB_URL, GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, SMTP_* settings
- NEW: Add MAINTENANCE_INTERNAL_TOKEN for maintenance system
Deploy! (Now works seamlessly with fixed dependency issues)

⚠️ Password Reset Configuration: Password reset emails contain a link to /reset-password. This URL must be accessible from the internet. The app constructs it using:

Priority 1: NEXT_PUBLIC_APP_URL environment variable
Priority 2: Vercel's automatic VERCEL_URL (if not set in Priority 1)
Priority 3: Request headers (x-forwarded-proto, x-forwarded-host)
Priority 4: Request origin

To ensure password reset works on production:

NEXT_PUBLIC_APP_URL=https://your-production-domain.com

Docker

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
CMD ["npm", "start"]

Traditional Server

npm install --production
npm run build
npm start

🤝 Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

Code Standards

Follow ESLint rules
Use TypeScript for type safety
Add comments for complex logic
Test new features thoroughly
Keep components focused and reusable
Test QR scanner functionality on real devices
Verify maintenance mode works across all routes

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Radix UI – For excellent accessible components
Next.js – For the amazing React framework
MongoDB – For robust database solutions
Tailwind CSS – For utility-first CSS framework
html5-qrcode – For reliable QR code scanning functionality
The Open Source Community – For invaluable libraries and tools

📞 Support

For support, email support@samarpan.com or open an issue in the repository.

🗺️ Roadmap

🔍 Troubleshooting Guide

Common Issues & Solutions

QR Scanner Issues ✅ FIXED

Problem: "HTML Element with id=admin-qr-reader not found"
Solution: ✅ RESOLVED - Implemented robust DOM element waiting with retry logic

Deployment Issues ✅ FIXED

Problem: "Cannot install with 'frozen-lockfile'" on Vercel
Solution: ✅ RESOLVED - Cleaned up dependencies and lockfile conflicts

Maintenance Mode

Enable: Admin Dashboard → Maintenance Mode → Toggle switch
Priority Levels: Choose from low, medium, high, critical for different styling
Emergency Access: Use secret key parameter: ?secret=your-key
IP Bypass: Add allowed IPs in maintenance settings

Camera Access

HTTPS Required: Camera access requires HTTPS on mobile devices
Permissions: Ensure camera permissions are granted in browser
Testing: Use npm run dev -- --host for local mobile testing

Made with ❤️ to save lives

Latest Update: January 2026 - Enhanced QR System, Maintenance Mode & Deployment

⬆ Back to Top

Name		Name	Last commit message	Last commit date
Latest commit History 92 Commits
.vscode		.vscode
app		app
components		components
hooks		hooks
lib		lib
public		public
scripts		scripts
styles		styles
types		types
.gitignore		.gitignore
.npmrc		.npmrc
.vercelignore		.vercelignore
DEPLOYMENT_CHECKLIST.md		DEPLOYMENT_CHECKLIST.md
LEARN.md		LEARN.md
LICENSE		LICENSE
LICENSE.md		LICENSE.md
QR_MODULE_README.md		QR_MODULE_README.md
README.md		README.md
build.log		build.log
components.json		components.json
middleware.ts		middleware.ts
next.config.mjs		next.config.mjs
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
server.log		server.log
tsconfig.json		tsconfig.json
vercel.json		vercel.json

Folders and files

Latest commit

History

Repository files navigation