🦅 Hawkeye

Campus Incident Reporting & Predictive Maintenance System

🚀 Live Demo • 📚 Documentation • 🤖 ML API• 📸 Demo Video • 📚 Data ON which ml model was trained on

📖 Overview

Hawkeye is an intelligent campus incident reporting and predictive maintenance system that leverages machine learning to predict equipment failures before they occur. Built for educational institutions, it streamlines incident management, technician scheduling, and proactive maintenance planning.

✨ Key Highlights

🤖 AI-Powered Predictions: ML model deployed on BentoML Cloud predicts equipment failures with confidence scores
📊 Real-time Analytics: Comprehensive dashboards with heatmaps, aging analysis, and SLA monitoring
👥 Multi-role System: Separate portals for Students, Administrators, and Technicians
🔔 Smart Notifications: Real-time alerts for critical incidents and assignments
📍 Geolocation Tracking: GPS-based incident reporting with interactive heatmaps
📈 Performance Metrics: Technician performance tracking and workload optimization

🎯 Features

For Students & Staff

📝 Quick Incident Reporting: Submit issues with images, location, and detailed descriptions
📱 Real-time Tracking: Monitor incident status from creation to resolution
💬 Feedback System: Rate technician performance and provide constructive feedback
🔔 Instant Notifications: Get updates on your reported incidents

For Administrators

🎛️ Comprehensive Dashboard: Overview of all incidents with advanced filtering
👷 Technician Management: Assign tasks based on specialization and availability
📊 Analytics Suite:
- Incident heatmaps by location and category
- Aging analysis for long-pending issues
- SLA monitoring with automatic escalation
- Predictive alerts powered by ML
📈 Performance Tracking: Monitor technician efficiency and resolution times
👥 User Management: Control access and manage roles

For Technicians

📋 Task Dashboard: View assigned incidents with priority sorting
✅ Status Updates: Update incident progress in real-time
📸 Completion Reports: Submit completion notes and images
📊 Personal Metrics: Track your performance and completed tasks

ML-Powered Intelligence

🔮 Failure Prediction: Machine learning model predicts equipment failures
📉 Risk Assessment: Confidence scoring for predicted incidents
🎯 Critical Alerts: Automatic flagging of high-risk areas
📊 Model Transparency: R² scores and validation metrics displayed

🏗️ Architecture

Tech Stack

Frontend

Framework: Next.js 16 (App Router)
UI Library: React 19
Styling: Tailwind CSS 4
Components: Radix UI
Charts: Recharts & Plotly.js
Forms: React Hook Form + Zod

Backend

Database: MongoDB Atlas
Authentication: NextAuth.js
API: Next.js API Routes (REST)
Rate Limiting: Custom middleware

Machine Learning

Deployment: BentoML Cloud
API Endpoint: failure-prediction-prod
Features: Equipment age, maintenance history, environmental factors
Output: Days to failure prediction with confidence scores

System Components

┌─────────────────────────────────────────────────────────────┐
│                      Frontend Layer                         │
│  ┌──────────┬──────────┬──────────┬──────────────────┐     │
│  │  User    │  Admin   │Technician│   Components     │     │
│  │Dashboard │Dashboard │ Portal   │  (Radix UI)      │     │
│  └──────────┴──────────┴──────────┴──────────────────┘     │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                    API Routes (Next.js)                     │
│  ┌────────┬─────────┬───────────┬─────────┬──────────┐     │
│  │Incidents│Technicians│Predictions│Notifications│Auth│     │
│  └────────┴─────────┴───────────┴─────────┴──────────┘     │
└─────────────────────────────────────────────────────────────┘
           │                                    │
           ▼                                    ▼
