Skip to content

titoretty/BloodBank

BranchesTags

Repository files navigation

🩸 Blood Bank Management System

Version: 2.0
Last Updated: November 12, 2025
Status: In Development (Security Fixes in Progress)

📋 Table of Contents

  1. Overview
  2. Features
  3. System Requirements
  4. Installation Guide
  5. Database Setup
  6. Configuration
  7. User Roles & Permissions
  8. Security Status
  9. Password Reset Feature
  10. Notification System
  11. Blood Stock Management
  12. Testing Guide
  13. Troubleshooting
  14. Known Issues
  15. Changelog

🎯 Overview

A comprehensive web-based Blood Bank Management System designed to streamline blood donation, inventory management, and request handling. The system supports three primary user roles: Admin, Hospital, and User (Donors/Recipients).

Key Highlights

  • ✅ Complete blood stock management for hospitals
  • ✅ User-to-user and user-to-hospital blood requests
  • ✅ Real-time notifications system
  • ✅ Blood donation tracking
  • ✅ Password reset with OTP verification
  • ✅ Responsive design with unified theme
  • ⚠️ Security improvements in progress

✨ Features

For Users (Donors/Recipients)

  • 📝 User registration and profile management
  • 🩸 Request blood from hospitals
  • 👥 Request blood from other users
  • 💉 Donate blood to hospitals
  • 🔔 Real-time notifications
  • 📊 View donation and request history
  • 🔍 Search available blood stock
  • 🗺️ Hospital location map

For Hospitals

  • 🏥 Hospital registration and verification
  • 📦 Blood stock management (add/edit/delete inventory)
  • 📥 Receive and manage blood requests
  • 📤 Accept blood donations
  • ✅ Approve or reject requests/donations
  • 🔔 Notification system for incoming requests
  • 📊 Dashboard with statistics
  • 📈 Low stock alerts

For Admins

  • 👤 User management (approve/reject/edit/delete)
  • 🏥 Hospital management (approve/reject/edit/delete)
  • 📊 System-wide reports and analytics
  • 🔔 Notifications for pending approvals
  • 🔒 System configuration
  • 📈 View all blood requests and donations

💻 System Requirements

Server Requirements

  • Web Server: Apache 2.4+ or Nginx
  • PHP: 7.4 or higher (8.0+ recommended)
  • Database: MySQL 5.7+ or MariaDB 10.4+
  • Extensions Required:
    • PDO or MySQLi
    • mbstring
    • openssl
    • JSON
    • cURL (for email)

Development Environment

  • XAMPP 7.4+ / WAMP / LAMP / MAMP
  • phpMyAdmin (recommended)
  • Modern web browser (Chrome, Firefox, Edge, Safari)

🚀 Installation Guide

Step 1: Download/Clone the Project

# Clone from repository
git clone https://github.com/CERO-100/BloodBank.git

# Or download and extract ZIP file

Step 2: Move to Web Directory

# For XAMPP
Move to: C:\xampp\htdocs\BloodBank

# For WAMP
Move to: C:\wamp64\www\BloodBank

# For LAMP (Linux)
Move to: /var/www/html/BloodBank

Step 3: Import Database

  1. Start Apache and MySQL in XAMPP/WAMP
  2. Open phpMyAdmin: http://localhost/phpmyadmin
  3. Create Database: Click "New" → Name: blood → Create
  4. Import SQL File:
    • Click on blood database
    • Go to "Import" tab
    • Choose file: backups/blood_bank_complete.sql
    • Click "Go"

Step 4: Configure Database Connection

Edit: includes/config.php or includes/db.php

define('DB_HOST', 'localhost');
define('DB_USER', 'root');
define('DB_PASS', '');           // Your MySQL password
define('DB_NAME', 'blood');

Step 5: Configure Email (For Password Reset)

Edit: includes/mailer.php

$mail->Username = 'your-email@gmail.com';        // Your Gmail
$mail->Password = 'your-16-char-app-password';   // Gmail App Password

Get Gmail App Password:

  1. Go to https://myaccount.google.com/security
  2. Enable 2-Step Verification
  3. Create App Password for "Mail"
  4. Use the generated 16-character password

Step 6: Access the System

Main Site:    http://localhost/BloodBank/
User Login:   http://localhost/BloodBank/login.php
Admin Login:  http://localhost/BloodBank/admin/admin_login.php

🗄️ Database Setup

Complete Database Structure

The system uses 6 main tables:

1. admins - Administrator Accounts

- admin_id (Primary Key)
- name
- email (Unique)
- password (Hashed with bcrypt)
- role (admin/superadmin)
- created_at

2. users - Users, Hospitals, Donors

- user_id (Primary Key)
- name
- email (Unique)
- password (Hashed)
- role (user/hospital/admin)
- phone
- blood_group (for users)
- location
- district
- latitude, longitude (for hospitals)
- status (pending/approved/rejected)
- created_at

3. blood_stock - Hospital Inventory

- stock_id (Primary Key)
- hospital_id (Foreign Key → users)
- blood_group (A+, A-, B+, B-, AB+, AB-, O+, O-)
- quantity
- updated_at

4. requests - Blood Requests

- request_id (Primary Key)
- user_id (Foreign Key → users)
- hospital_id (Foreign Key → users) - For hospital requests
- donor_id (Foreign Key → users) - For user-to-user requests
- blood_group
- quantity
- status (pending/approved/rejected)
- created_at

5. donations - Blood Donations

- donation_id (Primary Key)
- user_id (Foreign Key → users)
- hospital_id (Foreign Key → users)
- blood_group
- quantity
- status (pending/approved/rejected)
- created_at

6. notifications - System Notifications

- id (Primary Key)
- user_id (Foreign Key → users)
- message
- type (user/hospital/donation/request/system)
- status (unread/read)
- created_at

Database Features

  • ✅ Foreign key constraints for data integrity
  • ✅ Indexes on frequently queried columns
  • ✅ Proper enum types for status fields
  • ✅ Automatic timestamps
  • ✅ ON DELETE CASCADE/SET NULL for referential integrity

⚙️ Configuration

Essential Configuration Files

  1. includes/config.php - Main configuration

    • Database credentials
    • Site base URL
    • Role constants

  2. includes/db.php - Database connection

    • Alternative DB connection file
    • Used in some older files

  3. includes/mailer.php - Email configuration

    • SMTP settings
    • Gmail credentials
    • Email templates

  4. includes/session.php - Session management

    • Session security functions
    • Login/logout handlers
    • Role-based access control

  5. includes/functions.php - Utility functions

    • Input sanitization
    • Flash messages
    • Activity logging

👥 User Roles & Permissions

Admin Role

Access: admin/admin_login.php

Default Credentials:

Email: tito@gmail.com
Password: [Check database - hashed]

Permissions:

  • View all users and hospitals
  • Approve/reject user registrations
  • Approve/reject hospital registrations
  • Edit user/hospital profiles
  • Delete users/hospitals
  • View system reports
  • Manage system settings
  • View all requests and donations

Files:

  • admin/admin.php - Dashboard
  • admin/manage_users.php - User management
  • admin/manage_hospitals.php - Hospital management
  • admin/view_requests.php - All requests
  • admin/notifications.php - Admin notifications
  • admin/reports.php - System reports

Hospital Role

Access: login.php (role: hospital)

Default Credentials:

Email: testh@gmail.com
Password: [Check database]

Permissions:

  • Manage blood stock (add/edit/delete)
  • View incoming blood requests
  • Approve/reject blood requests
  • View incoming blood donations
  • Approve/reject blood donations
  • View dashboard statistics
  • Update hospital profile
  • Receive notifications

Files:

  • hospital/dashboard.php - Hospital dashboard
  • hospital/stock.php - Blood stock management
  • hospital/requests.php - Manage requests
  • hospital/donations.php - Manage donations
  • hospital/notifications.php - Hospital notifications
  • hospital/profile.php - Hospital profile

