RiverGuard

RiverGuard is a comprehensive video analysis platform that uses machine learning to detect garbage and debris in water bodies. The system processes video streams through a YOLO-based detection model and stores results in Firebase Firestore for tracking and analysis.

🌊 Overview

RiverGuard helps monitor and track pollution in rivers and water bodies by:

Analyzing video streams for garbage detection
Providing real-time statistics and visualizations
Storing historical data for trend analysis
Offering an intuitive web interface for uploads and viewing results

✨ Features

Backend

Video Analysis API: RESTful API for processing video files
YOLO Model Integration: Real-time garbage detection using trained YOLO models
Firebase Integration: Automatic result persistence to Firestore
Docker Containerization: Scalable microservices architecture
Frame Extraction: Automatic frame sampling from video streams
Multi-format Support: Handles MP4, AVI, MOV, MKV formats

Frontend

Modern UI: Built with Next.js 15 and React 19
Drag & Drop Upload: Easy video file upload interface
Stream URL Support: Process videos from URLs
Dashboard: View statistics and analysis results
Real-time Updates: Live feedback during processing
Responsive Design: Works on desktop and mobile devices

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Frontend      │    │  Backend API    │    │  Model Server   │
│   (Next.js)     │───▶│  (FastAPI)      │───▶│  (YOLO Model)   │
│                 │    │                 │    │                 │
│ - Uploads video │    │ - Receives      │    │ - Receives      │
│ - Sends userId  │    │   video + userId│    │   images        │
│ - Gets results  │◀───│ - Processes     │◀───│ - Runs YOLO     │
│                 │    │   via containers│    │   prediction    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                            │
                            │        ┌─────────────────┐
                            │        │   Firebase      │
                            └───────▶│   Firestore     │
                                     │                 │
                                     │ - Stores results│
                                     │ - Persists data │
                                     └─────────────────┘
                                     ┌─────────────────┐
                                     │ Image Container │
                                     │                 │
                                     │ - Extracts      │
                                     │   frames        │
                                     │ - Sends to      │
                                     │   model         │
                                     └─────────────────┘

🛠️ Tech Stack

Backend

FastAPI: Modern Python web framework
Docker & Docker Compose: Containerization and orchestration
YOLO: Object detection model for garbage identification
Firebase Admin SDK: Database integration
FFmpeg: Video processing and frame extraction
Uvicorn: ASGI server

Frontend

Next.js 15: React framework with App Router
React 19: UI library
Firebase Client SDK: Real-time database access
CSS Modules: Scoped styling

📋 Prerequisites

Before you begin, ensure you have the following installed:

Docker (version 20.10+)
Docker Compose (version 2.0+)
Node.js (version 18+)
npm or yarn
Python (version 3.13+ for local development)
Firebase Account: Service account key file (RiverGuardAccountKey.json)

🚀 Installation & Setup

1. Clone the Repository

git clone <repository-url>
cd RiverGuard

2. Backend Setup

2.1. Configure Firebase

Place your Firebase service account key file in the BackEnd/ directory:

cp /path/to/your/RiverGuardAccountKey.json BackEnd/RiverGuardAccountKey.json

Ensure the Firebase project ID matches your configuration (default: trashapi-6eced)

2.2. Start Backend Services

cd BackEnd
docker-compose up -d

This will:

Build and start the API server on port 8000
Build and start the model server on port 8001
Create a Docker network for inter-container communication
Set up health checks and auto-restart

2.3. Verify Backend is Running

# Check container status
docker-compose ps

# Test health endpoint
curl http://localhost:8000/health

# View logs
docker-compose logs -f api-server

3. Frontend Setup

3.1. Install Dependencies

cd FrontEnd
npm install

3.2. Configure Environment

The frontend uses config.js for configuration. Update if needed:

// FrontEnd/config.js
export const config = {
  backendUrl: 'http://localhost:8000', // Update for production
  // ... other config
}

3.3. Start Development Server

npm run dev

The frontend will be available at http://localhost:3000

🎯 Usage

Uploading a Video

Navigate to the Dashboard (/dashboard)
Click "Upload Stream" or drag and drop a video file
Enter a duration (optional)
Click "Submit"
Wait for processing to complete
View results in the "View" tab

API Usage

Analyze Video Endpoint

