Skip to content

bprdshield/verifychain-team-titans

BranchesTags

Repository files navigation

VerifyChain 🔐

License: MIT Python 3.11+ Next.js 14 FastAPI

🏆 2nd Runner-Up | SHIELD 1.0 Hackathon | BPR&D X MNIT Jaipur Best Solution for Track #3: Real-Time Database for Delivery Personnel Verification

📋 Table of Contents

🎯 Overview

VerifyChain is a comprehensive, AI-powered real-time verification database system designed to secure India's gig economy by enabling instant background verification of 10+ million delivery personnel and banking agents. The platform provides a centralized, decentralized verification network accessible to multiple stakeholders including law enforcement, employers, banks, and citizens.

Key Highlights

  • ✅ Multi-Stakeholder Platform: Serves workers, employers, police, banks, and citizens
  • ✅ Real-Time Verification: Instant QR code, OTP, and face recognition-based checks
  • ✅ AI-Powered Risk Analysis: Claude AI integration for intelligent threat detection
  • ✅ GPS Tracking: Live location monitoring and route validation
  • ✅ Trust Score System: Dynamic 0-100 scoring based on 6 weighted factors
  • ✅ Government Integration: Aadhaar/DigiLocker verification support
  • ✅ Enterprise-Ready: Built with scalability, security, and compliance in mind

🚨 Problem Statement

Challenge: Real-Time Database for Delivery Personnel Verification (Gig Workers) & Banking Agents

Context: With the explosive growth of India's gig economy (food delivery, e-commerce, banking agents), there's an urgent need for a centralized verification system that enables:

  1. Household Safety: On-demand identity verification for delivery personnel visiting homes
  2. Law Enforcement: Rapid background checks at checkpoints or incident sites
  3. Banking Security: Verification of Banking Correspondents (BC) handling Aadhaar Enabled Payment System (AePS)
  4. Regulatory Compliance: Streamlined police verification for gig workers

Target Beneficiaries:

  • 🏠 Citizens receiving deliveries at home
  • 👮 Police Officers conducting checkpoint verifications and investigations
  • 🏢 Employers (Swiggy, Zomato, Dunzo, Amazon, Flipkart)
  • 🏦 Banks authorizing agents for AePS transactions
  • 🛵 Gig Workers seeking legitimate employment and trust-building

💡 Solution

VerifyChain provides a comprehensive verification ecosystem that addresses all stakeholders' needs:

For Citizens

  • Scan QR codes on delivery personnel's devices for instant verification
  • Get color-coded risk status (🟢 GREEN / 🟡 YELLOW / 🔴 RED)
  • Track live delivery location with ETA
  • Report incidents directly through the platform

For Police Officers

  • Checkpoint verification via QR scan, phone lookup, or worker ID
  • Access complete worker history: employment, incidents, police records
  • AI-powered risk analysis with actionable recommendations
  • Real-time status checks and investigation tools
  • Pattern detection for coordinated fraud attempts

For Employers

  • Streamlined worker onboarding with Aadhaar verification
  • Create and assign delivery tasks with auto-generated QR codes
  • Real-time fleet tracking and analytics dashboard
  • Monitor worker performance and trust scores
  • Manage incident reports and compliance

For Banks

  • Verify Banking Correspondents before AePS transactions
  • Check agent authorization status in real-time
  • Maintain compliance with RBI regulations
  • Track agent performance and incident history

For Gig Workers

  • Quick registration with Aadhaar integration
  • Build trust through verified employment history
  • Display QR codes for easy verification
  • Track earnings and performance metrics
  • Transparent trust score with improvement tips

✨ Key Features

🔐 Multi-Method Verification System

1. QR Code Verification

  • Dynamic Time-Limited Tokens: HMAC-SHA256 signed tokens with 60-minute expiry
  • Replay Attack Prevention: Nonce-based system prevents token reuse
  • Embedded Assignment Data: Contains worker ID, employer ID, assignment details
  • Offline-First Design: Works with limited connectivity

2. OTP Verification

  • 6-Digit Codes: Redis-backed with 10-minute TTL
  • SMS/WhatsApp Delivery: Integrated with MSG91/Twilio
  • Door-to-Door Scenarios: Ideal for situations where QR scanning is difficult

3. Face Recognition

  • AWS Rekognition Integration: Enterprise-grade facial matching
  • Pre-Trip Selfie Verification: Match delivery personnel with registered photo
  • 90% Confidence Threshold: Prevents false positives from drawings/posters
  • Privacy-First: Face embeddings stored, not raw images

4. Phone Number Lookup

  • Instant Search: Direct database queries for emergency situations
  • Police Access: Available at checkpoints and investigation scenarios

🧠 AI-Powered Risk Intelligence

Claude AI Integration for:

  • Worker Risk Scoring: Comprehensive profile analysis with confidence levels
  • Anomaly Detection: Identifies unusual behavior patterns
  • Incident NLP Analysis: Extracts key entities from incident reports
  • Pattern Clustering: Detects coordinated fraud attempts
  • Fraud Detection: Behavioral analysis from verification history
  • Actionable Recommendations: Specific steps for police/employers

📊 Dynamic Trust Score System (0-100)

Calculated from 6 weighted components:

Component Weight Description
Background Score 20% Police verification status, criminal record checks
Employment Score 15% Tenure with employers, termination history
Performance Score 30% Total deliveries completed, customer ratings
Incident Score 15% Deductions based on severity (Low: -2, Critical: -10)
Compliance Score 10% Document validity, regulatory adherence
Verification Score 10% Successful verification count

