🛡️ SentinelChain AI - Supply Chain Risk Intelligence Platform

AI-powered supply chain risk detection and monitoring system with blockchain verification on Algorand.

🎯 Overview

SentinelChain AI is an enterprise-grade platform that combines:

• AI Risk Detection - Machine learning + rule-based risk analysis
• Agentic AI - Three specialized agents (Delay, Escalation, Recovery)
• Trust Scoring - Dynamic actor reputation system
• Blockchain Verification - Immutable audit trail on Algorand
• Role-Based Dashboards - Tailored views for each stakeholder

🏗️ Architecture

Frontend (React + Vite)
    ↓
Backend API (FastAPI)
    ↓
┌─────────────────────────────────────┐
│  Monitoring Engine                  │
│  ↓                                  │
│  Risk Engine (Rules + ML)           │
│  ↓                                  │
│  Agent Coordinator                  │
│  ├─ Delay Agent                     │
│  ├─ Escalation Agent                │
│  └─ Recovery Agent                  │
│  ↓                                  │
│  Trust Engine                       │
│  ↓                                  │
│  Blockchain (if HIGH risk)          │
└─────────────────────────────────────┘

🚀 Quick Start

Prerequisites

• Python 3.11+
• Node.js 18+
• npm or yarn

Backend Setup

cd backend
pip install -r requirements.txt
uvicorn main:app --reload --port 8000

Backend will start at: http://localhost:8000

Frontend Setup

cd frontend
npm install
npm run dev

Frontend will start at: http://localhost:5173

📊 Features

1. Role-Based Dashboards

Supplier Dashboard

• View shipments created by supplier
• Monitor carrier trust scores
• Create new shipments
• Track risk alerts

Carrier Dashboard

• View assigned shipments
• Monitor own trust score
• Track performance metrics
• View route information

Distributor Dashboard

• View incoming shipments
• Monitor supplier trust scores
• Track delivery status
• Quality issue alerts

Admin Dashboard

• System-wide overview
• All shipments and actors
• Network health metrics
• Blockchain logs

2. AI Agent Recommendations

Three specialized AI agents analyze each shipment:

Delay Agent

• Predicts future delays
• Analyzes historical patterns
• Provides ETA estimates

Escalation Agent

• Monitors trust score trends
• Flags high-risk actors
• Recommends alternative carriers

Recovery Agent

• Suggests mitigation strategies
• Provides action items
• Risk recovery plans

3. Trust Scoring System

Dynamic reputation system for all actors:

• Reliable (85-100): Green status
• Monitor (70-84): Blue status
• High Risk (50-69): Amber status
• Critical (0-49): Red status

Trust scores update based on:

• Risk events (LOW/MEDIUM/HIGH)
• Delivery performance
• Quality issues
• Historical behavior

4. Blockchain Verification

Only HIGH-risk events are logged to blockchain:

• Immutable audit trail
• Algorand network integration
• Transaction ID tracking
• Transparent verification

🎮 User Roles

Login Credentials (Demo)

Role	Actor ID	Trust Score	Shipments
Supplier	SUP01	55.8	3 shipments
Carrier	CAR01	69.6	4 shipments
Distributor	DIS01	90.2	3 shipments
Admin	ADMIN01	N/A	All shipments

📡 API Endpoints

Core Endpoints

• GET /shipments - All shipments
• GET /actors - All actors with trust scores
• GET /shipment/{id} - Shipment details
• GET /shipment/{id}/recommendations - AI recommendations
• GET /blockchain - Blockchain logs

Role-Specific Endpoints

• GET /supplier/{id}/shipments - Supplier's shipments
• GET /carrier/{id}/shipments - Carrier's shipments
• GET /distributor/{id}/shipments - Distributor's shipments
• GET /actor/{id}/trust - Actor's trust score
• GET /stats/system - System statistics

Analysis Endpoints

• POST /shipments/booking-analysis - Pre-booking risk analysis

🧪 Testing

Test Different Roles

1. Login as Supplier

   • Go to http://localhost:5173/login
   • Select "Supplier"
   • See only your 3 shipments
   • Trust score: 55.8

2. Login as Carrier

   • Select "Carrier"
   • See only your 4 assigned shipments
   • Trust score: 69.6

3. Login as Distributor

   • Select "Distributor"
   • See only your 3 incoming shipments
   • Trust score: 90.2

4. Login as Admin

   • Select "Admin"
   • See all 10 shipments
   • View system statistics

Test AI Recommendations

1. Login as any role
2. Click "View" on a HIGH-risk shipment
3. Scroll to "AI Agent Recommendations"
4. See 3 agent cards with:
   • Confidence scores
   • Severity levels
   • Action items

📁 Project Structure

ai-supply-chain-risk-passport/
├── backend/                         # Backend API and services
│   ├── agents/                      # AI agent modules
│   │   ├── delay_agent.py
│   │   ├── escalation_agent.py
│   │   └── recovery_agent.py
│   ├── data/
│   │   └── shipments.csv
│   ├── agent_coordinator.py
│   ├── blockchain_service.py
│   ├── main.py
│   ├── ml_model.py
│   ├── models.py
│   ├── monitoring_engine.py
│   ├── risk_engine.py
│   ├── trust_engine.py
│   └── requirements.txt
├── frontend/                        # React frontend application
│   ├── src/
│   │   ├── components/
│   │   │   ├── common/
│   │   │   └── layout/
│   │   ├── context/
│   │   │   └── AuthContext.jsx
│   │   ├── pages/
│   │   │   ├── dashboards/
│   │   │   ├── BlockchainPage.jsx
│   │   │   ├── LandingPage.jsx
│   │   │   ├── LoginPage.jsx
│   │   │   ├── ShipmentDetailPage.jsx
│   │   │   ├── ShipmentsPage.jsx
│   │   │   └── TrustOverviewPage.jsx
│   │   ├── services/
│   │   │   └── api.js
│   │   ├── utils/
│   │   │   └── helpers.js
│   │   ├── App.jsx
│   │   └── main.jsx
│   ├── package.json
│   └── vite.config.js
├── README.md                        # This file
├── HOW_TO_RUN.md                   # Setup and run instructions
├── PROJECT_STRUCTURE.md            # Detailed project structure
├── EXAMINER_GUIDE_COMPLETE.md      # Complete examiner guide
├── FINAL_SYSTEM_SPECIFICATION.md   # System design specification
├── ROLE_BASED_ARCHITECTURE.md      # Role-based architecture
├── SYSTEM_ARCHITECTURE.md          # Technical architecture
└── FIXES_COMPLETED.md              # Latest fixes documentation

See PROJECT_STRUCTURE.md for detailed file organization.

🔧 Technology Stack

Backend

• FastAPI - Modern Python web framework
• Scikit-learn - Machine learning (Isolation Forest)
• Pandas - Data processing
• Pydantic - Data validation

Frontend

• React 18 - UI framework
• Vite - Build tool
• TailwindCSS - Styling
• React Router - Navigation
• Axios - API calls
• Lucide React - Icons

Blockchain

• Algorand - Blockchain network (integration ready)

📈 Key Metrics

• 10 Shipments processed
• 10 Actors tracked (4 suppliers, 3 carriers, 3 distributors)
• 3 AI Agents providing recommendations
• 2 HIGH-risk events logged to blockchain
• 72.5 average network trust score

🎯 Demo Flow (3 Minutes)

1. Landing Page (30s)

   • Show value proposition
   • Click "Login"

2. Dashboard (30s)

   • Login as Supplier
   • Show KPIs and shipments
   • Explain color-coded risk badges

3. AI Recommendations (90s) ⭐

   • Click "View" on HIGH-risk shipment
   • Show 3 AI agent cards
   • Explain predictions and action items
   • Highlight confidence scores

4. Blockchain Verification (30s)

   • Show blockchain badge
   • Navigate to Blockchain page
   • Show transaction logs

🔐 Security Notes

• Authentication context manages user sessions
• Role-based access control
• Data filtering by actor ID
• Blockchain for immutable audit trail

📝 License

This project is for demonstration purposes.

🤝 Contributing

This is a hackathon project. For production use, additional features needed:

• Real authentication (JWT)
• Database integration (PostgreSQL)
• Real-time monitoring (WebSocket)
• Production blockchain integration
• Enhanced security measures

📚 Documentation

Essential documentation files:

• HOW_TO_RUN.md - Complete setup and run instructions
• EXAMINER_GUIDE_COMPLETE.md - Comprehensive guide for examiners
• FINAL_SYSTEM_SPECIFICATION.md - Official system design
• ROLE_BASED_ARCHITECTURE.md - Role-based business logic
• SYSTEM_ARCHITECTURE.md - Technical architecture
• PROJECT_STRUCTURE.md - Detailed file organization
• FIXES_COMPLETED.md - Latest improvements and fixes

📞 Support

For questions or issues, please refer to the documentation files above.

---

Built with ❤️ for supply chain transparency and risk intelligence