┌──────────────────────┐          ┌──────────────────────────┐
│   MongoDB Atlas      │          │   BentoML Cloud API      │
│  ┌────────────────┐  │          │  ┌────────────────────┐ │
│  │ • users        │  │          │  │ Failure Prediction │ │
│  │ • incidents    │  │          │  │    ML Model        │ │
│  │ • predictions  │  │          │  │  (R² Validated)    │ │
│  │ • notifications│  │          │  └────────────────────┘ │
│  │ • technician_  │  │          │                          │
│  │   schedule     │  │          └──────────────────────────┘
│  └────────────────┘  │
└──────────────────────┘

🗄️ Database Schema

Collections

users

{
  _id: ObjectId,
  email: String (unique, indexed),
  password_hash: String,
  name: String,
  role: String, // "user" | "admin" | "technician"
  specialization: String, // For technicians
  created_at: Date,
  updated_at: Date
}

incidents

{
  _id: ObjectId,
  user_id: ObjectId (indexed),
  title: String,
  category: String, // "Electricity", "Water", "IT", "Hostel", "Garbage"
  description: String,
  image_url: String,
  location: String,
  latitude: Number,
  longitude: Number,
  status: String (indexed), // "new", "assigned", "in_progress", "resolved", "closed"
  priority: Number, // 1-5
  assigned_to: ObjectId (indexed),
  created_at: Date (indexed),
  updated_at: Date,
  resolved_at: Date
}

predictions

{
  _id: ObjectId,
  location: String (indexed),
  category: String (indexed),
  confidence_score: Number, // 0-1
  alert_message: String,
  predicted_time: Date,
  days_to_next_failure: Number,
  model_info: Object,
  created_at: Date (indexed)
}

technician_schedule

{
  _id: ObjectId,
  technician_id: ObjectId (indexed),
  incident_id: ObjectId (indexed),
  scheduled_time: Date (indexed),
  duration_minutes: Number,
  status: String (indexed), // "scheduled", "in_progress", "completed", "cancelled"
  created_at: Date
}

notifications

{
  _id: ObjectId,
  user_id: ObjectId (indexed),
  type: String,
  title: String,
  message: String,
  link: String,
  read: Boolean (indexed),
  created_at: Date (indexed)
}

technician_feedback

{
  _id: ObjectId,
  incident_id: ObjectId (indexed),
  technician_id: ObjectId (indexed),
  user_id: ObjectId (indexed),
  rating: Number, // 1-5
  comment: String,
  created_at: Date (indexed)
}

🚀 Getting Started

Prerequisites

Node.js 18+ and npm/pnpm
MongoDB Atlas account (or local MongoDB instance)
BentoML Cloud API access (optional, for ML predictions)

Installation

Clone the repository

git clone https://github.com/SCARPxVeNOM/hawkeye.git
cd hawkeye/v0-incident-reporting-system

Install dependencies
```
npm install
# or
pnpm install
```

Set up environment variables

Create a .env.local file in the root directory:

# MongoDB Configuration
MONGODB_URI=mongodb+srv://your-connection-string
MONGODB_DB_NAME=incident_reporting

# NextAuth Configuration
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your-secret-key-here

# Google OAuth (Optional)
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

Initialize the database

node scripts/init-db.js
node scripts/create-admin.js
node scripts/create-technician.js

Run the development server
```
npm run dev
# or
pnpm dev
```
Open your browser

Navigate to http://localhost:3000

Default Credentials

Admin Access

URL: /admin/login
Email: admin@campus.com
Password: admin123

Technician Access

URL: /technician/login
All technicians use password: tech123

Available Technician Accounts:

Electrical Technician
- Email: john.smith@campus.com
- Password: tech123
- Specialization: Electrical
Plumbing Technician
- Email: sarah.johnson@campus.com
- Password: tech123
- Specialization: Plumbing
HVAC Technician
- Email: mike.davis@campus.com
- Password: tech123
- Specialization: HVAC
IT Technician
- Email: emily.chen@campus.com
- Password: tech123
- Specialization: IT
General Technician
- Email: david.wilson@campus.com
- Password: tech123
- Specialization: General

🤖 ML Model Integration

Model Files

The trained ML model files are available in the model/ directory:

