📖 Blood-Vault

BloodVault is a full-stack web application that revolutionizes blood donation and distribution by creating a centralized, real-time blood inventory system. The platform connects blood donors, hospitals, and individuals in need through an intuitive interface that requires no login for searching blood availability.

🎯 Problem Statement

During medical emergencies, finding the right blood type quickly can mean the difference between life and death:

• 🩸 Blood shortages cause preventable deaths annually
• 🏥 Hospitals struggle to maintain optimal inventory levels
• ⏰ Manual coordination between donors and recipients wastes critical time
• 📍 No centralized database of blood availability across locations
• 🔍 Patients' families must call multiple hospitals individually

💡 Our Solution

BloodVault eliminates these pain points through:

• Public Blood Search - Anyone can search for available blood without creating an account
• Real-time Inventory - Hospitals update stock instantly, visible to all users
• Direct Communication - Contact information provided for immediate coordination
• Donor Network - Platform to connect willing donors with those in need
• Location-based Matching - Find blood near you using city and state filters
• Two-way Requests - Hospitals can request blood, donors can offer donations

---

✨ Features

🌐 Public Features (No Login Required)

Blood Search

• Search available blood by type, city, and state
• View real-time inventory from all registered hospitals
• See blood expiry dates and quantities
• Get hospital contact information instantly
• Filter by location for nearby options

Blood Needs Dashboard

• Browse urgent blood requirements from hospitals
• View patient details and urgency levels
• Filter by blood type and location
• Access contact information for immediate response
• No registration needed to view or contact

🩸 Donor Features

Account Management

• Register with blood type and location
• Persistent login (stays logged in across sessions)
• Update profile information
• Dashboard with personalized statistics

Blood Donation

• Offer to Donate - Post blood donation offers publicly
• Search Needs - Find patients/hospitals needing your blood type
• Location Matching - See nearby blood requirements
• Request Blood - Create urgent requests for family/friends
• Manage Requests - Track and update all your requests
• Status Updates - Mark requests as fulfilled or cancel them

Dashboard Analytics

• View active donation offers
• Track blood requests created
• See nearby urgent needs
• Statistics on your contributions

🏥 Hospital Features

Inventory Management

• Upload Blood Stock - Add available blood units to public database
• Update Inventory - Modify quantities, expiry dates, status
• Delete Items - Remove expired or used blood units
• Real-time Sync - Changes reflect immediately in public search
• Bulk Operations - Manage multiple blood types efficiently

Blood Request Management

• Post Requirements - Create urgent blood need requests
• Patient Details - Add patient name and contact for emergencies
• Urgency Levels - System auto-calculates urgency based on date
• Status Tracking - Monitor active, fulfilled, and cancelled requests
• Public Visibility - Requests appear on public dashboard

Donor Network

• Find Donors - Search for donors by blood type and location
• View Offers - See all active blood donation offers
• Contact Donors - Direct communication with willing donors
• Filter Options - Sort by blood type, location, date

Hospital Dashboard

• Total stock overview (all blood types combined)
• Active requests counter
• Urgent needs tracker
• Quick action buttons (Upload Stock, Request Blood)
• Recent donor offers feed
• Inventory table with expiry tracking

🔒 Security & Privacy

Authentication

• JWT-based - Secure token authentication
• Password Encryption - bcrypt hashing for user passwords
• Hospital Verification - Secret key required for hospital accounts
• Persistent Sessions - localStorage for seamless experience
• Auto-logout - Session management for security

Access Control

• Role-based Routes - Donors and hospitals have separate dashboards
• Protected Endpoints - Middleware verification on sensitive operations
• Data Privacy - Users see only authorized information
• Safe Defaults - Public data carefully filtered

---

🔄 How It Works

System Architecture