curl -X POST \
  -F "video_file=@/path/to/video.mp4" \
  -F "userId=user123" \
  http://localhost:8000/api/analyze-video

Response:

{
  "success": true,
  "userId": "user123",
  "results": {
    "ok": true,
    "video": "video.mp4",
    "frames_sent": 16,
    "responses": [
      {
        "frame": "frame_00001.jpg",
        "response": {
          "garbage_count": 0,
          "filename": "frame_00001.jpg",
          "message": "Image processed successfully"
        }
      }
    ]
  }
}

Health Check

curl http://localhost:8000/health

📁 Project Structure

RiverGuard/
├── BackEnd/
│   ├── api_server.py              # FastAPI server with Firebase integration
│   ├── requirements.txt           # Python dependencies
│   ├── Dockerfile                 # API server container config
│   ├── docker-compose.yml         # Multi-container orchestration
│   ├── RiverGuardAccountKey.json  # Firebase service account key
│   ├── temp_uploads/              # Temporary video storage
│   ├── image_container/
│   │   ├── dockerfile
│   │   ├── image_client.py        # Frame extraction client
│   │   └── input/                 # Test video directory
│   └── model_container/
│       ├── dockerfile
│       ├── main.py                # YOLO prediction logic
│       ├── model_server.py        # Model HTTP server
│       └── FinalModel.pt          # Trained YOLO model
│
├── FrontEnd/
│   ├── src/
│   │   ├── app/
│   │   │   ├── page.js            # Home page
│   │   │   ├── dashboard/         # Dashboard page
│   │   │   ├── about/             # About page
│   │   │   ├── donate/            # Donate page
│   │   │   ├── components/
│   │   │   │   ├── FileDrop/      # File upload component
│   │   │   │   ├── ViewStats/     # Statistics viewer
│   │   │   │   ├── Navbar/        # Navigation bar
│   │   │   │   ├── HowTo/         # Instructions component
│   │   │   │   └── DonateOption/  # Donation component
│   │   │   └── api/               # Next.js API routes
│   │   └── lib/
│   │       └── firebase.js        # Firebase client config
│   ├── config.js                  # Frontend configuration
│   ├── package.json
│   └── next.config.mjs
│
└── README.md                      # This file

🔧 Configuration

Backend Environment Variables

The image container supports these environment variables:

