BloodHub - Blood Management System

A comprehensive Spring Boot web application for managing blood donation requests, connecting donors with recipients, and managing hospital information.

🚀 Features

Core Functionality

• User Management: Registration, authentication, and profile management
• Blood Request Management: Post, view, edit, and manage blood donation requests
• Hospital Directory: Find and manage nearby hospitals and blood banks
• Search & Filter: Advanced search capabilities for blood requests and donors
• Real-time Updates: Dynamic content updates and notifications

User Roles

• Regular Users: Can post blood requests, search for donors, and view hospital information
• Administrators: Full system access including user management and system configuration

Security Features

• Spring Security integration with BCrypt password encoding
• Role-based access control
• Secure session management
• CSRF protection

🛠️ Technology Stack

Backend

• Java 11
• Spring Boot 2.7.14
• Spring Data JPA
• Spring Security
• MySQL 8.0

Frontend

• Thymeleaf (Server-side templating)
• Bootstrap 5.1.3 (Responsive UI framework)
• Font Awesome 6.0.0 (Icons)
• Custom CSS & JavaScript

Build Tools

• Maven (Dependency management and build)
• Gradle Wrapper (Alternative build option)

📋 Prerequisites

Before running this application, ensure you have:

• Java 11 or higher
• MySQL 8.0 or higher
• Maven 3.6 or higher
• Git (for cloning the repository)

🚀 Quick Start

1. Clone the Repository

git clone <repository-url>
cd blood-management-system

2. Database Setup

1. Create a MySQL database:

CREATE DATABASE blood_management;

2. Update database configuration in src/main/resources/application.properties:

spring.datasource.url=jdbc:mysql://localhost:3306/blood_management?createDatabaseIfNotExist=true&useSSL=false&serverTimezone=UTC
spring.datasource.username=your_username
spring.datasource.password=your_password

3. Build and Run

# Using Maven
mvn clean install
mvn spring-boot:run

# Or using the JAR file
java -jar target/blood-management-system-0.0.1-SNAPSHOT.jar

4. Access the Application

Open your browser and navigate to: http://localhost:8080/bloodhub

🏗️ Project Structure

src/
├── main/
│   ├── java/
│   │   └── com/
│   │       └── bloodhub/
│   │           ├── BloodManagementApplication.java
│   │           ├── config/
│   │           │   └── SecurityConfig.java
│   │           ├── controller/
│   │           │   ├── AuthController.java
│   │           │   ├── BloodRequestController.java
│   │           │   ├── DashboardController.java
│   │           │   ├── HomeController.java
│   │           │   └── HospitalController.java
│   │           ├── entity/
│   │           │   ├── User.java
│   │           │   ├── BloodRequest.java
│   │           │   ├── Hospital.java
│   │           │   ├── Role.java
│   │           │   └── enums/
│   │           ├── repository/
│   │           │   ├── UserRepository.java
│   │           │   ├── BloodRequestRepository.java
│   │           │   └── HospitalRepository.java
│   │           └── service/
│   │               ├── UserService.java
│   │               ├── BloodRequestService.java
│   │               └── HospitalService.java
│   └── resources/
│       ├── static/
│       │   ├── css/
│       │   │   └── style.css
│       │   └── js/
│       │       └── script.js
│       ├── templates/
│       │   ├── auth/
│       │   │   ├── login.html
│       │   │   ├── register.html
│       │   │   └── forgot-password.html
│       │   ├── blood-requests/
│       │   │   ├── list.html
│       │   │   ├── create.html
│       │   │   └── view.html
│       │   ├── dashboard.html
│       │   └── home.html
│       └── application.properties

🔧 Configuration

Application Properties

Key configuration options in application.properties:

# Server Configuration
server.port=8080
server.servlet.context-path=/bloodhub

# Database Configuration
spring.datasource.url=jdbc:mysql://localhost:3306/blood_management
spring.datasource.username=root
spring.datasource.password=password

# JPA Configuration
spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true

# Security Configuration
spring.security.user.name=admin
spring.security.user.password=admin

Environment Variables

You can override configuration using environment variables:

export SPRING_DATASOURCE_URL=jdbc:mysql://localhost:3306/blood_management
export SPRING_DATASOURCE_USERNAME=your_username
export SPRING_DATASOURCE_PASSWORD=your_password

📊 Database Schema

Core Tables

• users: User accounts and profiles
• roles: User roles and permissions
• user_roles: Many-to-many relationship between users and roles
• blood_requests: Blood donation requests
• hospitals: Hospital and blood bank information

Key Relationships

• Users can have multiple roles
• Blood requests are associated with users
• Hospitals are categorized by division

🔐 Security

Authentication

• Form-based login with Spring Security
• Password encryption using BCrypt
• Session management with remember-me functionality

Authorization

• Role-based access control
• URL-level security constraints
• Method-level security annotations

CSRF Protection

• Enabled by default
• Token-based protection for all forms
• Exceptions for specific endpoints if needed

🌐 API Endpoints

Public Endpoints

• GET / - Home page
• GET /home - Home page
• GET /login - Login page
• GET /register - Registration page
• GET /forgot-password - Password reset page

Protected Endpoints

• GET /dashboard - User dashboard
• GET /profile - User profile
• GET /blood-requests - List blood requests
• POST /blood-requests/create - Create blood request
• GET /hospitals/nearby - Find nearby hospitals

Admin Endpoints

• GET /admin/** - Admin panel (requires ADMIN role)

🎨 UI Components

Responsive Design

• Mobile-first approach using Bootstrap 5
• Responsive navigation and layouts
• Touch-friendly interface elements

Interactive Features

• Dynamic form validation
• Real-time search and filtering
• Smooth animations and transitions
• Toast notifications

Theme Support

• Light/dark theme toggle
• Customizable color schemes
• Consistent branding throughout

🧪 Testing

Running Tests

# Unit tests
mvn test

# Integration tests
mvn verify

# All tests with coverage
mvn clean test jacoco:report

Test Structure

• Unit tests for services and controllers
• Integration tests for repositories
• End-to-end tests for critical workflows

🚀 Deployment

Production Build

mvn clean package -Pprod

Docker Support

FROM openjdk:11-jre-slim
COPY target/blood-management-system-0.0.1-SNAPSHOT.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "/app.jar"]

Environment-Specific Configurations

• Development: application-dev.properties
• Production: application-prod.properties
• Testing: application-test.properties

📈 Monitoring & Logging

Logging Configuration

• Logback for logging framework
• Configurable log levels
• Structured logging for production

Health Checks

• Spring Boot Actuator endpoints
• Database connectivity checks
• Application health status

🔄 Database Migrations

Initial Setup

The application automatically creates the database schema on first run using:

• spring.jpa.hibernate.ddl-auto=update
• Entity annotations for table creation

Schema Updates

• Automatic schema evolution
• Data migration scripts (if needed)
• Version control for database changes

🤝 Contributing

Development Setup

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

Code Standards

• Follow Java coding conventions
• Use meaningful variable and method names
• Add comprehensive documentation
• Include unit tests for new features

📝 License

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

🙏 Acknowledgments

• Spring Boot team for the excellent framework
• Bootstrap team for the responsive UI components
• Font Awesome for the icon library
• The open-source community for various libraries and tools

📞 Support

For support and questions:

• Create an issue in the GitHub repository
• Check the documentation
• Review existing issues and discussions

🔮 Roadmap

Planned Features

• Real-time notifications
• Mobile app (React Native/Flutter)
• Advanced analytics dashboard
• Integration with external blood banks
• SMS/Email notifications
• Multi-language support
• API documentation (Swagger)
• Performance monitoring
• Automated testing pipeline

Version History

• v0.0.1-SNAPSHOT: Initial release with core functionality

---

BloodHub - Connecting blood donors with those in need, one request at a time. ❤️