┌─────────────────────────────────────────────────────────────┐
│                        FRONTEND (React)                      │
│                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │ Public Pages │  │    Donor     │  │   Hospital   │     │
│  │  (No Auth)   │  │  Dashboard   │  │  Dashboard   │     │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘     │
│         │                  │                   │             │
│         └──────────────────┼───────────────────┘             │
│                            │                                 │
│                    ┌───────▼────────┐                       │
│                    │   API Service   │                       │
│                    │     (Axios)     │                       │
│                    └───────┬────────┘                       │
└────────────────────────────┼──────────────────────────────┘
                             │
                    HTTP/HTTPS Requests
                             │
┌────────────────────────────▼──────────────────────────────┐
│                 BACKEND (Node.js + Express)                │
│                                                             │
│  ┌──────────────────────────────────────────────────────┐ │
│  │                    API Routes                         │ │
│  │  /api/auth         /api/inventory                     │ │
│  │  /api/blood-requests   /api/public                    │ │
│  └─────────────────┬────────────────────────────────────┘ │
│                    │                                        │
│  ┌─────────────────▼────────────────────────────────────┐ │
│  │              Middleware Layer                         │ │
│  │  • JWT Verification  • CORS  • Error Handling        │ │
│  └─────────────────┬────────────────────────────────────┘ │
│                    │                                        │
│  ┌─────────────────▼────────────────────────────────────┐ │
│  │               Controllers                             │ │
│  │  • Business Logic  • Validation  • Processing        │ │
│  └─────────────────┬────────────────────────────────────┘ │
│                    │                                        │
│  ┌─────────────────▼────────────────────────────────────┐ │
│  │            Mongoose Models                            │ │
│  │  • User  • Inventory  • BloodRequest                 │ │
│  └─────────────────┬────────────────────────────────────┘ │
└────────────────────┼────────────────────────────────────┘
                     │
                     │ Database Queries
                     │
┌────────────────────▼────────────────────────────────────┐
│                  MongoDB Atlas                           │
│                                                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │    Users     │  │  Inventories │  │Blood Requests│ │
│  │  Collection  │  │  Collection  │  │  Collection  │ │
│  └──────────────┘  └──────────────┘  └──────────────┘ │
└───────────────────────────────────────────────────────┘

Data Flow Examples

Example 1: Public Blood Search

User → Search Blood Page → Select (A+, Mumbai, Maharashtra)
  → Frontend sends GET /api/public/search-blood?bloodType=A+&city=Mumbai
  → Backend queries Inventory collection
  → Returns matching blood stock with hospital details
  → Frontend displays results in BloodStockCard components
  → User sees: 3 hospitals with A+ blood in Mumbai
  → User clicks "Contact Hospital" to get phone number

Example 2: Hospital Uploads Blood Stock

Hospital Login → Hospital Dashboard → Click "Upload Blood Stock"
  → Fill form (O+, 50 units, expiry: 30 days)
  → Frontend sends POST /api/inventory/upload with JWT token
  → Backend verifies token (authMiddleware)
  → Checks user role = hospital
  → Saves to Inventory collection with hospital reference
  → Returns success
  → Frontend redirects to My Inventory
  → Blood now visible in public search immediately

Example 3: Donor Offers Blood Donation

Donor Login → Donor Dashboard → Click "Offer Blood Donation"
  → Form pre-filled with donor's blood type (O+), city, state
  → Donor enters quantity (1), available date, notes
  → Frontend sends POST /api/blood-requests/create
  → Backend validates: requestType=donation, requesterType=donor
  → Auto-calculates urgency based on date
  → Saves to BloodRequest collection
  → Returns success
  → Hospitals can now see this offer in "Find Donors" page

---

📱 User Guide

Public Users (No Login Required)

Searching for Blood

1. Visit the homepage or click "Search Blood" in navbar
2. Select blood type from dropdown (A+, B+, O+, etc.)
3. Enter city and state (e.g., Mumbai, Maharashtra)
4. Click "Search" button
5. View available blood stock from hospitals:
   • Blood type and quantity
   • Hospital name and location
   • Expiry date
   • Contact number
6. Call hospital directly or visit for blood

