🦁 WildGuard AI — Wildlife Threat Intelligence Platform

AI-powered real-time wildlife detection and risk assessment for agricultural stakeholders.

Built with React + Flask + TensorFlow | Full-stack ML + Web Engineering

🎯 What This Project Demonstrates

• Full-Stack Engineering: React frontend, Flask backend, TensorFlow ML pipeline, SQLite persistence
• ML + Product: Beyond accuracy metrics—end-to-end system design for real-world decision-making
• UI/UX Intentionality: Design system, component library, dark theme, responsive design
• Production Thinking: Error handling, CORS, file validation, API design, database schema
• Problem-Solving: Rule-based risk engine fuses model confidence with contextual logic

🚀 Quick Start

Backend Setup

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
python api.py

Backend runs on http://localhost:5000

Frontend Setup

cd frontend
npm install
npm run dev

Frontend runs on http://localhost:5173

Test It

• Sample prediction: curl http://localhost:5000/predict?sample=true
• Upload image: curl -F "file=@image.jpg" http://localhost:5000/predict
• View history: curl http://localhost:5000/recent

🏗️ Architecture

┌─────────────────────────────────────────────────────┐
│               React Frontend (Vite)                 │
│  ┌────────────────────────────────────────────────┐ │
│  │ Hero | Command Center | Timeline | Insights    │ │
│  │ Component Library: Atoms, Molecules, Organisms │ │
│  └────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘
                        ↕ (REST API)
┌─────────────────────────────────────────────────────┐
│          Flask API (http://localhost:5000)          │
│  /predict (POST/GET), /recent, /sample              │
└─────────────────────────────────────────────────────┘
           ↕ (Model Inference) ↕ (Persistence)
     ┌──────────────┐         ┌──────────────┐
     │  TensorFlow  │         │  SQLite DB   │
     │ Classifier   │         │  Detection   │
     │ (18 classes) │         │  History     │
     └──────────────┘         └──────────────┘

🧠 The ML Model

• Training Data: 18 animal classes (Tigers, Leopards, Elephants, Crocodiles, etc.)
• Architecture: TensorFlow/Keras CNN
• Input: 96×96px RGB images
• Output: Top-3 class predictions with confidence scores

⚙️ The Risk Engine (Business Logic)

Not all predictions are equal. The system fuses three signals:

1. Model Confidence (0–1.0)

   • High confidence (≥0.95) → escalate crop/livestock risk
   • Low confidence (<0.6) → de-escalate human risk

2. Historical Sightings (0+)

   • 3+ recent detections → increase human/crop urgency
   • Informs trend analysis and alert thresholds

3. Contextual Rules (Optional)

   • Example: Crocodile near water → elevated human/livestock risk
   • Extensible for site-specific logic

Output: Risk scores (low/moderate/high/very_high) + actionable recommendations

🎨 Design System

Color Palette (Dark, premium)

• Primary background: #0B1020
• Text: #E6EEF8 (primary), #9AA7BF (muted)
• Accent: #7C3AED (purple)
• Risk levels: Green (low) → Orange (medium) → Red (high)

📊 Technical Stack

Layer	Technology
Frontend	React 18, Vite, CSS (design tokens)
Backend	Flask, Python 3.9+
ML	TensorFlow/Keras
Database	SQLite

📝 API Endpoints

Method	Endpoint	Description
POST	/predict	Upload image file for classification
GET	/predict?sample=true	Get random sample prediction
GET	/predict?sample=Species	Get prediction for specific species
GET	/recent	Fetch recent detection history

🎓 Key Design Decisions

Decision	Why
96×96px input	Fast inference, pragmatic for mobile capture
Rule-based risk	Interpretability + control for safety-critical domain
SQLite	Simplicity + portability for MVP
React	Industry standard + hire-ability
Component system	Scalability + maintainability

📚 Documentation

• Full portfolio breakdown: See PORTFOLIO_PACKAGE.md
• Recruiter demo script: In PORTFOLIO_PACKAGE.md (Section 3)
• Architecture deep-dive: In PORTFOLIO_PACKAGE.md (Section 4)
• Deployment guide: In PORTFOLIO_PACKAGE.md (Section 10)

🚢 Deploy (Quick Options)

Docker

docker build -t wildguard .
docker run -p 5000:5000 wildguard

Heroku

heroku create wildguard-ai
git push heroku main

Render.com (Free Tier)

Connect GitHub repo → Deploy

🔮 Future Directions

• Live camera feed integration (WebRTC)
• Multi-model ensemble (confidence boost)
• Geographic heat maps
• Push notifications for alerts
• Admin dashboard with audit logs
• Model retraining pipeline

📄 License

MIT — Use freely for learning and portfolio purposes.

---

View full portfolio breakdown →