🩸 Blood Warriors - Project Pavlov

Connecting Thalassemia patients with blood donors through intelligent SMS communication

🎯 About Project Pavlov

Project Pavlov is an intelligent SMS-based blood donation system designed specifically to help Thalassemia patients find compatible blood donors. The system uses natural language processing and automated workflows to facilitate blood donation requests and donor registration through simple SMS conversations.

🎯 Mission

Bridge the gap between Thalassemia patients and blood donors
Simplify blood donation through accessible SMS communication
Ensure privacy and compliance with healthcare regulations
Provide education about Thalassemia and blood donation

🏥 Problem Statement

Thalassemia patients require regular blood transfusions, but finding compatible donors can be challenging. Traditional methods are often slow and inefficient, leading to delays in critical care.

✨ Features

🔄 SMS Conversation System

Intelligent Chatbot: Natural language processing for donor registration and blood requests
Multi-step Registration: Guided donor registration process via SMS
Blood Compatibility Matching: Automatic matching of compatible blood types
Educational Content: Thalassemia awareness and blood donation education

📊 Real-time Analytics Dashboard

Live Statistics: Real-time donor and request tracking
Interactive Charts: Daily registration trends and blood group availability
Compliance-focused: Privacy-protected donor information display
Responsive Design: Modern, accessible web interface

🔒 Privacy & Compliance

Data Hashing: Phone numbers and personal data are hashed for privacy
Healthcare Compliance: Designed according to healthcare data protection standards
Audit Trails: Complete tracking of all interactions and requests

🚨 Emergency Response

Urgent Blood Requests: Priority handling for emergency situations
Donor Notifications: Automated SMS alerts to compatible donors
Location-based Matching: Geographic proximity consideration

🏗️ Architecture

project-pavlov/
├── app.py                 # Flask backend server (route handlers)
├── streamlit_app.py       # Streamlit frontend dashboard
├── utils/                 # Modular utility functions
│   ├── constants.py       # Configuration constants
│   ├── data_utils.py      # API calls & data processing
│   ├── chart_utils.py     # Chart creation functions
│   ├── helpers.py         # Utility functions
│   ├── backend_utils.py   # Backend logic & state management
│   └── styles.py          # CSS styling & HTML templates
├── pyproject.toml         # Modern Python packaging
├── requirements.txt       # Legacy pip dependencies
└── README.md             # This file

🔧 Technology Stack

Backend: Flask (Python web framework)
Frontend: Streamlit (data science web app)
SMS: Twilio (communication platform)
Charts: Plotly (interactive visualizations)
Data: Pandas (data manipulation)

🚀 Quick Start

Prerequisites

Python 3.8 or higher
Twilio account (for SMS functionality)
ngrok (for local development with Twilio webhooks)

1. Clone the Repository

git clone https://github.com/bloodwarriors/project-pavlov.git
cd project-pavlov

2. Install Dependencies

Option A: Using `uv` (Recommended)

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .

Option B: Using `pip`

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e .

3. Configure Environment

# Copy environment template
cp .env.example .env

# Edit .env with your Twilio credentials
nano .env

4. Start the Application

# Terminal 1: Start Flask backend
python app.py

# Terminal 2: Start Streamlit frontend
streamlit run streamlit_app.py

📦 Installation

System Requirements

Python: 3.8 or higher
Memory: 512MB RAM minimum
Storage: 100MB free space
Network: Internet connection for Twilio SMS

Development Dependencies

For development and testing, install with dev dependencies:

# Using uv
uv pip install -e ".[dev]"

# Using pip
pip install -e ".[dev]"

Production Deployment

For production deployment, consider:

Database: Replace in-memory storage with PostgreSQL/MySQL
Caching: Add Redis for session management
Load Balancer: Use nginx for production traffic
SSL: Configure HTTPS for secure communications

⚙️ Configuration

Environment Variables

Create a .env file in the project root:

# Twilio Configuration
TWILIO_ACCOUNT_SID=your_account_sid_here
TWILIO_AUTH_TOKEN=your_auth_token_here
TWILIO_PHONE_NUMBER=+1234567890

# Flask Configuration
FLASK_ENV=development
FLASK_DEBUG=True

# Optional: Database Configuration (for production)
DATABASE_URL=postgresql://user:password@localhost/pavlov_db

Twilio Setup

Create Twilio Account: Sign up at twilio.com
Get Phone Number: Purchase a Twilio phone number
Configure Webhook: Set webhook URL to https://your-domain.com/webhook
Test SMS: Verify SMS functionality in Twilio console

🎮 Usage

SMS Interaction Flow

1. Donor Registration

User: hi
Bot: 🩸 Welcome to Blood Warriors - Project Pavlov!
     How can we help you today?
     1. 🩸 Register as Blood Donor
     2. 🚨 Request Blood
     3. 📚 Learn About Thalassemia
     4. 🆘 Get Help

User: 1
Bot: 🩸 Welcome to Blood Warriors Donor Registration!
     Please provide your blood type (A+, A-, B+, B-, AB+, AB-, O+, O-):

User: A+
Bot: Great! Now please provide your full name:

User: John Doe
Bot: Please provide your email address:

User: john@example.com
Bot: Please provide your location (city/district):

User: Mumbai
Bot: Please provide your age:

User: 25
Bot: Are you available for donation? (YES/NO):

User: YES
Bot: ✅ Registration Successful!
     You're now registered as a A+ donor in Mumbai.
     Donor ID: a1b2c3d4e5f6
     We'll notify you when someone needs your blood type.

2. Blood Request

User: 2
Bot: 🚨 Blood Request Form
     Please provide your blood type (A+, A-, B+, B-, AB+, AB-, O+, O-):

User: O+
Bot: What's the urgency level? (URGENT/NORMAL):

User: URGENT
Bot: Please provide your location (city/district):

User: Delhi
Bot: ✅ Blood Request Submitted!
     🚨 O+ blood needed in Delhi
     📞 We've notified 3 potential donors
     ⏰ We'll contact you within 30 minutes

Web Dashboard

SMS Simulator Tab

Test SMS conversations in real-time
Simulate donor registration and blood requests
Clear chat history while preserving donor data

Live Statistics Tab

Real-time metrics: Total donors, available donors, active requests
Interactive charts showing daily registration trends
Blood group availability visualization

Donor Registry Tab

Privacy-compliant donor listing
Hashed phone numbers for security
Blood group distribution charts

Blood Requests Tab

Anonymized request tracking
Urgency level monitoring
Request status management

Project Structure

utils/
├── constants.py       # Blood types, educational content, colors
├── data_utils.py      # API calls, data retrieval, health checks
├── chart_utils.py     # Plotly chart creation functions
├── helpers.py         # Validation, hashing, utility functions
├── backend_utils.py   # SMS handling, conversation logic, state management
└── styles.py          # CSS styling and HTML templates

📚 API Reference

Backend Endpoints

`POST /webhook`

Handles incoming SMS from Twilio

Input: Twilio webhook payload
Output: TwiML response

`GET /api/stats`

Returns system statistics

{
  "total_donors": 15,
  "available_donors": 12,
  "active_requests": 3,
  "total_requests": 25
}

`GET /api/donors`

Returns all registered donors (public data only)

{
  "+1234567890": {
    "blood_type": "A+",
    "location": "Mumbai",
    "available": true,
    "registered_at": "2025-08-04T10:30:00"
  }
}

`GET /api/requests`

Returns all blood requests

{
  "req_1": {
    "blood_type": "O+",
    "urgency": "urgent",
    "location": "Delhi",
    "status": "active",
    "created_at": "2025-08-04T11:00:00"
  }
}

`GET /health`

Health check endpoint

{
  "status": "healthy",
  "timestamp": "2025-08-04T11:00:00"
}

Frontend Components

SMS Simulator

File: streamlit_app.py (tab1)
Purpose: Test SMS conversations
Features: Real-time chat, message history, clear functionality

Analytics Dashboard

File: streamlit_app.py (tab2)
Purpose: View system statistics and charts
Features: Live metrics, interactive charts, responsive design

Donor Registry

File: streamlit_app.py (tab3)
Purpose: View registered donors
Features: Privacy-compliant display, blood group distribution

Blood Requests

File: streamlit_app.py (tab4)
Purpose: View blood requests
Features: Anonymized data, urgency tracking

📄 License

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

🙏 Acknowledgments

Thalassemia Patients: For inspiring this project
Blood Donors: For their life-saving contributions
Twilio: For providing SMS infrastructure
Streamlit: For the amazing web app framework
Open Source Community: For the tools and libraries

📞 Support

Email: Reach out to either Dhyaneesh or Akshath

🩸 Every blood donation saves up to 3 lives. You're not just donating blood - you're giving someone a chance to live! ❤️

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
utils		utils
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
app.py		app.py
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
streamlit_app.py		streamlit_app.py

License

deprecated-work/pavlov

Folders and files

Latest commit

History

Repository files navigation