Status Determination:

  • 🟢 GREEN (Safe): Score ≥70 + Clean record + No major incidents
  • 🟡 YELLOW (Caution): Score 40-69 or minor incidents
  • 🔴 RED (High Risk): Score <40 or flagged by police or ≥5 incidents

📍 Real-Time GPS Tracking

  • Continuous Location Logging: Updates every minute (configurable)
  • WebSocket Live Streaming: Real-time tracking interface
  • Route Validation: Detects deviations from expected paths
  • Geofencing Alerts: Notifications when leaving authorized zones
  • ETA Prediction: Accurate delivery time estimates using Google Maps API
  • Geocoding Services: Address ↔ Coordinates conversion

🚨 Comprehensive Incident Management

Incident Types:

  • Theft, Harassment, Fraud, Impersonation, Assault, Verbal Abuse, Property Damage, Suspicious Behavior

Severity Levels:

  • 🟢 Low → 🟡 Medium → 🟠 High → 🔴 Critical

Status Workflow:

  • Reported → Investigating → Resolved/Dismissed/Escalated

Features:

  • Geolocation tagging at time of report
  • Evidence URL storage (photos, videos)
  • AI-powered incident analysis
  • Reporter anonymity options
  • Automatic trust score adjustments

🏛️ Government Integration

  • Aadhaar Verification: DigiLocker OAuth integration for identity verification
  • Police Records API: Background check integration (mock mode available)
  • Regulatory Compliance: Aligns with BPR&D and RBI requirements
  • Data Privacy: Stores only Aadhaar hash, not full number

🏗️ Architecture

System Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         FRONTEND LAYER                          │
│                     (Next.js 14 + React 18)                     │
├─────────────────────────────────────────────────────────────────┤
│  Worker Portal  │  Police Portal  │  Employer Portal  │  Admin  │
│  Bank Portal    │  Public Verification  │  GPS Tracking         │
└─────────────────────────────────────────────────────────────────┘
                              ↓ ↑ (REST API + WebSocket)
┌─────────────────────────────────────────────────────────────────┐
│                        BACKEND LAYER                             │
│                      (FastAPI + Uvicorn)                         │
├─────────────────────────────────────────────────────────────────┤
│  Authentication  │  Verification  │  Trust Score  │  GPS         │
│  Incident Mgmt   │  AI Analysis   │  QR/OTP      │  Tracking    │
└─────────────────────────────────────────────────────────────────┘
                              ↓ ↑
┌──────────────────┬──────────────────┬─────────────────────────┐
│   PostgreSQL     │      Redis       │    External Services    │
│  (Primary DB)    │   (Cache/OTP)    │  ─ AWS Rekognition      │
│  ─ Users         │   ─ Sessions     │  ─ AWS S3               │
│  ─ Workers       │   ─ OTPs         │  ─ Anthropic Claude AI  │
│  ─ Assignments   │   ─ Rate Limits  │  ─ Google Maps API      │
│  ─ Verifications │   ─ Live Data    │  ─ DigiLocker/Aadhaar   │
│  ─ Incidents     │                  │  ─ MSG91/Twilio (SMS)   │
└──────────────────┴──────────────────┴─────────────────────────┘

Data Flow: Verification Process

┌─────────────┐
│  1. Worker  │ → Registers with Aadhaar
│ Registration│ → Photo Upload + Face Embedding
└──────┬──────┘
       ↓
┌─────────────┐
│  2. Employer│ → Creates Assignment
│  Assignment │ → Generates QR + OTP
└──────┬──────┘
       ↓
┌─────────────┐
│  3. Worker  │ → Accepts Job
│   Accepts   │ → Pre-Trip Selfie (Face Match)
└──────┬──────┘ → Starts GPS Tracking
       ↓
┌─────────────┐
│ 4. Citizen/ │ → Scans QR / Enters OTP
│   Police    │ → Backend Validates Token
│ Verification│ → Fetches Worker Profile
└──────┬──────┘ → Calculates Trust Score
       ↓        → Runs AI Risk Analysis
┌─────────────┐
│ 5. Response │ → GREEN/YELLOW/RED Status
│   Display   │ → Worker Info + Warnings
└──────┬──────┘ → AI Recommendations
       ↓
┌─────────────┐
│ 6. Logging  │ → Records Verification Event
│  & Analytics│ → Updates Trust Score
└─────────────┘ → Sends Notifications

🛠️ Technology Stack

Frontend

Technology Version Purpose
Next.js 14.1.0 React framework with SSR/SSG
React 18.x UI component library
TypeScript 5.x Type-safe JavaScript
Tailwind CSS 3.3.0 Utility-first CSS framework
Radix UI Latest Accessible component primitives
Lucide React Latest Icon library
html5-qrcode 2.3.8 QR code scanning
react-qr-code 2.0.12 QR code generation
Google Maps API Latest Maps integration

Backend

Technology Version Purpose
FastAPI 0.109.0 Modern Python web framework
Uvicorn 0.27.0 ASGI server
SQLAlchemy 2.0.25 Async ORM
PostgreSQL 15+ Primary database
asyncpg 0.29.0 Async PostgreSQL driver
Redis 5.0.1 Caching & session management
Pydantic 2.5.3 Data validation
python-jose 3.3.0 JWT token handling
bcrypt 4.0.1 Password hashing
Pillow 10.2.0 Image processing
qrcode 7.4.2 QR generation

AI & Cloud Services

Service Purpose
Anthropic Claude AI Risk analysis, NLP, pattern detection
AWS Rekognition Face recognition & verification
AWS S3 Image and file storage
Google Maps API Geocoding, directions, distance matrix, ETA
DigiLocker Aadhaar verification (government API)
MSG91/Twilio SMS and WhatsApp notifications

DevOps & Infrastructure

Technology Purpose
Docker Containerization
Docker Compose Local development orchestration
Railway Deployment platform
AWS Cloud infrastructure (RDS, ElastiCache, Lightsail)
GitHub Version control

🚀 Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

  • Python 3.11 or higher (Download)
  • Node.js 18.x or higher (Download)
  • PostgreSQL 15+ (Download)
  • Redis 7+ (Download) (Optional - in-memory fallback available)
  • Git (Download)
  • Docker & Docker Compose (Optional, for containerized setup) (Download)

Installation

Option 1: Docker Compose (Recommended for Quick Start)

  1. Clone the repository

    git clone https://github.com/yourusername/verifychain.git
cd verifychain

  2. Set up environment variables

    # Copy example env files
cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env

  3. Start all services

    docker-compose up --build

    This will start:

    • PostgreSQL database on port 5432
    • Redis on port 6379
    • Backend API on port 8000
    • Frontend on port 3000

  4. Access the application

Option 2: Manual Installation

Backend Setup

  1. Navigate to backend directory

    cd backend

  2. Create virtual environment

    python -m venv venv

# On Windows
venv\Scripts\activate

# On macOS/Linux
source venv/bin/activate

  3. Install dependencies

    pip install -r requirements.txt

  4. Set up PostgreSQL database

    # Create database
createdb verifychain

# Or using psql
psql -U postgres
CREATE DATABASE verifychain;
\q

  5. Configure environment variables

    Create backend/.env file:

    # Database
DATABASE_URL=postgresql+asyncpg://postgres:password@localhost:5432/verifychain
REDIS_URL=redis://localhost:6379

# Security (generate with: python -c "import secrets; print(secrets.token_hex(32))")
SECRET_KEY=your-super-secret-key-min-32-characters
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=1440
REFRESH_TOKEN_EXPIRE_DAYS=30

# Application
ENVIRONMENT=development
DEBUG=true
APP_NAME=VERIFYCHAIN
FRONTEND_URL=http://localhost:3000
ALLOWED_ORIGINS=http://localhost:3000,http://127.0.0.1:3000

# Mock Modes (set to true for development without API keys)
AADHAAR_MOCK=true
POLICE_RECORDS_MOCK=true
SMS_MOCK=true
FACE_RECOGNITION_MOCK=true
GPS_TRACKING_MOCK=true
CLAUDE_AI_MOCK=true

# Optional: External Services (add when available)
# ANTHROPIC_API_KEY=sk-ant-api03-...
# AWS_ACCESS_KEY_ID=...
# AWS_SECRET_ACCESS_KEY=...
# GOOGLE_MAPS_API_KEY=AIza...
# DIGILOCKER_CLIENT_ID=...

  6. Initialize database

    # Run migrations (creates tables)
python -m app.database

# Seed demo data (optional)
python scripts/seed_demo_data.py

  7. Start backend server

    uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
Frontend Setup

  1. Open new terminal and navigate to frontend

    cd frontend

  2. Install dependencies

    npm install

  3. Configure environment variables

    Create frontend/.env.local file:

    NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_GOOGLE_MAPS_API_KEY=your-google-maps-key (optional)

  4. Start development server

    npm run dev

  5. Access the application

⚙️ Configuration

Environment Variables

Backend Configuration (backend/.env)

Essential Variables
# Database Configuration
DATABASE_URL=postgresql+asyncpg://user:password@host:5432/database
# For development with SQLite:
# DATABASE_URL=sqlite+aiosqlite:///./verifychain.db

# Redis (Optional - in-memory fallback if not provided)
REDIS_URL=redis://localhost:6379

# Security (CRITICAL - Generate strong secret)
SECRET_KEY=<generate-with-python-secrets-token-hex-32>
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=1440  # 24 hours
REFRESH_TOKEN_EXPIRE_DAYS=30

# Application
ENVIRONMENT=development  # or production
DEBUG=true  # false in production
APP_NAME=VERIFYCHAIN
FRONTEND_URL=http://localhost:3000
ALLOWED_ORIGINS=http://localhost:3000,http://127.0.0.1:3000
External Services (Production)
# Anthropic Claude AI
ANTHROPIC_API_KEY=sk-ant-api03-...
CLAUDE_MODEL=claude-sonnet-4-20250514
CLAUDE_AI_MOCK=false

# AWS Services
AWS_REGION=ap-south-1
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...
S3_BUCKET=verifychain-assets

# Face Recognition
FACE_RECOGNITION_MOCK=false

# Google Maps
GOOGLE_MAPS_API_KEY=AIza...
GPS_TRACKING_MOCK=false

# Aadhaar/DigiLocker
DIGILOCKER_CLIENT_ID=...
DIGILOCKER_CLIENT_SECRET=...
DIGILOCKER_REDIRECT_URI=http://localhost:8000/api/v1/aadhaar/callback
AADHAAR_API_URL=https://stage1.uidai.gov.in
AADHAAR_MOCK=false

# SMS Provider
SMS_PROVIDER=msg91  # or twilio
SMS_MOCK=false
MSG91_AUTH_KEY=...
MSG91_SENDER_ID=VCHAIN
# Or for Twilio:
# TWILIO_ACCOUNT_SID=...
# TWILIO_AUTH_TOKEN=...
# TWILIO_WHATSAPP_NUMBER=...

# Police Records
POLICE_RECORDS_MOCK=false
Feature Flags (Development)
# Enable mock modes for development without API keys
AADHAAR_MOCK=true
POLICE_RECORDS_MOCK=true
SMS_MOCK=true
FACE_RECOGNITION_MOCK=true
GPS_TRACKING_MOCK=true
CLAUDE_AI_MOCK=true

Frontend Configuration (frontend/.env.local)

NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_GOOGLE_MAPS_API_KEY=your-google-maps-key

Generating Secret Key

python -c "import secrets; print(secrets.token_hex(32))"

🎮 Running the Application

Development Mode

With Docker Compose:

docker-compose up

Manual (Two Terminals):

Terminal 1 - Backend:

cd backend
source venv/bin/activate  # or venv\Scripts\activate on Windows
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Terminal 2 - Frontend:

cd frontend
npm run dev

Production Mode

Backend:

cd backend
uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4

Frontend:

cd frontend
npm run build
npm start

Database Migrations

cd backend
python -m app.database  # Creates all tables
python scripts/seed_demo_data.py  # Seeds demo data

👥 User Portals

1. Worker Portal (/worker/*)

For gig workers and delivery personnel

Features:

  • 📝 Registration: Aadhaar verification, photo upload, profile setup
  • 🎫 QR Code Display: Show dynamic verification code to customers/police
  • 📊 Dashboard: View trust score, active assignments, earnings
  • 📍 GPS Tracking: Automatic location logging during deliveries
  • ⭐ Performance: Track ratings, completed deliveries, reviews
  • 📱 Notifications: Assignment updates, verification alerts

Access: http://localhost:3000/worker

2. Police Portal (/police/*)

For law enforcement officers

Features:

  • 🚔 Checkpoint Verification: Scan QR, enter phone number, or worker ID
  • 🔍 Investigation Tools: Complete worker history, employment records
  • 🚨 Incident Management: View reports, update investigation status
  • 🤖 AI Risk Analysis: Claude-powered threat assessment with recommendations
  • 📊 Analytics Dashboard: Verification statistics, pattern detection
  • 🚩 Flagging System: Mark high-risk individuals, add notes

Access: http://localhost:3000/police

3. Employer Portal (/employer/*)

For delivery companies (Swiggy, Zomato, etc.)

Features:

  • 👥 Workforce Management: Onboard/offboard workers, view roster
  • 📦 Assignment Creation: Create delivery tasks with auto-generated QR/OTP
  • 📍 Fleet Tracking: Real-time GPS monitoring of all active workers
  • 📊 Analytics Dashboard: Performance metrics, completion rates, incidents
  • ⭐ Rating System: Rate workers after delivery completion
  • 🚨 Incident Reports: Report and track worker-related incidents

Access: http://localhost:3000/employer

4. Bank Admin Portal (/bank/*)

For banking institutions managing AePS agents

Features:

  • 🏦 Agent Verification: Verify Banking Correspondents before transactions
  • 🔐 Authorization Management: Grant/revoke AePS access
  • 📊 Compliance Dashboard: Monitor agent performance, incident history
  • 🚨 Risk Alerts: AI-powered fraud detection for banking agents
  • 📝 Audit Logs: Complete verification history for regulatory compliance

Access: http://localhost:3000/bank

5. Admin Portal (/admin/*)

For super administrators

Features:

  • ⚙️ System Configuration: Manage platform settings, feature flags
  • 👥 User Management: Create/edit users across all portals
  • 🏢 Employer Management: Onboard new companies, manage subscriptions
  • 📊 Platform Analytics: System-wide statistics, usage metrics
  • 🔧 Maintenance Tools: Database backups, system health monitoring

Access: http://localhost:3000/admin

6. Public Access (/verify, /tracking)

For citizens and general public

Features:

  • 🔍 Verify Worker: Scan QR code or enter OTP to verify delivery person
  • 📍 Track Delivery: Real-time GPS tracking with ETA
  • 📝 Worker Registration: Public registration form for new workers
  • 🚨 Report Incident: Anonymous incident reporting
  • 🧪 Demos: Face recognition and GPS tracking demonstrations

Access:

🔄 How It Works

Complete Verification Workflow

Step 1: Worker Registration

Worker → Fills registration form → Aadhaar verification (DigiLocker)
→ Photo upload → Face embedding generation → Profile created
→ Initial trust score: 50 (YELLOW status)

Step 2: Employer Onboarding

Employer → Creates assignment for worker → System generates:
  ├─ QR Code (HMAC-signed, 60-min expiry, nonce-based)
  ├─ 6-digit OTP (Redis-stored, 10-min TTL)
  └─ Assignment record (origin, destination, GPS coordinates)
→ Worker notified via SMS/WhatsApp

Step 3: Worker Accepts Job

Worker → Accepts assignment → Captures pre-trip selfie
→ Face recognition match (90% confidence required)
→ GPS tracking starts → Status: EN_ROUTE

Step 4: Verification at Delivery Location

Citizen/Police → Scans QR code OR enters OTP
→ Backend validates:
  ├─ Token signature (HMAC-SHA256)
  ├─ Expiry timestamp
  ├─ Nonce uniqueness (prevents replay attacks)
  └─ Worker status (active/suspended)
→ Fetches worker profile from database
→ Calculates real-time trust score (6 components)
→ Runs Claude AI risk analysis (if enabled)
→ Returns response:
  ├─ 🟢 GREEN (Safe): Score ≥70, clean record
  ├─ 🟡 YELLOW (Caution): Score 40-69 or minor issues
  └─ 🔴 RED (High Risk): Score <40 or flagged

Step 5: Incident Detection & Response

If incident reported:
  → System assigns severity (LOW/MEDIUM/HIGH/CRITICAL)
  → Claude AI analyzes description (NLP)
  → Pattern clustering identifies related incidents
  → Trust score recalculated (deductions applied)
  → Notifications sent to employer, worker, police
  → Auto-flag if threshold exceeded (e.g., 5+ incidents)

Step 6: Continuous Monitoring

During delivery:
  → GPS location logged every minute
  → Route validation (compares actual vs expected path)
  → Geofence alerts if leaving authorized zone
  → ETA updated based on real-time traffic
  → Employer sees live tracking dashboard

Step 7: Delivery Completion

Worker → Marks delivery complete → Final selfie (optional)
→ Customer rates worker (1-5 stars)
→ Trust score updated (performance component)
→ Verification log stored immutably for audit
→ Payment processed to worker

📚 API Documentation

Base URL

  • Development: http://localhost:8000
  • Production: https://your-domain.com

Interactive API Docs

Authentication

All authenticated endpoints require JWT token in header:

Authorization: Bearer <your_jwt_token>

Key Endpoints

Authentication

POST   /api/v1/auth/register          # User registration
POST   /api/v1/auth/login             # Login (returns JWT + refresh token)
POST   /api/v1/auth/refresh           # Refresh access token
GET    /api/v1/auth/me                # Get current user profile
POST   /api/v1/auth/change-password   # Change password

Verification (Public)

POST   /api/v1/verify/qr              # Verify by QR code
POST   /api/v1/verify/otp             # Verify by OTP
GET    /api/v1/verify/assignment/{id} # Check assignment status

Workers

POST   /api/v1/workers/register       # Register new worker (with Aadhaar)
GET    /api/v1/workers/me             # Get worker profile
POST   /api/v1/workers/{id}/upload-photo  # Upload profile photo
GET    /api/v1/workers/{id}           # Get public worker info
PUT    /api/v1/workers/{id}           # Update worker profile

Assignments

POST   /api/v1/assignments                    # Create assignment
GET    /api/v1/assignments                    # List assignments
GET    /api/v1/assignments/{id}               # Get assignment details
PUT    /api/v1/assignments/{id}/status        # Update status
POST   /api/v1/assignments/{id}/pre-trip-selfie  # Upload selfie

Police Operations

POST   /api/v1/police/checkpoint/verify      # Checkpoint verification
GET    /api/v1/police/workers/{id}           # Investigate worker
GET    /api/v1/police/incidents              # List incidents
POST   /api/v1/police/incidents/{id}/investigate  # Update investigation

Employers

GET    /api/v1/employers/me                  # Get employer profile
GET    /api/v1/employers/me/stats            # Get analytics
GET    /api/v1/employers/workers             # List workers
POST   /api/v1/employers/workers/{id}/employment  # Onboard worker
DELETE /api/v1/employers/workers/{id}/employment  # Offboard worker

GPS Tracking

POST   /api/v1/tracking/location             # Log location
GET    /api/v1/tracking/assignment/{id}      # Get live location
WS     /api/v1/tracking/live/{id}            # WebSocket live stream

Banking

POST   /api/v1/banking/agents/verify         # Verify banking agent
GET    /api/v1/banking/agents/{id}           # Get agent details
POST   /api/v1/banking/agents                # Register agent

Incident Reports

POST   /api/v1/reports/incident              # Report incident
GET    /api/v1/reports/incidents             # List reports
GET    /api/v1/reports/summary               # Analytics summary
PUT    /api/v1/reports/incidents/{id}        # Update incident

Health & Status

GET    /health                               # Basic health check
GET    /api/v1/health                        # Detailed status (mock modes)

Example Requests

1. Register Worker

curl -X POST "http://localhost:8000/api/v1/workers/register" \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Rajesh Kumar",
    "phone_number": "+919876543210",
    "email": "rajesh@example.com",
    "aadhaar_number": "123456789012",
    "address": "123 Main St, Jaipur"
  }'

2. Login

curl -X POST "http://localhost:8000/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "worker1@demo.com",
    "password": "password123"
  }'

3. Verify Worker by QR Code

curl -X POST "http://localhost:8000/api/v1/verify/qr" \
  -H "Content-Type: application/json" \
  -d '{
    "qr_token": "eyJhIjoxLCJ3IjoyLCJlIjozLCJuIjoiYWJjZCIsIngiOjE3MDAwMDAwMDAsInMiOiJzaWduYXR1cmUifQ=="
  }'

Response:

{
  "verification_id": 123,
  "status": "GREEN",
  "trust_score": 85,
  "worker": {
    "id": 2,
    "full_name": "Rajesh Kumar",
    "phone_number": "+919876543210",
    "photo_url": "https://...",
    "employer_name": "Swiggy"
  },
  "assignment": {
    "order_id": "ORD-12345",
    "destination": "45 Park Street, Jaipur"
  },
  "warnings": [],
  "ai_analysis": {
    "risk_level": "LOW",
    "confidence": 0.95,
    "recommendations": ["Verified safe for delivery"]
  }
}

🌐 Deployment

Railway (Recommended - Easiest)

Railway configuration is already included in railway.toml.

  1. Install Railway CLI

    npm install -g @railway/cli

  2. Login to Railway

    railway login

  3. Create new project

    railway init

  4. Add environment variables

    railway variables set DATABASE_URL="postgresql://..."
railway variables set SECRET_KEY="your-secret-key"
# Add all required environment variables

  5. Deploy

    railway up

Railway will automatically:

  • Provision PostgreSQL and Redis
  • Build Docker containers
  • Deploy frontend and backend
  • Provide HTTPS URLs

AWS Deployment Options

Option 1: AWS Lightsail (Simple, $7/month)

See detailed guide in DEPLOY_AWS.md

# Create instance
aws lightsail create-container-service \
  --service-name verifychain \
  --power small \
  --scale 1

# Deploy containers
aws lightsail push-container-image --service-name verifychain --label backend --image verifychain-backend
aws lightsail push-container-image --service-name verifychain --label frontend --image verifychain-frontend

Option 2: AWS App Runner (Serverless)

# Deploy backend
aws apprunner create-service \
  --service-name verifychain-backend \
  --source-configuration '{
    "ImageRepository": {
      "ImageIdentifier": "your-ecr-repo/backend:latest",
      "ImageRepositoryType": "ECR"
    }
  }'

Option 3: AWS EC2 (Full Control)

  1. Launch EC2 instance (Ubuntu 22.04)
  2. Install Docker and Docker Compose
  3. Clone repository
  4. Set environment variables
  5. Run docker-compose -f docker-compose.prod.yml up -d

Production Checklist

  • Set ENVIRONMENT=production
  • Set DEBUG=false
  • Generate strong SECRET_KEY (32+ characters)
  • Use production database (PostgreSQL on AWS RDS)
  • Set up Redis cluster (AWS ElastiCache)
  • Configure AWS S3 for file storage
  • Add AWS Rekognition credentials
  • Set up Anthropic Claude API key
  • Configure Google Maps API key
  • Set up SMS provider (MSG91/Twilio)
  • Enable HTTPS (SSL/TLS certificates)
  • Configure CORS allowed origins
  • Set up database backups
  • Enable monitoring and logging
  • Configure rate limiting
  • Set up CDN for static files
  • Disable all mock modes
  • Test all verification flows end-to-end

🔐 Demo Credentials

Pre-seeded accounts for testing (after running seed_demo_data.py):

Role Email Password Access
Worker worker1@demo.com password123 Worker Portal
Police Officer officer@jaipur.police password123 Police Portal
Employer (Swiggy) employer@swiggy.demo password123 Employer Portal
Bank Admin (SBI) employer@sbi.demo password123 Bank Portal
Super Admin superadmin@verifychain.in password123 Admin Portal

Demo Worker Profile:

  • Name: Ramesh Kumar
  • Phone: +919876543210
  • Trust Score: 75 (GREEN)
  • Total Deliveries: 150
  • Rating: 4.5/5

Test QR Code Generation: After logging in as employer, create an assignment to generate a test QR code and OTP.

📁 Project Structure

verifychain-main/
│
├── backend/                      # Python FastAPI Backend
│   ├── app/
│   │   ├── __init__.py
│   │   ├── main.py               # FastAPI app initialization
│   │   ├── config.py             # Settings & environment variables
│   │   ├── database.py           # SQLAlchemy async database setup
│   │   │
│   │   ├── models/               # SQLAlchemy ORM Models
│   │   │   ├── __init__.py
│   │   │   ├── user.py           # User authentication model
│   │   │   ├── worker.py         # Worker profile model
│   │   │   ├── employer.py       # Employer/company model
│   │   │   ├── assignment.py     # Delivery assignment model
│   │   │   ├── verification.py   # Verification event log
│   │   │   ├── incident.py       # Incident report model
│   │   │   ├── employment.py     # Worker-employer relationship
│   │   │   ├── location_log.py   # GPS tracking history
│   │   │   └── banking_auth.py   # Banking agent credentials
│   │   │
│   │   ├── schemas/              # Pydantic Request/Response Schemas
│   │   │   ├── __init__.py
│   │   │   ├── user.py
│   │   │   ├── worker.py
│   │   │   ├── assignment.py
│   │   │   ├── verification.py
│   │   │   └── ...
│   │   │
│   │   ├── routers/              # API Route Handlers
│   │   │   ├── __init__.py
│   │   │   ├── auth.py           # Authentication endpoints
│   │   │   ├── verification.py   # Public verification API
│   │   │   ├── workers.py        # Worker management
│   │   │   ├── assignments.py    # Assignment CRUD
│   │   │   ├── police.py         # Police checkpoint & investigation
│   │   │   ├── employers.py      # Employer management
│   │   │   ├── tracking.py       # GPS tracking (+ WebSocket)
│   │   │   ├── banking.py        # Banking agent verification
│   │   │   └── reports.py        # Incident reporting
│   │   │
│   │   ├── services/             # Business Logic Services
│   │   │   ├── __init__.py
│   │   │   ├── trust_score_service.py    # Trust score calculation
│   │   │   ├── claude_ai_service.py      # AI risk analysis
│   │   │   ├── face_service.py           # AWS Rekognition integration
│   │   │   ├── gps_service.py            # Google Maps integration
│   │   │   ├── qr_service.py             # QR token generation/validation
│   │   │   ├── otp_service.py            # OTP generation/validation
│   │   │   ├── aadhaar_service.py        # DigiLocker integration
│   │   │   ├── sms_service.py            # MSG91/Twilio integration
│   │   │   └── police_records_service.py # Police verification API
│   │   │
│   │   ├── security/             # Authentication & Authorization
│   │   │   ├── __init__.py
│   │   │   ├── jwt.py            # JWT token handling
│   │   │   ├── password.py       # Password hashing (bcrypt)
│   │   │   └── permissions.py    # Role-based access control
│   │   │
│   │   └── utils/                # Utility Functions
│   │       ├── __init__.py
│   │       ├── redis_client.py   # Redis connection manager
│   │       └── validators.py     # Custom validators
│   │
│   ├── scripts/
│   │   └── seed_demo_data.py     # Database seeding script
│   │
│   ├── requirements.txt          # Python dependencies
│   ├── Dockerfile                # Backend Docker image
│   └── .env.example              # Example environment variables
│
├── frontend/                     # Next.js Frontend
│   ├── src/
│   │   ├── app/                  # Next.js 14 App Router
│   │   │   ├── layout.tsx        # Root layout
│   │   │   ├── page.tsx          # Homepage (portal selection)
│   │   │   │
│   │   │   ├── verify/           # Public verification
│   │   │   │   └── page.tsx
│   │   │   ├── tracking/         # Live delivery tracking
│   │   │   │   └── page.tsx
│   │   │   │
│   │   │   ├── worker/           # Worker Portal
│   │   │   │   ├── login/
│   │   │   │   ├── dashboard/
│   │   │   │   ├── profile/
│   │   │   │   └── assignments/
│   │   │   │
│   │   │   ├── police/           # Police Portal
│   │   │   │   ├── login/
│   │   │   │   ├── checkpoint/
│   │   │   │   ├── investigation/
│   │   │   │   └── incidents/
│   │   │   │
│   │   │   ├── employer/         # Employer Portal
│   │   │   │   ├── login/
│   │   │   │   ├── dashboard/
│   │   │   │   ├── workers/
│   │   │   │   ├── assignments/
│   │   │   │   └── analytics/
│   │   │   │
│   │   │   ├── bank/             # Bank Admin Portal
│   │   │   │   ├── login/
│   │   │   │   ├── dashboard/
│   │   │   │   └── agents/
│   │   │   │
│   │   │   └── admin/            # Super Admin Portal
│   │   │       ├── login/
│   │   │       ├── dashboard/
│   │   │       └── users/
│   │   │
│   │   ├── components/           # Reusable React Components
│   │   │   ├── ui/               # UI primitives (Radix-based)
│   │   │   ├── QRScanner.tsx
│   │   │   ├── QRCodeDisplay.tsx
│   │   │   ├── TrustScoreCard.tsx
│   │   │   ├── MapView.tsx
│   │   │   └── ...
│   │   │
│   │   └── lib/                  # Utilities & API Client
│   │       ├── api.ts            # Axios/fetch wrapper
│   │       ├── auth.ts           # Authentication helpers
│   │       └── utils.ts          # Helper functions
│   │
│   ├── public/                   # Static assets
│   ├── package.json              # Node dependencies
│   ├── Dockerfile                # Frontend Docker image
│   ├── tailwind.config.ts        # Tailwind CSS config
│   ├── tsconfig.json             # TypeScript config
│   └── .env.example              # Example environment variables
│
├── docker-compose.yml            # Development orchestration
├── docker-compose.prod.yml       # Production orchestration
├── railway.toml                  # Railway deployment config
├── DEPLOY_AWS.md                 # AWS deployment guide
├── README.md                     # This file
└── LICENSE                       # MIT License

🔒 Security Features

Authentication & Authorization

  • JWT-based authentication with access + refresh tokens
  • bcrypt password hashing (12 rounds)
  • Role-based access control (RBAC) with 6 distinct roles
  • Token expiry: Access (24h), Refresh (30 days)
  • Password strength validation
  • Rate limiting on auth endpoints

Data Security

  • Aadhaar number hashing - never stores plain text
  • Face embeddings stored - not raw images
  • SQL injection protection via SQLAlchemy ORM
  • XSS prevention with input sanitization (bleach library)
  • CORS configuration with allowed origins
  • HTTPS enforcement in production
  • Environment variable security - secrets not in code

Verification Security

  • HMAC-SHA256 QR signatures - prevents token forgery
  • Nonce-based replay prevention - tokens can't be reused
  • Time-limited tokens - 60-minute QR expiry, 10-minute OTP
  • Redis-backed OTP storage with TTL
  • Face recognition confidence minimum 90%
  • Device fingerprinting for suspicious activity detection

API Security

  • Rate limiting via Redis (configurable per endpoint)
  • Request validation with Pydantic schemas
  • SQL injection protection via parameterized queries
  • Content Security Policy (CSP) headers
  • HSTS headers for HTTPS enforcement
  • Audit logging of all verification events

Privacy Compliance

  • GDPR-inspired data minimization - only essential data stored
  • Right to deletion - users can request data removal
  • Data encryption at rest (database level)
  • Data encryption in transit (HTTPS/TLS)
  • Anonymized incident reporting option
  • Consent management for data processing

🤝 Contributing

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

How to Contribute

  1. Fork the repository

    git clone https://github.com/yourusername/verifychain.git
cd verifychain
git checkout -b feature/your-feature-name

  2. Set up development environment

    • Follow installation instructions above
    • Enable mock modes for easier development

  3. Make your changes

    • Write clean, documented code
    • Follow existing code style (PEP 8 for Python, ESLint for TypeScript)
    • Add unit tests for new features

  4. Test thoroughly

    # Backend tests
cd backend
pytest tests/

# Frontend tests
cd frontend
npm run test

  5. Commit with clear messages

    git add .
git commit -m "Add: Feature description"

  6. Push and create Pull Request

    git push origin feature/your-feature-name

Development Guidelines

  • Code Style:
    • Python: PEP 8, type hints preferred
    • TypeScript: ESLint + Prettier
  • Commits: Use conventional commits (feat:, fix:, docs:, etc.)
  • Documentation: Update README for new features
  • Tests: Maintain >80% code coverage
  • Security: Never commit secrets or API keys

Areas for Contribution

  • 🐛 Bug fixes and issue resolution
  • ✨ New verification methods (biometric, document scan)
  • 🌍 Internationalization (Hindi, regional languages)
  • 📱 Mobile app (React Native)
  • 🧪 Test coverage improvements
  • 📚 Documentation enhancements
  • 🎨 UI/UX improvements
  • ⚡ Performance optimizations

Reporting Issues

Use GitHub Issues with:

  • Bug Report: Describe expected vs actual behavior
  • Feature Request: Explain use case and benefits
  • Security Vulnerability: Email team directly (do not post publicly)

📄 License

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

MIT License

Copyright (c) 2024 VerifyChain Team

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

[Full MIT License text...]

🙏 Acknowledgments

Hackathon Recognition

  • Event: SHIELD 1.0 Hackathon
  • Organizers: Bureau of Police Research & Development (BPR&D) × MNIT Jaipur
  • Venue: Centre for Development of Technical Institutions (CDTI), Jaipur
  • Achievement: 🥉 2nd Runner-Up | Best Solution for Track #3
  • Problem Statement: Real-Time Database for Delivery Personnel Verification (Gig Workers) & Banking Agents

Team Contributions

Special thanks to all team members who contributed to this project during the 48-hour hackathon and subsequent development.

Technology Partners

  • Anthropic - Claude AI for risk analysis
  • Amazon Web Services (AWS) - Rekognition, S3, RDS, ElastiCache
  • Google - Maps API for geocoding and tracking
  • UIDAI - Aadhaar verification infrastructure
  • Open Source Community - FastAPI, Next.js, PostgreSQL, Redis

Mentors & Advisors

  • BPR&D officials for problem statement guidance
  • MNIT faculty for technical mentorship
  • Law enforcement professionals for domain expertise

📞 Support & Contact

Documentation

Get Help

  • GitHub Issues: Report bugs or request features
  • Discussions: Ask questions and share ideas
  • Email: support@verifychain.in (if applicable)

Community

  • Star ⭐ the repository if you find it useful
  • Follow for updates on new features
  • Share your implementations and use cases

🚀 Roadmap

Phase 1: MVP (Completed ✅)

  • Multi-portal system (Worker, Police, Employer, Bank, Admin)
  • QR code and OTP verification
  • Trust score calculation system
  • Basic GPS tracking
  • Incident management
  • Claude AI integration

Phase 2: Enhanced Features (In Progress 🔄)

  • Mobile applications (iOS & Android)
  • Advanced face recognition (liveness detection)
  • Offline verification mode
  • Multi-language support (Hindi, regional languages)
  • Voice-based verification
  • Enhanced analytics dashboard

Phase 3: Enterprise Scale (Planned 📅)

  • Multi-tenant architecture for different states
  • Blockchain integration for immutable audit logs
  • Advanced ML fraud detection models
  • Integration with national crime databases
  • WhatsApp Business API integration
  • Predictive risk scoring

Phase 4: Ecosystem Expansion (Future 🔮)

  • Open API for third-party integrations
  • Marketplace for gig platforms
  • Insurance integration based on trust scores
  • Credit scoring for gig workers
  • Training and certification modules
  • Community safety network

📊 Statistics & Impact

Hackathon Achievements

  • ⏱️ Built in 48 hours
  • 👥 Solves problems for 10+ million gig workers in India
  • 🎯 Addresses critical safety concerns for households and law enforcement
  • 🏆 Recognized as best solution in Track #3

Potential Impact

  • Citizens: Safer home deliveries and service visits
  • Police: 90% faster checkpoint verifications
  • Employers: Reduced onboarding time from days to minutes
  • Banks: Enhanced AePS security and compliance
  • Workers: Better employment opportunities through verified profiles

🎓 Learn More

Technologies Used

Related Resources

⭐ Star This Repository

If you find VerifyChain useful, please consider giving it a star! It helps others discover the project and motivates continued development.

Built with ❤️ for a Safer India

VerifyChain | Securing the Gig Economy, One Verification at a Time

GitHub Stars GitHub Forks GitHub Issues

About

Realtime Database for gig worker verification and tracking using natural language prompt to gather details of the gig workers for instant tracking.

verifychain.up.railway.app/

Topics

google-maps nextjs claude fastapi digilocker anthropic

Resources

Readme
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages