🏛️ Algerian Medical Passport Blockchain System

Revolutionizing Healthcare Through Blockchain Technology

A comprehensive, secure, and patient-controlled medical data management system for Algeria

The Algerian Medical Passport is a revolutionary blockchain-based healthcare ecosystem that provides secure, transparent, and patient-controlled medical data management. Built on cutting-edge Web3 technologies, it serves as the first comprehensive medical passport system in Algeria and the MENA region.

• 🔐 Patient-Controlled Data: Complete data sovereignty for patients
• 🏛️ Government Verified: Official medical ID issuance and regulation
• 🏢 Multi-Stakeholder: Serves all healthcare ecosystem participants
• 📱 Mobile-First: Responsive design for all devices
• 🌐 Multi-Network: Supports Polygon, Ethereum, and local networks
• 🔒 Enterprise Security: Military-grade encryption and security
• ⚡ Real-Time: Instant verification and updates
• 🌍 Interoperable: Cross-platform medical record sharing

The system serves six main stakeholders in a comprehensive healthcare ecosystem:

• Blockchain Networks: Polygon, Ethereum, Hardhat Local
• Smart Contracts: Solidity 0.8.19
• Development Framework: Hardhat
• Web3 Library: Ethers.js v5
• Wallet Integration: MetaMask

• Framework: React 18+ with TypeScript
• UI Library: Material-UI (MUI)
• State Management: React Hooks + Context
• Form Handling: Formik with Yup validation
• Styling: Responsive CSS with Mobile-First approach

• Runtime: Node.js 16+
• Framework: Express.js
• Database: MongoDB (optional), IPFS for documents
• Authentication: JWT tokens
• Security: Helmet, CORS, Rate limiting
• Logging: Winston

• Package Manager: npm
• Testing: Hardhat tests, Jest
• Linting: ESLint, Prettier
• Version Control: Git
• CI/CD Ready: GitHub Actions compatible

algerian-medical-passport-blockchain/
├── 📄 contracts/                    # Smart contracts (Solidity)
│   ├── IdentityManagement.sol      # Medical ID issuance & verification
│   ├── MedicalRecords.sol          # Medical record storage & access
│   ├── PrescriptionManagement.sol  # Prescription lifecycle
│   └── AccessControl.sol           # Permission management
│
├── 📱 frontend/                     # React + TypeScript application
│   ├── src/
│   │   ├── components/             # Reusable UI components
│   │   ├── pages/                  # Route components
│   │   ├── hooks/                  # Custom React hooks
│   │   ├── config/                 # Configuration files
│   │   └── types/                  # TypeScript definitions
│   └── public/
│       └── healty1.png             # Custom logo
│
├── ⚙️ backend/                      # Node.js API server
│   ├── src/
│   │   ├── controllers/            # Request handlers
│   │   ├── middleware/             # Authentication & validation
│   │   ├── routes/                 # API routes
│   │   └── services/               # Business logic
│   └── tests/                      # Backend tests
│
├── 📋 scripts/                     # Deployment & utility scripts
│   ├── deploy.js                   # Contract deployment
│   └── setupDemo.js                # Demo data setup
│
├── 🧪 test/                        # Smart contract tests
├── 📆 demo/                        # Demo & presentation files
│   ├── EXECUTIVE_PRESENTATION.html # Executive presentation
│   └── DEMO_WALKTHROUGH.html       # Interactive demo guide
│
├── 📝 docs/                        # Documentation
│   └── SYSTEM_ARCHITECTURE.md      # Comprehensive system docs
│
├── 🏠 .env.example                 # Environment variables template
├── ⚙️ hardhat.config.js             # Hardhat configuration
├── 📦 package.json                 # Main package configuration
└── 📋 README.md                   # You are here!

Before you begin, ensure you have the following installed:

• Node.js (>= 16.0.0) - Download here
• npm (>= 8.0.0) - Comes with Node.js
• MetaMask browser extension - Install here
• Git - Download here

# Clone the repository
git clone https://github.com/nasrosoft/algerian-medical-passport-blockchain.git

# Navigate to project directory
cd algerian-medical-passport-blockchain

# Install dependencies for all packages
npm install

# Copy environment template
cp .env.example .env

# Edit .env file with your configuration (optional for local development)
# nano .env

# Terminal 1: Start local Hardhat blockchain
npm run node

# Terminal 2: Deploy contracts to local network
npm run deploy:local

# Set up demo data with sample users and records
npx hardhat run scripts/setupDemo.js --network localhost

# Option 1: Start all services simultaneously
npm run dev

# Option 2: Start services individually
# Frontend (Terminal 1)
cd frontend && npm start

# Backend (Terminal 2)
cd backend && npm run dev

The application automatically detects your network and provides guidance for setup. For manual configuration:

Localhost Network:

• Network Name: Localhost 8545
• New RPC URL: http://localhost:8545
• Chain ID: 1 (or 1337)
• Currency Symbol: ETH

# Run all smart contract tests
npm test

# Run tests with coverage report
npm run coverage

# Run specific test file
npx hardhat test test/IdentityManagement.test.js

# Run tests with gas reporting
npm test -- --gas

# Frontend tests
cd frontend && npm test

# Backend tests
cd backend && npm test

# E2E tests (if available)
npm run test:e2e

# Set up environment variables for testnet
export PRIVATE_KEY="your_private_key"
export POLYGON_MUMBAI_URL="your_rpc_url"

# Deploy to testnet
npm run deploy:testnet

# Verify contracts
npm run verify

1. Visit Polygon Faucet
2. Enter your wallet address
3. Request testnet MATIC tokens

After running the demo setup script, you'll have the following test accounts:

1. Patient Registration

   • Connect as Patient and register through the system
   • Government approves and issues medical ID

2. Doctor-Patient Consultation

   • Patient grants access to doctor
   • Doctor creates medical records
   • Patient can view their records

3. Prescription Workflow

   • Doctor issues prescription during consultation
   • Patient receives prescription notification
   • Pharmacy verifies and dispenses medication

4. Access Control Management

   • Patient grants/revokes doctor access
   • Time-limited permissions
   • Emergency access controls

5. Government Analytics

   • View system-wide statistics
   • Monitor healthcare provider activity
   • Generate anonymized reports

• Complete Control: Patients own and control their medical data
• Granular Permissions: Grant/revoke access to specific providers
• Time-Limited Access: Temporary permissions with automatic expiration
• Emergency Protocols: Special access controls for critical situations
• Audit Trail: Complete history of data access and permissions

• Medical ID Issuance: Secure, blockchain-based identity verification
• Provider Verification: Healthcare provider license validation
• System Analytics: Privacy-preserving healthcare insights
• Regulatory Compliance: Built-in compliance with healthcare regulations
• Policy Enforcement: Automated enforcement of healthcare policies

• Instant Access: Real-time access to patient medical history (with permission)
• Immutable Records: Tamper-proof medical record creation
• Smart Prescriptions: Cryptographically secured prescription management
• Multi-Stakeholder: Seamless coordination between hospitals, clinics, and doctors
• Treatment Tracking: Complete treatment outcome monitoring

• Real-Time Verification: Instant prescription authenticity validation
• Fraud Prevention: Blockchain-based anti-counterfeiting
• Dispensing History: Complete medication dispensing records
• Inventory Management: Track medication stock and expiration
• Drug Interaction Alerts: Safety warnings for medication conflicts

• End-to-End Encryption: AES-256 encryption for sensitive data
• Multi-Signature Controls: Multi-party authorization for critical operations
• Role-Based Access: Granular permission system by user type
• Zero-Knowledge Ready: Privacy-preserving analytics capabilities
• GDPR Compliance: Built-in data protection regulation adherence

• Mobile-First Design: Responsive interface for all devices
• Multi-Language Support: Arabic, French, English interfaces
• Real-Time Notifications: Instant updates on medical activities
• Intuitive Dashboards: Role-specific user interfaces
• Offline Capabilities: Essential functions work without internet

# Set up environment variables
export PRIVATE_KEY="your_private_key_here"
export POLYGON_MUMBAI_URL="your_polygon_rpc_url"
export POLYGONSCAN_API_KEY="your_polygonscan_api_key"

# Deploy to Mumbai testnet
npm run deploy:testnet

# Verify contracts on Polygonscan
npm run verify:testnet

# Set up mainnet environment variables
export PRIVATE_KEY="your_production_private_key"
export POLYGON_MAINNET_URL="your_polygon_mainnet_rpc"
export POLYGONSCAN_API_KEY="your_polygonscan_api_key"

# Deploy to mainnet (use with caution)
npm run deploy:mainnet

# Verify contracts
npm run verify:mainnet

1. Polygon Mumbai Faucet: https://faucet.polygon.technology/
2. Alchemy Polygon Faucet: https://www.alchemy.com/faucets/polygon-mumbai

We welcome contributions to the Algerian Medical Passport project! Here's how you can help:

1. Check existing issues to avoid duplicates
2. Use the issue templates when available
3. Provide detailed reproduction steps
4. Include environment details (OS, Node.js version, etc.)

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

• Follow TypeScript/JavaScript best practices
• Write comprehensive tests for new features
• Update documentation for API changes
• Use conventional commit messages
• Ensure all tests pass before submitting PR

Help improve our documentation:

• Fix typos and improve clarity
• Add examples and use cases
• Translate to Arabic or French
• Create video tutorials

• Project Lead: Mohammed TAMALI Abdelmadjid LARBI
• Blockchain Developer: nasrosoft
• Frontend Developer: nasrosoft
• Backend Developer: nasrosoft

• Email: amdlarbi@gmail.com / mtamali@gmail.com / nasrosoft.dev@gmail.com
• Website: https://medical-passport.dz Loading..⏳
• LinkedIn: Mohammed TAMALI
• LinkedIn: Abdelmadjid LARBI
• LinkedIn: nasrosoft

• ✅ Core smart contracts development
• ✅ 6-stakeholder system implementation
• ✅ Multi-network support
• ✅ Comprehensive form validation
• ✅ Responsive UI/UX design

• 🔄 Mobile application (iOS/Android)
• 🔄 Advanced analytics dashboard
• 🔄 Multi-language support (Arabic/French)
• 🔄 IPFS integration for document storage
• 🔄 API marketplace for third-party integrations

• ⏳ Regional expansion (MENA countries)
• ⏳ Insurance company integrations
• ⏳ Cross-border medical record sharing
• ⏳ Government API integration
• ⏳ Healthcare research platform

• ⏳ AI-powered diagnostic assistance
• ⏳ Telemedicine platform integration
• ⏳ IoT medical device connectivity
• ⏳ Advanced privacy (homomorphic encryption)
• ⏳ Decentralized governance (DAO)

If you find this project useful, please consider:

• ⭐ Starring this repository
• 👤 Following for updates
• 👨‍💻 Contributing to the codebase
• 📢 Sharing with your network
• 📝 Writing about your experience

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

• ✅ Commercial use allowed
• ✅ Modification allowed
• ✅ Distribution allowed
• ✅ Private use allowed
• ⚠️ License and copyright notice required
• ❌ No warranty provided

Built with INNO in Algeria for the future of healthcare

🚀 Revolutionizing Healthcare Through Blockchain Technology 🚀