WeInsure - Parametric Insurance Platform

A blockchain-based parametric insurance platform for event cancellations using weather data oracles and smart contracts.

🎯 Overview

WeInsure provides automated insurance coverage for events based on weather conditions. The platform uses Chainlink oracles to fetch real-time weather data and automatically triggers payouts when predefined weather thresholds are met.

Key Features

• Parametric Insurance: Automated payouts based on objective weather data
• Blockchain-Based: Transparent, immutable smart contracts on Ethereum
• Oracle Integration: Real-time weather data from multiple sources
• NFT Policies: Each policy is represented as an NFT for easy ownership tracking
• Award-Winning UI/UX: Professional, accessible design with 3-color palette
• Wallet Isolation: Each wallet gets its own separate policy dashboard
• Modern Frontend: Clean Next.js application with seamless Web3 integration
• Automated Triggers: No claims process - payouts are automatic when conditions are met
• Real-time Notifications: Professional notification system with visual indicators
• Mobile Optimized: Responsive design that works perfectly on all devices

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Frontend      │    │   Backend       │    │   Blockchain    │
│   (Next.js)     │◄──►│   (Node.js)     │◄──►│   (Sepolia)     │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Web3 Wallet   │    │   MongoDB       │    │   Smart         │
│   (MetaMask)    │    │   Weather APIs  │    │   Contracts     │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Smart Contracts

• PolicyFactory: Creates and manages insurance policies
• PolicyNFT: ERC721 tokens representing insurance policies
• Escrow: Manages premium payments and payouts
• TriggerContract: Handles weather data and trigger logic

Frontend (Next.js)

• Award-Winning UI/UX: Professional 3-color design system with optimal accessibility
• Clean Architecture: Component-based design with consistent styling
• Web3 Integration: Seamless wallet connection with RainbowKit
• Wallet-Specific Data: Isolated policy data for each connected wallet
• Real-time Monitoring: Live weather data and risk visualization
• Responsive Design: Mobile-first approach with smooth animations
• Professional Components: Clean cards, tables, forms, and navigation

Backend Services

• Premium Calculator: Actuarial calculations based on historical weather data
• Weather API Integration: Fetches data from multiple weather services
• MongoDB Database: Stores policy metadata and weather history

Oracle Adapter

• Multi-Source Weather Data: OpenWeatherMap, NOAA, backup APIs
• Consensus Mechanism: Validates data across multiple sources
• Chainlink Integration: Submits verified data to blockchain

🚀 Quick Start

Prerequisites

• Node.js >= 18.0.0
• MongoDB
• Ethereum wallet with Sepolia testnet ETH
• API keys for weather services (optional for testing)

Installation

1. Clone the repository

git clone https://github.com/YOUR_USERNAME/WeInsure.git
cd WeInsure

2. Install all dependencies

npm run install:all

3. Configure environment variables

# Copy example files and configure with your API keys
cp .env.example .env
cp backend/.env.example backend/.env
cp oracle-adapter/.env.example oracle-adapter/.env
cp frontend/.env.example frontend/.env.local

# Edit each .env file with your actual API keys and configuration
# See the .env.example files for detailed comments on each variable

Deployment & Setup

1. Compile and deploy smart contracts

npm run compile
npm run deploy:sepolia

2. Setup frontend with contract addresses

npm run setup:frontend

3. Start all services

npm run dev

This will start:

• Frontend: http://localhost:3000
• Backend API: http://localhost:3001
• Oracle Adapter: Weather monitoring service

🎨 Frontend Features

✨ Award-Winning UI/UX Design

WeInsure features a professional, clean design system built with modern web standards:

🎯 Design System

• Professional 3-Color Palette:
  • Primary Blue (#2563eb) - Trust and reliability
  • Neutral Gray (#64748b) - Clean readability
  • Success Green (#10b981) - Positive actions
• Typography: Inter font family for optimal readability
• Accessibility: WCAG compliant color contrasts and interactions
• Responsive: Mobile-first design approach

🏠 Landing & Navigation

• Clean Navbar: Professional navigation with wallet integration
• USDC Balance Display: Real-time balance tracking with visual indicators
• Responsive Menu: Smooth mobile navigation experience
• Active States: Clear indication of current page location

📝 Create Policy Page

• Multi-Step Form: Intuitive policy creation workflow
• Real-time Validation: Instant feedback on form inputs
• Premium Calculator: Live premium calculation with breakdown
• Weather Threshold Setup: Visual threshold configuration
• Smart Contract Integration: Seamless blockchain interactions

📊 Dashboard

• Wallet-Specific Data: Each wallet has isolated policy data
• Summary Cards: Clean metric displays with hover animations
• Active Policy Monitor: Real-time weather risk visualization
• Policy History Table: Professional table design with status badges
• Live Risk Monitor: Progress bars showing current vs trigger thresholds
• Notification System: Clean notification cards with read/unread states

🔔 Notification Features

• Real-time Updates: Instant notifications for policy events
• Visual Indicators: Unread badges and status indicators
• Persistent Storage: Notifications persist across sessions
• Clean UI: Professional notification cards with proper hierarchy

📱 Mobile Experience

• Responsive Design: Optimized for all screen sizes
• Touch-Friendly: Proper touch targets and interactions
• Performance: Smooth animations and transitions
• Accessibility: Screen reader compatible and keyboard navigable

🏠 Home Page

• Hero section with clear value proposition
• Feature highlights and platform statistics
• How it works explanation
• Call-to-action sections

📝 Create Policy

• Step 1: Event details and location
• Step 2: Weather thresholds configuration
• Step 3: Review and payment
• Real-time premium calculation
• Smart contract integration

📊 Dashboard

• Policy overview and statistics
• Real-time weather monitoring
• Policy status tracking
• Quick actions and navigation

📈 Monitor

• Live weather charts (24h history)
• Policy risk assessment
• Alert system for critical conditions
• Multi-policy monitoring

📋 Available Scripts

Main Commands

npm run install:all      # Install all dependencies
npm run dev             # Start all services (frontend, backend, oracle)
npm run compile         # Compile smart contracts
npm test               # Run contract tests
npm run deploy:sepolia  # Deploy to Sepolia testnet
npm run verify:sepolia  # Verify contracts on Etherscan

Individual Services

# Frontend
npm run frontend:dev    # Start frontend development server
npm run frontend:build  # Build frontend for production

# Backend
npm run backend:dev     # Start backend development server
npm run backend:start   # Start backend production server

# Oracle Adapter
npm run oracle:dev      # Start oracle with auto-restart
npm run oracle:start    # Start oracle production mode

Utilities

npm run setup:frontend  # Setup frontend with contract addresses
npm run setup:testnet   # Setup testnet environment
npm run interact        # Test contract interactions
npm run monitor         # Monitor policies and weather

🧪 Testing

Smart Contract Tests

npm test                # Run all tests
npm run test:coverage   # Run with coverage report
npm run test:gas        # Analyze gas usage

Test Results

WeInsure Integration Tests
  ✅ Should complete full policy lifecycle - normal weather
  ✅ Should complete full policy lifecycle - cancellation trigger

PolicyFactory
  ✅ Should create a policy successfully

TriggerContract
  ✅ Should register trigger conditions
  ✅ Should process weather data and trigger cancellation
  ✅ Should calculate 24-hour rainfall correctly

6 passing (2s)

📊 Policy Workflow

1. Policy Creation

1. Connect Web3 wallet to frontend
2. Fill out event details and location
3. Set weather thresholds for triggers
4. System calculates premium using actuarial models
5. Pay premium in USDC and receive Policy NFT

2. Weather Monitoring

1. Oracle adapter polls weather APIs hourly
2. Data validated using consensus mechanism
3. Frontend displays real-time weather charts
4. Risk levels calculated and displayed

3. Trigger Evaluation

1. Postponement: Wind ≥ threshold for consecutive hours → 50% payout
2. Cancellation: Rain ≥ threshold in 24h OR wind ≥ threshold → 100% payout
3. Payouts are automatic and instant
4. Policy NFT status updated

🔧 Configuration

Weather Thresholds

• Postponement Rainfall: Typically 10-15mm in 1 hour
• Postponement Wind: Typically 50-60 km/h sustained
• Cancellation Rainfall: Typically 20-25mm in 24 hours
• Cancellation Wind: Typically 80-100 km/h

Premium Calculation

ExpectedLoss = (Postponement% × Coverage × Prob_p) + (100% × Coverage × Prob_c)
PurePremium = ExpectedLoss
LoadedPremium = PurePremium / (1 - TargetLossRatio)

🛡️ Security Features

• Multi-source Oracle Consensus: Prevents single point of failure
• OpenZeppelin Standards: Battle-tested smart contract implementations
• Access Control: Role-based permissions throughout
• Reentrancy Protection: All external calls are protected
• Input Validation: Comprehensive parameter validation

🌐 Network Support

• Sepolia Testnet ✅ (Primary development network)
• Ethereum Mainnet (Production ready)
• Polygon (Future deployment)
• Arbitrum (Future deployment)

📁 Project Structure

WeInsure/
├── contracts/              # Smart contracts
│   ├── PolicyFactory.sol
│   ├── PolicyNFT.sol
│   ├── Escrow.sol
│   ├── TriggerContract.sol
│   └── mockERC20.sol
├── frontend/               # Next.js frontend with award-winning UI/UX
│   ├── app/               # App router pages with clean layouts
│   │   ├── components/    # Professional reusable components
│   │   ├── dashboard/     # Wallet-specific dashboard
│   │   ├── create-policy/ # Multi-step policy creation
│   │   └── globals.css    # Professional 3-color design system
│   └── lib/              # Utilities and API client
├── backend/               # Node.js backend
│   ├── src/
│   │   ├── controllers/   # API controllers
│   │   ├── models/        # Database models
│   │   ├── routes/        # API routes
│   │   └── services/      # Business logic
│   └── server.js
├── oracle-adapter/        # Weather oracle service
│   ├── index.js          # Main oracle service
│   ├── weather-fetcher.js # Weather API integration
│   ├── consensus.js      # Data validation
│   └── chainlink-integration.js
├── scripts/              # Deployment and utility scripts
├── test/                # Smart contract tests
└── package.json         # Main project configuration

🎯 User Journey

Seamless User Experience

1. Connect Wallet → Clean wallet connection interface with professional styling
2. Wallet Isolation → Each wallet gets its own isolated policy dashboard
3. Create Policy → Intuitive multi-step form with real-time validation
4. Visual Feedback → Professional notifications and status updates
5. Monitor Weather → Clean dashboard with live risk visualization
6. Automatic Payouts → Instant notifications when payouts are triggered
7. Policy Management → Professional table interface for policy history

Design Highlights

• Professional Aesthetics: Clean, modern design suitable for financial applications
• Optimal Readability: High contrast colors and proper typography
• Smooth Interactions: Subtle animations and hover effects
• Mobile Optimized: Responsive design that works on all devices
• Accessibility First: WCAG compliant design for all users

🚀 Deployment

Local Development

npm run dev  # Starts all services locally

Production Deployment

1. Smart Contracts: Deploy to mainnet using deployment scripts
2. Backend: Deploy to cloud service (AWS, GCP, etc.)
3. Frontend: Deploy to Vercel or similar platform
4. Oracle: Run as a service with proper monitoring

🤝 Contributing

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

📄 License

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

🆘 Support

• Issues: GitHub Issues
• Documentation: Check the README and code comments
• Discussions: GitHub Discussions

---

WeInsure - Protecting events with blockchain-powered parametric insurance 🛡️⛈️