User Role (Donor/Recipient)

Access: login.php (role: user)

Default Credentials:

Email: jerin@gmail.com
Password: [Check database]

Permissions:

  • Request blood from hospitals
  • Request blood from other users
  • Donate blood to hospitals
  • View request/donation history
  • Search available blood stock
  • View hospital locations on map
  • Update profile
  • Receive notifications

Files:

  • user/dashboard.php - User dashboard
  • user/request_blood.php - Request from hospital
  • user/request_public.php - Request from user
  • user/donate_blood.php - Donate blood
  • user/my_requests.php - Request history
  • user/my_donations.php - Donation history
  • user/notifications.php - User notifications
  • user/profile.php - User profile

🔒 Security Status

✅ Security Features Implemented

  1. Password Security

    • Bcrypt hashing (PASSWORD_DEFAULT)
    • Minimum password length enforcement
    • Password strength indicator

  2. Session Security (Partial)

    • Session regeneration on login
    • IP address tracking
    • User agent verification
    • Auto-logout after inactivity (admin only)

  3. Input Validation (Partial)

    • Email validation
    • Phone number format validation
    • Blood group enum validation
    • Integer type casting

  4. SQL Injection Protection (IN PROGRESS)

    • ✅ 8 files fixed with prepared statements
    • ⚠️ 22+ files remaining with vulnerabilities

⚠️ Critical Security Issues (IN PROGRESS)

1. SQL Injection Vulnerabilities - CRITICAL ⛔

Status: 27% Fixed (8/30+ files)

Files Fixed:

  • ✅ admin/approve_user.php
  • ✅ admin/approve_h.php
  • ✅ login.php
  • ✅ hospital/stock.php
  • ✅ includes/unified_header.php
  • ✅ user/donate_blood.php
  • ✅ user/profile.php

Files Requiring Fixes:

  • ⚠️ user/request_blood.php
  • ⚠️ user/history.php
  • ⚠️ hospital/profile.php
  • ⚠️ hospital/header.php
  • ⚠️ hospital/dashboard.php
  • ⚠️ hospital/requests.php
  • ⚠️ hospital/donations.php
  • ⚠️ All admin delete/edit files
  • ⚠️ All notification files

Risk: Database compromise, data theft, unauthorized access

2. Missing CSRF Protection - HIGH ⚠️

Status: Not Implemented

Affected Areas:

  • All user approval/rejection forms
  • Hospital management forms
  • Blood stock management
  • Profile update forms
  • All CRUD operations

Risk: Cross-site request forgery attacks

3. XSS Vulnerabilities - MEDIUM ⚠️

Status: Partial Protection

Issues:

  • Output not consistently escaped with htmlspecialchars()
  • User-generated content not sanitized
  • JavaScript injection possible in some forms

Risk: Session hijacking, malicious script execution

4. Authentication Issues - HIGH ⚠️

Fixed:

  • ✅ Status check added (pending users blocked)
  • ✅ Login redirect path corrected
  • ✅ Session security improved

Remaining:

  • ⚠️ No password reset attempts limit
  • ⚠️ No account lockout mechanism
  • ⚠️ Session timeout inconsistent across modules

🛡️ Security Recommendations

Before Production:

  1. ✅ Fix all SQL injection vulnerabilities (Priority 1)
  2. ✅ Implement CSRF token system
  3. ✅ Add comprehensive XSS protection
  4. ✅ Implement rate limiting for login/password reset
  5. ✅ Add account lockout after failed attempts
  6. ✅ Enable HTTPS only
  7. ✅ Implement Content Security Policy (CSP)
  8. ✅ Add input validation on all forms
  9. ✅ Sanitize all database outputs
  10. ✅ Regular security audits

🔐 Password Reset Feature

Complete 3-Step Flow

Step 1: Email Verification (forgot_password.php)

  • Enter registered email address
  • System generates 6-digit OTP
  • OTP valid for 15 minutes
  • Email sent via PHPMailer

Step 2: OTP Verification (verify_otp.php)

  • Enter 6-digit OTP from email
  • Visual countdown timer (15:00)
  • Paste support for easy input
  • 3-attempt security limit
  • Resend OTP option

Step 3: New Password (reset_password.php)

  • Enter new password
  • Real-time strength indicator
  • Requirements checklist:
    • ✅ Minimum 6 characters
    • ✅ Contains uppercase letter
    • ✅ Contains lowercase letter
    • ✅ Contains number
    • ✅ Contains special character
  • Password confirmation validation

Email Configuration

Required: Gmail App Password

Setup:

  1. Enable 2-Step Verification on Gmail
  2. Go to App Passwords
  3. Generate password for "Mail"
  4. Add to includes/mailer.php

Files:

  • forgot_password.php - Step 1
  • verify_otp.php - Step 2
  • reset_password.php - Step 3
  • includes/mailer.php - Email configuration

🔔 Notification System

Features

  • ✅ Real-time notifications for all users
  • ✅ User-to-user request notifications
  • ✅ Hospital request/donation notifications
  • ✅ Admin approval notifications
  • ✅ Unread count badges
  • ✅ Mark as read functionality
  • ✅ Notification types: user, hospital, donation, request, system

For Users

Location: user/notifications.php

Receives:

  • Blood request responses from hospitals
  • Blood request responses from other users
  • Donation approval/rejection
  • System announcements

For Hospitals

Location: hospital/notifications.php

Receives:

  • New blood requests from users
  • New blood donation offers
  • Stock low alerts
  • System announcements

For Admins

Location: admin/notifications.php

Receives:

  • New user registrations (pending approval)
  • New hospital registrations (pending approval)
  • System alerts

🩸 Blood Stock Management

Features

  • ✅ Add blood stock by blood group
  • ✅ Update quantities
  • ✅ Delete stock entries
  • ✅ Visual dashboard with stat cards
  • ✅ Low stock alerts (< 5 units)
  • ✅ Color-coded indicators
  • ✅ Real-time stock validation

Stock Request Flow

  1. User Requests Blood:

    • User selects hospital
    • System shows only available blood groups
    • Quantity limited to available stock

  2. Stock Validation:

    • Client-side: Dynamic max quantity
    • Server-side: Availability check
    • Error if insufficient stock

  3. Hospital Approves:

    • Automatic stock deduction
    • Notification sent to user
    • Stock updated in real-time

  4. Stock Indicators:

    • 🟢 Green (≥5 units) - Good stock
    • 🟡 Yellow (<5 units) - Low stock warning
    • 🔴 Red (0 units) - Out of stock

Stock Dashboard Cards

  • Total Units: Sum of all blood units
  • Blood Types: Number of blood groups in stock
  • Low Stock Alert: Count of low stock items

🧪 Testing Guide

Quick Test Checklist

User Registration & Approval

  • Register new user with valid data
  • Check user appears in admin panel
  • Admin approves user
  • User receives approval notification
  • User can now login
  • Pending user cannot login

Hospital Registration & Approval

  • Register new hospital with location
  • Check hospital in admin panel
  • Admin approves hospital
  • Hospital receives notification
  • Hospital can login
  • Hospital can access dashboard

Blood Stock Management

  • Hospital adds blood stock
  • Stock appears in inventory
  • Edit stock quantity
  • Low stock alert shows for <5 units
  • Delete stock entry
  • Dashboard stats update

Blood Request Flow (Hospital)

  • User searches hospitals
  • User sees only available blood
  • User requests blood
  • Hospital receives notification
  • Hospital approves request
  • Stock deducts automatically
  • User receives approval notification

Blood Request Flow (User-to-User)

  • User searches for donors
  • User sends request to donor
  • Donor receives notification
  • Request appears in donor's notifications

Blood Donation Flow

  • User donates to hospital
  • Hospital receives notification
  • Hospital approves donation
  • User receives confirmation
  • Stock increases (if implemented)

Password Reset

  • Click "Forgot Password"
  • Enter email, receive OTP
  • Enter OTP within 15 minutes
  • Set new password
  • Login with new password

Notification System

  • All actions trigger notifications
  • Unread count updates
  • Mark as read works
  • Notifications display correctly

🔧 Troubleshooting

Common Issues

1. Database Connection Error

Error: Connection failed: Access denied

Solution:

// Check includes/config.php or includes/db.php
define('DB_HOST', 'localhost');
define('DB_USER', 'root');
define('DB_PASS', '');  // ← Check this matches your MySQL password
define('DB_NAME', 'blood');

2. Admin Login Redirect to Wrong Page

Error: 404 Not Found - admin/dashboard.php

Solution: Already fixed! Login now redirects to admin/admin.php

3. Pending Users Can Login

Status: ✅ FIXED

Users with status='pending' are now blocked from logging in.

4. SQL Injection Errors

Error: You have an error in your SQL syntax

Status: ⚠️ Partially Fixed (27% complete)

Temporary Workaround: Avoid special characters in inputs

5. Email Not Sending (Password Reset)

Error: SMTP Error

Solutions:

  1. Check Gmail App Password in includes/mailer.php
  2. Enable "Less secure app access" (not recommended)
  3. Use Gmail App Password (recommended)
  4. Check firewall/antivirus blocking port 587
  5. Verify SMTP settings: 
    $mail->Host = 'smtp.gmail.com';
$mail->Port = 587;
$mail->SMTPSecure = 'tls';

6. Notifications Not Showing

Causes:

  • Database migration not run
  • notifications table missing
  • Incorrect user_id in session

Solutions:

  1. Check notifications table exists
  2. Verify user is logged in
  3. Check SQL queries in notification files

7. Stock Not Deducting on Approval

Status: ✅ Working

Automatic stock deduction implemented in hospital/requests.php

8. "Column 'donor_id' doesn't exist"

Solution: Run database migration:

ALTER TABLE requests 
ADD COLUMN donor_id INT(11) DEFAULT NULL AFTER hospital_id;

ALTER TABLE requests 
ADD CONSTRAINT fk_requests_donor 
FOREIGN KEY (donor_id) REFERENCES users(user_id) 
ON DELETE SET NULL;

9. Session Timeout Too Aggressive

Location: includes/admin_auth.php (line ~35)

Change timeout:

$timeout = 30 * 60; // 30 minutes (change as needed)

10. Unified Theme Not Applied

Status: ⚠️ Partial Implementation

Only header/footer use unified theme. Remaining pages need updates.

Files:

  • assets/css/theme.css - Unified theme
  • includes/unified_header.php - New header
  • includes/unified_footer.php - New footer

⚠️ Known Issues

Critical (Must Fix Before Production)

  1. SQL Injection Vulnerabilities ⛔

    • Status: 27% Fixed (8/30+ files)
    • Impact: HIGH - Database compromise possible
    • ETA: 2-3 hours to complete

  2. No CSRF Protection ⛔

    • Status: Not Implemented
    • Impact: HIGH - Unauthorized actions possible
    • ETA: 4-6 hours to implement

  3. Inconsistent Session Management ⚠️

    • Status: Partially Fixed
    • Impact: MEDIUM - Security gaps
    • ETA: 2-3 hours

Medium Priority

  1. Design Inconsistency 🎨

    • Status: 0/45 pages using unified theme
    • Impact: LOW - Visual inconsistency
    • ETA: 2-3 days

  2. XSS Vulnerabilities ⚠️

    • Status: Partial protection
    • Impact: MEDIUM - Script injection possible
    • ETA: 3-4 hours

  3. No Input Validation on Some Forms ⚠️

    • Status: Basic validation only
    • Impact: MEDIUM - Invalid data possible
    • ETA: 2-3 hours

Low Priority

  1. No Rate Limiting

    • Impact: LOW - Brute force possible
    • ETA: 2-3 hours

  2. No Activity Logging

    • Impact: LOW - Audit trail incomplete
    • ETA: 1-2 hours

  3. No Email Queue System

    • Impact: LOW - Email delays possible
    • ETA: 4-6 hours

📝 Changelog

Version 2.0 - November 12, 2025 (IN PROGRESS)

Security Fixes

  • ✅ Fixed SQL injection in 8 critical files
  • ✅ Added user status check in login
  • ✅ Fixed admin login redirect
  • ✅ Enhanced session security
  • ✅ Added email validation
  • ⚠️ 22+ files still need SQL injection fixes

Features Added

  • ✅ Complete password reset with OTP
  • ✅ User-to-user blood requests
  • ✅ Hospital notification system
  • ✅ Blood stock management with visual dashboard
  • ✅ Stock-based request validation
  • ✅ Automatic stock deduction on approval
  • ✅ Unified design system (theme.css)
  • ✅ Unified header/footer components

Bug Fixes

  • ✅ Fixed notification system
  • ✅ Fixed empty status values in database
  • ✅ Added donor_id field to requests table
  • ✅ Fixed redirect paths
  • ✅ Fixed session variable conflicts

Database Changes

  • ✅ Added donor_id column to requests table
  • ✅ Added foreign key constraints
  • ✅ Added performance indexes
  • ✅ Fixed data integrity issues
  • ✅ Consolidated SQL files

Version 1.0 - Initial Release

Core Features

  • User registration and login
  • Hospital registration
  • Admin panel
  • Blood stock management (basic)
  • Blood request system
  • Blood donation system
  • Basic notifications

📚 Documentation Files

Main Documentation

  • README.md - This file (comprehensive guide)

Database

  • backups/blood_bank_complete.sql - Complete database with sample data
  • backups/sample_data_insert.sql - Additional sample data (NEW)

Reports (Reference Only)

All issues documented below have been consolidated into this README:

  • PRODUCTION_READINESS_REPORT.md - Security analysis
  • SQL_INJECTION_FIX_PROGRESS.md - Fix tracking
  • CHANGES_SUMMARY.md - Complete changelog
  • FIXES_DOCUMENTATION.md - Technical details

🚀 Deployment Checklist

Before Production

Security (CRITICAL)

  • Fix all SQL injection vulnerabilities
  • Implement CSRF protection
  • Add XSS protection (htmlspecialchars)
  • Implement rate limiting
  • Add account lockout mechanism
  • Enable HTTPS only
  • Change all default passwords
  • Remove sample data from database
  • Disable error display (display_errors = Off)
  • Enable error logging

Configuration

  • Update database credentials
  • Configure email (SMTP)
  • Set correct BASE_URL
  • Configure session timeout
  • Set up backup system
  • Configure file upload limits
  • Set proper file permissions

Testing

  • Test all user flows
  • Test all admin functions
  • Test all hospital functions
  • Test notification system
  • Test password reset
  • Test on multiple browsers
  • Test on mobile devices
  • Load testing
  • Security audit

Documentation

  • Create admin user guide
  • Create hospital user guide
  • Create donor user guide
  • Document API endpoints (if any)
  • Create backup/restore guide
  • Document server requirements

👨‍💻 Development Team

Developer: CERO-100
Repository: https://github.com/CERO-100/BloodBank
Support: [Create an issue on GitHub]

📄 License

[Add your license information here]

🙏 Credits

  • Bootstrap 5 - UI Framework
  • Font Awesome 6.5.0 - Icons
  • PHPMailer - Email functionality
  • SweetAlert2 - Beautiful alerts
  • Chart.js - Dashboard charts

📞 Support

For issues and questions:

  1. Check this README first
  2. Check troubleshooting section
  3. Review documentation files
  4. Check PHP error logs
  5. Create GitHub issue

⚠️ IMPORTANT: This system is currently undergoing security improvements. DO NOT deploy to production until all critical security issues are resolved.

Current Status: 27% security fixes complete (8/30+ files)
Estimated Production Ready: 5-7 days

Last Updated: November 12, 2025
Version: 2.0-dev
Status: 🔄 In Development

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages