Skip to content

README.md

Latest commit

 

History

History
229 lines (181 loc) · 8.69 KB

README.md

File metadata and controls

229 lines (181 loc) · 8.69 KB

CertiTrust - Advanced Certificate Verification System

This project is a smart, scalable, and secure certificate verification system with ML-powered authenticity detection for comprehensive certificate validation.

🆕 NEW: SPOC Alert System

Automatic notifications when certificates are not found during verification!

  • 🔔 Real-time Alerts: Instant notifications on SPOC dashboard when verification fails
  • 📊 Smart Detection: Automatically triggered when certificate hash not found in database
  • 🎯 Actionable Interface: Resolve or dismiss alerts with one click
  • 🔄 Auto-refresh: Dashboard updates every 30 seconds
  • 👨‍🎓 Student Details: Shows student name, roll number, and verification attempt details
  • 🎨 Severity-based UI: Color-coded alerts (Critical=Red, Warning=Yellow, Info=Blue)

📚 Quick Start: See QUICK_START_ALERTS.md for 3-step setup (takes 3 minutes!)

🚀 Features

Core Verification

  • 🏛️ Institution Management: Complete database of educational institutions
  • 🔗 IPFS Integration: Secure certificate storage via Pinata with per-institution organization
  • 🔍 Hash Verification: SHA-256 based file integrity verification
  • 🔗 Blockchain Anchoring: Certificate hashes anchored on blockchain for immutability
  • 🤖 SIH ML Authentication: MobileNetV2-based AI model for certificate authenticity detection

Advanced Processing

  • 🧠 Two-Step Verification: Database lookup with ML fallback for comprehensive validation
  • 🎯 SIH Classifier Integration: Custom MobileNetV2 model trained on real vs fake certificates
  • 🤖 OCR Extraction: Automatic extraction of student information from certificate images
    • Student name detection
    • Roll number/Student ID extraction
    • Certificate type identification (Bachelor, Master, Diploma, etc.)
    • Marks/Grade/CGPA parsing
    • Issue date recognition
  • 📊 Smart Metadata: OCR-extracted data automatically stored as searchable IPFS metadata

AI/ML Features

  • 🎯 SIH Model Architecture: MobileNetV2 + Dense layers (224x224x3 input, 2-class softmax output)
  • 📊 Confidence Scoring: HIGH/MODERATE/LOW confidence levels with detailed probability analysis
  • 🔄 Model Conversion: Automated TensorFlow.js conversion from Keras .h5 models
  • 🛡️ Fallback System: Graceful handling when ML models are unavailable

Database Management

  • 🏢 Institution Database: Comprehensive institution registry with verification portals
  • 👥 Student Management: Individual and bulk student registration
  • 📜 Certificate Tracking: Complete certificate lifecycle management
  • � Analytics Dashboard: Real-time insights and system analytics

Administrative Features

  • 👨‍💼 Admin Dashboard: System analytics and activity monitoring (/admin)
  • 🗄️ Database Admin: Institution and student management interface (/database)
  • 📥 Bulk Import: CSV import for student data
  • 🔔 Activity Logging: Comprehensive audit trail

🆕 SPOC Alert System

  • 🚨 Automatic Alerts: Creates alerts when certificate verification fails
  • 📊 Dashboard Integration: Real-time alert display on SPOC dashboard
  • 🎯 Smart Notifications: Includes student info, hash, verifier details
  • ⚡ Instant Actions: Resolve or dismiss alerts with one click
  • 🔄 Auto-refresh: Updates every 30 seconds without page reload
  • 📈 Statistics: Alert counts by severity (Critical, Warning, Info)
  • 🔍 Investigation Tools: Full details for fraud detection and follow-up

🏗️ System Architecture

Database Components

  1. Institution Registry: Educational institutions with verification endpoints
  2. Student Database: Student profiles linked to institutions
  3. Certificate Records: Certificate metadata with IPFS and blockchain references
  4. Verification Logs: Activity tracking and audit trails

Data Flow

  1. Upload: Certificate + student info → IPFS + blockchain anchor
  2. Database: Auto-link student, institution, and certificate
  3. Verification: Cross-reference against database records
  4. Analytics: Real-time dashboard updates

📱 User Interface

Main Routes

  • /: Landing page with navigation
  • /upload: Certificate upload with institution selection
  • /check: Certificate verification interface
  • /admin: System analytics and activity monitoring
  • /database: Institution and student management

🤖 SIH ML Model Setup

Model Architecture

  • Base Model: MobileNetV2 (ImageNet weights, frozen)
  • Architecture: MobileNetV2 → GlobalAveragePooling2D → Dense(128) → Dropout(0.5) → Dense(64) → Dropout(0.5) → Dense(2, softmax)
  • Input: 224x224x3 RGB images
  • Output: 2-class categorical (REAL_CERT vs FAKE_CERT)
  • Training: Adam optimizer (0.0001), categorical crossentropy, early stopping

Model Conversion & Setup

Method 1: Automated Conversion (Recommended)

# Windows
.\convert-sih-model.bat

# Linux/Mac
python convert_sih_model.py

Method 2: Manual Conversion

# Install converter
pip install "tensorflowjs>=3.20.0,<4.0.0"

# Convert model
tensorflowjs_converter \
    --input_format=keras \
    --output_format=tfjs_layers_model \
    public/certificate_classifier.h5 \
    public/model

Method 3: Generate Model (if you don't have .h5 file)

  1. Open public/CNN_SIH.ipynb in Jupyter/VS Code
  2. Update the data paths in the notebook
  3. Run all cells to train and save certificate_classifier.h5
  4. Use Method 1 or 2 above to convert

Expected Output Structure

public/model/
├── model.json              # Model architecture
├── group1-shard1of1.bin   # Model weights
└── sih_model_info.json    # Metadata

Verification Workflow

  1. Step 1: Database hash lookup (instant)
  2. Step 2: If not found → SIH ML analysis (2-3 seconds)
  3. Result: Combined confidence with detailed breakdown

Available Scripts

npm start

Runs the app in the development mode.
Open http://localhost:3000 to view it in your browser.

OCR Features

  • Automatic Processing: OCR runs automatically when you upload image files (JPG, PNG)
  • Smart Detection: Uses advanced patterns to extract key information from various certificate formats
  • Metadata Integration: Extracted data is automatically included in IPFS metadata for better searchability
  • Fallback Support: Works even if OCR endpoint is unavailable (demo text)

Dependencies

  • Llama OCR Endpoint: Configure via .env (REACT_APP_LLAMA_OCR_URL)
  • React 19.1.1: Modern React with latest features
  • IPFS/Pinata: Decentralized storage
  • TensorFlow.js: ML model inference in browser

🗂️ Current Metadata Structure

Each uploaded certificate includes up to 9 metadata fields:

{
  institution: "Ranchi University",
  folder: "Ranchi_University", 
  category: "academic_certificate",
  state: "Jharkhand",
  uploadDate: "2025-09-10",
  studentName: "John Doe",           // 🤖 OCR extracted
  rollNumber: "RU2021001",           // 🤖 OCR extracted  
  certType: "Bachelor of Science",   // 🤖 OCR extracted
  marks: "85.5%"                     // 🤖 OCR extracted
}

🏛️ Supported Institutions

  • Universities: Ranchi University, Sido Kanhu Murmu University, etc.
  • Technical: IIT Dhanbad, NIT Jamshedpur, BIT Mesra, etc.
  • Medical: RIMS, MGM Medical College, etc.
  • Management: XLRI, IIM Ranchi, etc.
  • Arts & Science: St. Xavier's College, Gossner College, etc.

🔐 Admin Access

Navigate to /admin to access the admin dashboard for:

  • Managing verified records
  • Blacklist management
  • Audit logs viewing
  • System settings

📥 Bulk Operations

Navigate to /import for:

  • CSV/JSON bulk import
  • Institution data management

🚨 Alert System (NEW!)

Quick Setup

# 1. Run SQL script
# Copy database/setup-alerts.sql → Supabase SQL Editor → Run

# 2. Test alerts
npm start
# Upload non-existent certificate at /hr/verify
# Check SPOC dashboard for alerts

Documentation

  • QUICK_START_ALERTS.md - 3-minute setup guide
  • ALERT_SYSTEM_GUIDE.md - Complete documentation
  • ALERT_IMPLEMENTATION_SUMMARY.md - Technical details
  • database/setup-alerts.sql - Database schema

Features

✅ Auto-create alerts when certificate not found
✅ Real-time dashboard updates (30s refresh)
✅ Color-coded severity (🔴 Critical, 🟡 Warning, 🔵 Info)
✅ One-click Resolve/Dismiss actions
✅ Student details + verification history
✅ Alert statistics and analytics

🛠️ Technical Details

Built with Create React App and modern web technologies for a state-wide certificate verification system.