xgboost_advanced_model.joblib - Main XGBoost model for failure prediction (169MB)
scaler.joblib - Feature scaler for data normalization
target_encoder.joblib - Target encoder for categorical features
feature_info.joblib / feature_info.pkl - Feature metadata and information
optuna_study_advanced.pkl - Optuna hyperparameter optimization study
test_predictions_advanced.csv - Test predictions and evaluation results
feature_importance_advanced.png - Feature importance visualization

BentoML Cloud API

The ML model is deployed on BentoML Cloud and accessible via REST API:

Production Endpoint: https://failure-prediction-prod-0d460137.mt-guc1.bentoml.ai
Playground: BentoML Playground

Note: The model files in the repository can be used for local development or to deploy your own BentoML service. The production API uses the same model architecture.

Prediction Request Format

{
  "location": "Building A - Room 101",
  "category": "Electricity",
  "equipment_age_days": 1825,
  "manufacturer": "Generic",
  "model": "Standard",
  "last_maintenance_days_ago": 90,
  "operating_hours": 4380,
  "temperature_celsius": 25.5,
  "humidity_percent": 55.0,
  "vibration_level": 2.5,
  "power_consumption_kw": 5.0
}

Response Format

{
  "prediction": 0.75,
  "days_to_next_failure": 15,
  "model_info": {
    "validation_r2": "0.85",
    "test_r2": "0.82"
  }
}

Integration

import { getMLPrediction } from '@/lib/services/prediction.service'

// Get prediction for an incident
const prediction = await getMLPrediction(incident)
console.log(`Failure predicted in ${prediction.days_to_next_failure} days`)

📁 Project Structure

v0-incident-reporting-system/
├── app/                          # Next.js App Router
│   ├── admin/                    # Admin dashboard
│   │   ├── dashboard/            # Admin dashboard page
│   │   └── login/                # Admin login
│   ├── api/                      # API routes
│   │   ├── auth/                 # Authentication endpoints
│   │   ├── incidents/            # Incident CRUD
│   │   ├── predictions/          # ML predictions
│   │   ├── technicians/          # Technician management
│   │   └── notifications/        # Notification system
│   ├── auth/                     # User authentication pages
│   ├── dashboard/                # User dashboard
│   ├── technician/               # Technician portal
│   └── layout.tsx                # Root layout
├── components/                   # React components
│   ├── ui/                       # Radix UI components
│   ├── incident-form.tsx         # Incident reporting form
│   ├── incident-list.tsx         # Incident list view
│   ├── analytics-overview.tsx   # Dashboard analytics
│   ├── heatmap.tsx               # Location heatmap
│   ├── predictive-alerts.tsx    # ML prediction alerts
│   └── ...                       # Other components
├── lib/                          # Utility functions
│   ├── services/                 # Business logic services
│   │   ├── incident.service.ts   # Incident operations
│   │   ├── prediction.service.ts # ML predictions
│   │   ├── technician.service.ts # Technician management
│   │   └── notification.service.ts
│   ├── mongodb.ts                # MongoDB connection
│   └── utils.ts                  # Helper functions
├── scripts/                      # Database initialization
│   ├── init-db.js                # MongoDB setup
│   ├── create-admin.js           # Create admin user
│   └── create-technician.js      # Create technician users
├── public/                       # Static assets
├── types/                        # TypeScript definitions
├── .env.local                    # Environment variables
└── package.json                  # Dependencies

📊 Features Deep Dive

1. Intelligent Predictions

The system uses both rule-based and ML-powered prediction algorithms:

Rule-Based Predictions:

Frequency analysis of historical incidents
Location-category pattern recognition
7-day rolling window analysis

ML-Based Predictions (BentoML):

Equipment age and maintenance history analysis
Environmental factor correlation (temperature, humidity, vibration)
Regression model with R² validation
Days-to-failure prediction with confidence scores

2. SLA Monitoring & Escalation