INPUT_PATH: Path to input video (set by API server)
USER_ID: User identifier (set by API server)
WORKER_URL: Model server URL (default: http://visionmodel:8001/)

Firebase Configuration

Firebase integration requires:

Service Account Key: RiverGuardAccountKey.json in BackEnd/ directory
Firestore Collection: videos (automatically created)

Document Structure:

{
  "userId": "user_id_string",
  "videoFilename": "original_filename.mp4",
  "uploadDate": "timestamp",
  "totalGarbageCount": 19,
  "framesProcessed": 16,
  "garbageCountPerFrame": [0, 0, 0, 1, 2, ...]
}

Docker Compose Services

api-server: FastAPI server with Docker client capabilities
visionmodel: YOLO model server for garbage detection
imageclient: Temporary container for frame extraction

🐛 Troubleshooting

Common Issues

1. Backend API Not Accessible

# Check if containers are running
docker ps

# Verify API server is running
curl http://localhost:8000/health

# Check logs
docker-compose logs api-server

# Restart services
docker-compose restart api-server

2. Model Server Not Responding

# Check model server logs
docker-compose logs visionmodel

# Verify network connectivity
docker network inspect seniorprojtesting_my-network

# Test model server directly
curl http://localhost:8001/

3. Video Processing Fails

Ensure video file exists and is accessible
Check file permissions
Verify FFmpeg is working: docker exec imageclient ffmpeg -version
Check container logs for specific error messages

4. Firebase Integration Issues

# Verify credentials file exists
ls BackEnd/RiverGuardAccountKey.json

# Check Firebase logs
docker-compose logs api-server | grep -i firebase

# Verify Firebase Admin SDK is installed
docker exec api-server pip list | grep firebase

5. Frontend Connection Issues

Verify backend URL in FrontEnd/config.js
Check CORS settings in api_server.py
Ensure backend is running on the correct port
Check browser console for errors

Debug Commands

# View all container logs
docker-compose logs -f

# Check container status
docker-compose ps

# Inspect Docker network
docker network inspect seniorprojtesting_my-network

# Run container interactively
docker exec -it api-server /bin/bash

# Clean up and restart
docker-compose down
docker-compose up -d --build

📊 Performance

Processing Time: ~3-5 seconds for a 15-second video (16 frames)
Memory Usage: Containers are created and destroyed per request
File Size Limits: Configured to handle videos up to 100MB (adjustable)
Scalability: Each video processing request runs in isolation

🔒 Security Considerations

CORS: Currently set to allow all origins (allow_origins=["*"]). Update for production.
File Upload: Implement file size and type validation
Firebase: Keep service account keys secure and never commit to version control
API Keys: Store sensitive configuration in environment variables

🧪 Testing

Backend Testing

# Test health endpoint
curl http://localhost:8000/health

# Test video analysis
curl -X POST \
  -F "video_file=@test_video.mp4" \
  -F "userId=test_user" \
  http://localhost:8000/api/analyze-video

Frontend Testing

cd FrontEnd

# Run linting
npm run lint

# Test Firebase connection
npm run test:firestore

# Run simple tests
npm run test:simple

🚢 Deployment

Production Considerations

Environment Variables: Use environment variables for sensitive configuration
CORS: Restrict CORS to your frontend domain
Firebase: Use production Firebase project
Docker: Use production-optimized Docker images
SSL/TLS: Enable HTTPS for all services
Monitoring: Set up logging and monitoring services
Backup: Regular backups of Firebase data

Docker Production Build

# Build production images
docker-compose -f docker-compose.prod.yml build

# Start production services
docker-compose -f docker-compose.prod.yml up -d

📝 API Documentation

Endpoints

`POST /api/analyze-video`

Analyzes a video for garbage detection.

Request:

Method: POST
Content-Type: multipart/form-data
Parameters:
- video_file (file, required): Video file to analyze
- userId (string, required): User identifier

Response:

{
  "success": true,
  "userId": "user123",
  "results": {
    "ok": true,
    "video": "video.mp4",
    "frames_sent": 16,
    "responses": [...]
  }
}

`GET /health`

Health check endpoint.

Response:

{
  "status": "healthy",
  "service": "video-analysis-api"
}

🤝 Contributing

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

📄 License

[Specify your license here]

👥 Authors

[Add author information]

🙏 Acknowledgments

YOLO model for object detection
FastAPI for the robust backend framework
Next.js for the modern frontend framework
Firebase for data persistence

📞 Support

For issues or questions:

Check the troubleshooting section above
Review container logs for specific error messages
Ensure all services are running: docker-compose ps
Test the health endpoint: curl http://localhost:8000/health

RiverGuard - Protecting our waterways, one frame at a time. 🌊♻️

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
BackEnd		BackEnd
FrontEnd		FrontEnd
.DS_Store		.DS_Store
README.md		README.md
RiverGuard Final Report.pdf		RiverGuard Final Report.pdf
RiverGuard-STP-STR.docx		RiverGuard-STP-STR.docx

Folders and files

Latest commit

History

Repository files navigation

RiverGuard

🌊 Overview

✨ Features

Backend

Frontend

🏗️ Architecture

🛠️ Tech Stack

Backend

Frontend

📋 Prerequisites

🚀 Installation & Setup

1. Clone the Repository

2. Backend Setup

2.1. Configure Firebase

2.2. Start Backend Services

2.3. Verify Backend is Running

3. Frontend Setup

3.1. Install Dependencies

3.2. Configure Environment

3.3. Start Development Server

🎯 Usage

Uploading a Video

API Usage

Analyze Video Endpoint

Health Check

📁 Project Structure

🔧 Configuration

Backend Environment Variables

Firebase Configuration

Docker Compose Services

🐛 Troubleshooting

Common Issues

1. Backend API Not Accessible

2. Model Server Not Responding

3. Video Processing Fails

4. Firebase Integration Issues

5. Frontend Connection Issues

Debug Commands

📊 Performance

🔒 Security Considerations

🧪 Testing

Backend Testing

Frontend Testing

🚢 Deployment

Production Considerations

Docker Production Build

📝 API Documentation

Endpoints

POST /api/analyze-video

GET /health

🤝 Contributing

📄 License

👥 Authors

🙏 Acknowledgments

📞 Support

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`POST /api/analyze-video`

`GET /health`