Viewing Blood Needs

1. Visit homepage (public dashboard)
2. See list of urgent blood requirements
3. Filter by:
   • Blood type
   • City
   • State
   • Urgency level
4. View patient details and contact information
5. Contact hospital/donor to help

Donors

Registration

1. Click "Register" in navbar
2. Select "I am a Donor"
3. Fill form:
   • Full Name
   • Email (used for login)
   • Password (minimum 6 characters)
   • Phone number
   • Blood type (A+, A-, B+, B-, AB+, AB-, O+, O-)
   • City and State
   • Address (optional)
4. Click "Register"
5. Redirect to login page
6. Login with email and password

Offering Blood Donation

1. Login to donor account
2. Navigate to "Offer Blood Donation" (navbar or dashboard button)
3. Form shows:
   • Request type: Donation (pre-selected)
   • Blood type: Your blood type (auto-filled)
   • Quantity: Number of units (1-2 typically)
   • Available by: Date when you can donate
   • City/State: Your location (auto-filled, can change)
   • Contact person: Your name (auto-filled)
   • Contact number: Your phone (auto-filled)
   • Additional notes: Optional message
4. Click "Submit Donation Offer"
5. View confirmation message
6. Offer appears in hospital's "Find Donors" page
7. Hospitals can contact you directly

Requesting Blood (for family/emergency)

1. Login to donor account
2. Click "Request Blood" in navbar
3. Toggle to "Need Blood (Request)"
4. Fill form:
   • Blood type needed
   • Quantity required
   • Required by date
   • Patient name
   • Patient contact
   • Your location
5. Submit request
6. Request appears on public dashboard
7. Hospitals/donors can see and contact you

Managing Requests

1. Go to "Manage Requests"
2. View all your requests (donations offers + blood needs)
3. For each request:
   • See status (Active, Fulfilled, Cancelled)
   • View creation date and details
   • Update status when completed
   • Delete request if no longer needed

Hospitals

Registration

1. Click "Register" in navbar
2. Select "I am a Hospital/Blood Bank"
3. Fill form:
   • Organization Name (hospital name)
   • Email (official hospital email)
   • Password
   • Hospital Secret Key (obtain from admin)
   • Phone number
   • City and State
   • Address
4. Click "Register"
5. Login with email, password, and secret key

Uploading Blood Stock

1. Login to hospital account
2. Navigate to "Upload Blood Stock"
3. Fill form:
   • Blood type (A+, B+, O+, etc.)
   • Quantity (number of units available)
   • Expiry date (when blood expires)
   • City/State (auto-filled from profile)
   • Contact number (auto-filled from profile)
4. Click "Upload Blood Stock"
5. Blood appears in:
   • Your inventory ("My Inventory" page)
   • Public search results immediately
   • Public homepage stock feed

Managing Inventory

1. Go to "My Inventory" from navbar
2. View all uploaded blood stock:
   • Blood type
   • Quantity
   • Expiry date
   • Status (Available, Reserved, Expired)
3. Actions:
   • Update: Click edit icon, modify quantity/status
   • Delete: Remove expired or used blood
   • Filter: Search by blood type or status
4. Changes reflect in public search immediately

Posting Blood Requirements

1. Click "Request Blood" in navbar or dashboard
2. Select "Need Blood (Request)"
3. Fill form:
   • Blood type needed
   • Quantity required
   • Required by date (urgency auto-calculated)
   • Patient name
   • Patient contact
   • Hospital location (auto-filled)
   • Notes (optional: reason, urgency details)
4. Submit request
5. Request appears:
   • Public dashboard (homepage)
   • Donors can see and contact you
   • Your "Manage Requests" page

Finding Donors

1. Navigate to "Find Donors" page
2. View all active blood donation offers
3. Filter by:
   • Blood type
   • City
   • State
4. See donor information:
   • Blood type and quantity
   • Location
   • Available date
   • Contact number
5. Call donor directly to coordinate

---

🛠️ Tech Stack

Frontend

Technology	Version	Purpose
React	18.2.0	UI library for building components
React Router	6.10.0	Client-side routing and navigation
Axios	1.3.4	HTTP client for API requests
Tailwind CSS	3.3.0	Utility-first CSS framework
Context API	Built-in	Global state management (auth)

Backend

Technology	Version	Purpose
Node.js	16+	JavaScript runtime environment
Express.js	4.18.2	Web application framework
MongoDB	5+	NoSQL database
Mongoose	7.0.0	MongoDB object modeling (ODM)
JWT	9.0.0	JSON Web Tokens for authentication
bcryptjs	2.4.3	Password hashing
CORS	2.8.5	Cross-origin resource sharing
dotenv	16.0.3	Environment variable management

Development Tools

• Nodemon - Auto-restart server on changes
• Postman - API testing and documentation
• MongoDB Compass - Database GUI for debugging
• Git - Version control

Deployment

• Frontend: Vercel / Netlify
• Backend: Render / Railway / Heroku
• Database: MongoDB Atlas (Cloud)

---

📊 Database Schema

Collections Overview

MongoDB: bloodvault
├── users (Donors + Hospitals)
├── inventories (Blood Stock)
└── bloodrequests (Needs + Offers)

Users Collection

{
  _id: ObjectId("..."),
  role: "donor" | "hospital" | "organization",
  
  // Common fields
  email: "user@example.com",
  password: "$2a$10$hashed_password...",
  phone: "+919876543210",
  city: "Mumbai",
  state: "Maharashtra",
  address: "123 Main Street",
  
  // Donor-specific
  name: "John Doe",
  bloodType: "O+",
  
  // Hospital-specific
  organizationName: "Apollo Hospital",
  hospitalSecretKey: "apollo123",
  
  // Timestamps
  createdAt: ISODate("2025-01-15T10:30:00Z"),
  updatedAt: ISODate("2025-01-20T14:45:00Z")
}

Indexes: email (unique), role, city, bloodType

Inventories Collection

{
  _id: ObjectId("..."),
  hospital: ObjectId("..."),  // Reference to User
  bloodType: "A+",
  quantity: 25,
  expiryDate: ISODate("2025-03-15T00:00:00Z"),
  status: "available" | "reserved" | "expired",
  
  // Location (copied from hospital for faster queries)
  city: "Mumbai",
  state: "Maharashtra",
  address: "Apollo Hospital, Bandra West",
  contactNumber: "+912212345678",
  
  // Timestamps
  createdAt: ISODate("2025-01-15T10:30:00Z"),
  updatedAt: ISODate("2025-02-01T09:15:00Z")
}

Indexes: hospital, bloodType, city, status, expiryDate

Blood Requests Collection

{
  _id: ObjectId("..."),
  requestType: "need" | "donation",
  requesterType: "hospital" | "donor",
  requester: ObjectId("..."),  // Reference to User
  
  // Blood details
  bloodType: "B+",
  quantity: 3,
  requiredBy: ISODate("2025-02-10T00:00:00Z"),
  urgency: "normal" | "moderate" | "urgent",  // Auto-calculated
  
  // Location
  city: "Delhi",
  state: "Delhi",
  address: "Max Hospital, Saket",
  
  // Patient info (only for "need" requests)
  patientName: "Jane Smith",
  patientContact: "+919876543210",
  
  // Contact info
  contactPerson: "Dr. Kumar",
  contactNumber: "+911112345678",
  notes: "Emergency surgery required",
  
  // Status
  status: "active" | "fulfilled" | "cancelled",
  isPublic: true,
  
  // Timestamps
  createdAt: ISODate("2025-01-18T14:20:00Z"),
  updatedAt: ISODate("2025-01-19T11:30:00Z")
}

Indexes: requester, requestType, bloodType, city, status, urgency

---

🔌 API Reference

Base URL

Production: https://api.bloodvault.com/api
Development: http://localhost:5000/api

Authentication Endpoints

Register User

POST /api/auth/register
Content-Type: application/json

{
  "role": "donor",
  "name": "John Doe",
  "email": "john@example.com",
  "password": "password123",
  "phone": "+919876543210",
  "bloodType": "O+",
  "city": "Mumbai",
  "state": "Maharashtra",
  "address": "123 Main St"
}

Response (201):
{
  "success": true,
  "message": "User registered successfully",
  "data": {
    "_id": "...",
    "name": "John Doe",
    "email": "john@example.com",
    "role": "donor",
    "token": "eyJhbGc..."
  }
}

Login User

POST /api/auth/login
Content-Type: application/json

{
  "email": "john@example.com",
  "password": "password123"
}

Response (200):
{
  "success": true,
  "token": "eyJhbGc...",
  "user": {
    "_id": "...",
    "name": "John Doe",
    "email": "john@example.com",
    "role": "donor",
    "bloodType": "O+",
    "city": "Mumbai",
    "state": "Maharashtra"
  }
}

Get Current User

GET /api/auth/me
Authorization: Bearer <token>

Response (200):
{
  "success": true,
  "user": { ... }
}

Public Endpoints (No Auth)

Search Blood Stock

GET /api/public/search-blood?bloodType=A+&city=Mumbai&state=Maharashtra

Response (200):
{
  "success": true,
  "count": 3,
  "data": [
    {
      "_id": "...",
      "bloodType": "A+",
      "quantity": 15,
      "expiryDate": "2025-11-15T00:00:00.000Z",
      "city": "Mumbai",
      "state": "Maharashtra",
      "address": "Apollo Hospital, Bandra",
      "contactNumber": "+912212345678",
      "hospital": {
        "organizationName": "Apollo Hospital",
        "phone": "+912212345678"
      }
    }
  ]
}

Get Public Blood Needs

GET /api/public/blood-needs?bloodType=B+&city=Delhi

Response (200):
{
  "success": true,
  "count": 2,
  "data": [
    {
      "_id": "...",
      "requestType": "need",
      "bloodType": "B+",
      "quantity": 3,
      "requiredBy": "2025-10-20T00:00:00.000Z",
      "urgency": "urgent",
      "city": "Delhi",
      "patientName": "Patient Name",
      "contactPerson": "Dr. Smith",
      "contactNumber": "+911112345678",
      "requester": {
        "organizationName": "Max Hospital"
      }
    }
  ]
}

Inventory Endpoints (Hospital Only)

Upload Blood Stock

POST /api/inventory/upload
Authorization: Bearer <hospital_token>
Content-Type: application/json

{
  "bloodType": "O+",
  "quantity": 20,
  "expiryDate": "2025-12-31",
  "city": "Mumbai",
  "state": "Maharashtra",
  "address": "Apollo Hospital, Bandra",
  "contactNumber": "+912212345678"
}

Response (201):
{
  "success": true,
  "message": "Blood stock uploaded successfully",
  "data": { ... }
}

Get My Inventory

GET /api/inventory/my-inventory
Authorization: Bearer <hospital_token>

Response (200):
{
  "success": true,
  "count": 5,
  "data": [...]
}

Update Inventory

PUT /api/inventory/:id
Authorization: Bearer <hospital_token>
Content-Type: application/json

{
  "quantity": 15,
  "status": "available"
}

Delete Inventory

DELETE /api/inventory/:id
Authorization: Bearer <hospital_token>

Response (200):
{
  "success": true,
  "message": "Blood inventory deleted successfully"
}

Blood Request Endpoints

Create Blood Request

POST /api/blood-requests/create
Authorization: Bearer <token>
Content-Type: application/json

{
  "requestType": "need",
  "requesterType": "hospital",
  "bloodType": "A+",
  "quantity": 3,
  "requiredBy": "2025-10-25",
  "city": "Mumbai",
  "state": "Maharashtra",
  "patientName": "Patient Name",
  "patientContact": "+919876543210",
  "contactPerson": "Dr. Smith",
  "contactNumber": "+912212345678",
  "notes": "Emergency surgery"
}

Response (201):
{
  "success": true,
  "message": "Blood request created successfully",
  "data": { ... }
}

Get All Blood Requests

GET /api/blood-requests/all?requestType=donation&bloodType=O+&city=Delhi
Authorization: Bearer <token>

Query Parameters:
- requestType: need | donation
- bloodType: A+, B+, O+, etc.
- city: City name
- state: State name
- status: active | fulfilled | cancelled
- urgency: normal | moderate | urgent

Get My Requests

GET /api/blood-requests/my-requests
Authorization: Bearer <token>

Response (200):
{
  "success": true,
  "count": 2,
  "data": [...]
}

Update Request Status

PUT /api/blood-requests/:id/status
Authorization: Bearer <token>
Content-Type: application/json

{
  "status": "fulfilled"
}

Delete Request

DELETE /api/blood-requests/:id
Authorization: Bearer <token>

Response (200):
{
  "success": true,
  "message": "Blood request deleted successfully"
}

---

🧪 Testing

Test User Accounts

After running seed script (node seedData.js):

Hospitals:

Email: apollohospital@hospital.com
Password: password123
Secret Key: apollo123

Email: maxhealthcare@hospital.com
Password: password123
Secret Key: max123

Donors:

Email: donor1@gmail.com to donor16@gmail.com
Password: password123

Testing Workflows

Workflow 1: Public Blood Search

1. Visit homepage (no login)
2. Click "Search Blood"
3. Select: Blood Type = A+, City = Mumbai
4. Verify: See available blood from hospitals
5. Click hospital contact number
6. Expected: Can call/email hospital directly

Workflow 2: Hospital Uploads Stock

1. Login as: apollohospital@hospital.com
2. Click "Upload Blood Stock"
3. Fill: O+ blood, 50 units, expiry 30 days from now
4. Submit
5. Verify: Appears in "My Inventory"
6. Logout
7. Go to "Search Blood" (public)
8. Search for O+ in Mumbai
9. Expected: See uploaded blood in results

Workflow 3: Donor Offers Blood

1. Login as: donor1@gmail.com
2. Click "Offer Blood Donation"
3. Fill form with donation details
4. Submit
5. Verify: Appears in "Manage Requests"
6. Logout
7. Login as hospital
8. Go to "Find Donors"
9. Expected: See donor's offer

---

🗺️ Roadmap

Phase 1: Core Features ✅ Complete

• User authentication (donors and hospitals)
• Public blood search (no login)
• Hospital inventory management
• Blood request system (needs + offers)
• Location-based filtering
• Dashboard analytics

Phase 2: Enhanced Features 🚧 In Progress

• Email notifications for matches
• SMS alerts for urgent needs
• Blood donation history tracking
• Hospital verification system
• Advanced search filters
• Mobile responsive design improvements

Phase 3: Advanced Capabilities 📋 Planned

• Mobile app (React Native)
• Real-time chat between users
• Blood donation appointments
• Donation camps management
• Analytics and reporting dashboard
• Multi-language support
• Integration with health records
• AI-based blood demand prediction

---

🤝 Contributing

We welcome contributions from the community! Here's how you can help:

Ways to Contribute

• 🐛 Report Bugs - Found an issue? Let us know!
• ✨ Suggest Features - Have ideas? We'd love to hear them
• 📝 Improve Documentation - Help others understand the project
• 💻 Submit Code - Fix bugs or add features
• 🧪 Test - Help us find issues before users do
• 🌐 Translate - Make BloodVault accessible to more people

Contribution Guidelines

1. Fork the repository
2. Create a 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

Coding Standards

• Write clear, commented code
• Follow existing code style (Prettier/ESLint)
• Test your changes thoroughly
• Update documentation as needed
• Keep commits atomic and meaningful

**Made with ❤️ for saving