Automatic tracking of incident age
SLA breach detection and alerting
Priority escalation for overdue incidents
Configurable SLA thresholds by category

3. Heatmap Visualization

Interactive geospatial incident mapping
Category-based filtering
Density visualization using Plotly.js
Real-time updates

4. Technician Performance

Metrics tracked:

Average resolution time
Completion rate
User satisfaction ratings
Workload distribution

5. Notification System

Real-time push notifications
Role-based notification routing
Notification center with read/unread status
Email integration (optional)

🔧 Configuration

Environment Variables

Variable	Description	Required
`MONGODB_URI`	MongoDB connection string	✅ Yes
`MONGODB_DB_NAME`	Database name	✅ Yes
`NEXTAUTH_URL`	Application URL	✅ Yes
`NEXTAUTH_SECRET`	NextAuth secret key	✅ Yes
`GOOGLE_CLIENT_ID`	Google OAuth client ID	❌ No
`GOOGLE_CLIENT_SECRET`	Google OAuth secret	❌ No

Customization

SLA Thresholds

Update in lib/services/escalation.service.ts:

const SLA_THRESHOLDS = {
  electricity: 24, // hours
  water: 12,
  // Customize per category
}

🚢 Deployment

Vercel (Recommended)

Push your code to GitHub
Import project in Vercel
Configure environment variables
Deploy!

Docker

docker build -t hawkeye .
docker run -p 3000:3000 --env-file .env.local hawkeye

Manual Deployment

npm run build
npm start

📚 Documentation

Comprehensive documentation is available at:

🔗 https://documentation-zeta-eight.vercel.app/

Documentation includes:

AI Logic: ML prediction system architecture
Routine Flow: System workflows and processes
Task Scheduling: Background jobs and cron logic
DB Schema: Detailed database documentation

Contributors

_{Aryan Anand}
_SCARPxVeNOM

_Anubhav
_Anu062004

_{Ayush Saklani}
_{ayushsaklani-min}

How to Contribute

Fork the repository
Create a feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

📝 License

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

🙏 Acknowledgments

BentoML for providing the ML deployment platform
Vercel for hosting and deployment
MongoDB Atlas for database infrastructure
Radix UI for accessible component primitives
Next.js team for the amazing framework

📧 Contact & Support

GitHub: @SCARPxVeNOM
Repository: hawkeye
Issues: Report a bug

Built with ❤️ for smarter campus maintenance

⬆ Back to Top

Name		Name	Last commit message	Last commit date
app		app
components		components
lib		lib
model		model
public		public
scripts		scripts
styles		styles
types		types
.gitattributes		.gitattributes
.gitignore		.gitignore
README.md		README.md
components.json		components.json
next-env.d.ts		next-env.d.ts
next.config.mjs		next.config.mjs
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
postcss.config.mjs		postcss.config.mjs
tailwind.config.js		tailwind.config.js
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation

🦅 Hawkeye

Campus Incident Reporting & Predictive Maintenance System

📖 Overview

✨ Key Highlights

🎯 Features

For Students & Staff

For Administrators

For Technicians

ML-Powered Intelligence

🏗️ Architecture

Tech Stack

Frontend

Backend

Machine Learning

System Components

🗄️ Database Schema

Collections

users

incidents

predictions

technician_schedule

notifications

technician_feedback

🚀 Getting Started

Prerequisites

Installation

Default Credentials

Admin Access

Technician Access

🤖 ML Model Integration

Model Files

BentoML Cloud API

Prediction Request Format

Response Format

Integration

📁 Project Structure

📊 Features Deep Dive

1. Intelligent Predictions

2. SLA Monitoring & Escalation

3. Heatmap Visualization

4. Technician Performance

5. Notification System

🔧 Configuration

Environment Variables

Customization

Categories

SLA Thresholds

🚢 Deployment

Vercel (Recommended)

Docker

Manual Deployment

📚 Documentation

Contributors

How to Contribute

📝 License

🙏 Acknowledgments

📧 Contact & Support

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages