Scanimal - Animal Pattern Identification System

A comprehensive digital identity platform for animals, designed to provide unique identification through pattern recognition and secure ownership documentation.

🎯 Project Overview

Scanimal is a full-stack web application that enables animal owners to register their animals with digital identities, helping with:

• Theft Prevention: Digital identity makes it difficult for stolen animals to be sold
• Ownership Verification: Provides verifiable proof of ownership
• Lost Animal Recovery: Helps reunite lost animals with their owners
• Agricultural Management: Supports better livestock management and breeding programs

🚀 Features

Current Implementation

• ✅ User authentication (Registration & Login)
• ✅ JWT-based secure authentication
• ✅ Animal registration with multiple image uploads
• ✅ User dashboard with profile management
• ✅ Animal listing and search functionality
• ✅ Responsive web design
• ✅ MongoDB database integration

Future AI Integration (Planned)

• 🔄 Deep learning pattern recognition
• 🔄 Computer vision processing (OpenCV/TensorFlow)
• 🔄 High-accuracy pattern matching
• 🔄 Mobile app integration

🛠️ Technology Stack

Backend

• Node.js - Runtime environment
• Express.js - Web framework
• MongoDB - Database (local MongoDB)
• Mongoose - ODM for MongoDB
• JWT - Authentication tokens
• bcryptjs - Password hashing
• Multer - File upload handling

Frontend

• HTML5 - Structure
• CSS3 - Styling
• Vanilla JavaScript - Interactivity
• Fetch API - Backend communication

📋 Prerequisites

Before running the project, ensure you have:

1. Node.js (v14 or higher) - Download
2. MongoDB (local installation) - Download
3. MongoDB Compass (optional, for database management) - Download

🔧 Installation & Setup

1. Clone or Download the Project

cd scanimal

2. Install Dependencies

npm install

This will install:

• express
• mongoose
• jsonwebtoken
• bcryptjs
• multer
• cors
• dotenv

3. Set Up MongoDB

Option A: Using MongoDB Compass

1. Open MongoDB Compass
2. Connect to mongodb://127.0.0.1:27017
3. Create a new database named animalDB (or it will be created automatically)

Option B: Using mongosh (Command Line)

mongosh
use animalDB

4. Configure Environment Variables (Optional)

Create a .env file in the root directory:

MONGODB_URI=mongodb://127.0.0.1:27017/animalDB
JWT_SECRET=your_secret_key_here
PORT=3000
NODE_ENV=development

Note: If you don't create a .env file, the application will use default values.

5. Create Uploads Directory

The uploads directory will be created automatically when you register your first animal. However, you can create it manually:

mkdir uploads

🚀 Running the Application

Start the Server

npm start

Or for development:

npm run dev

The server will start on http://localhost:3000

Access the Application

Open your web browser and navigate to:

http://localhost:3000

📁 Project Structure

scanimal/
├── server.js                 # Main Express server
├── package.json              # Dependencies and scripts
├── .gitignore               # Git ignore file
├── .env.example             # Environment variables example
│
├── models/                   # Mongoose models
│   ├── User.js              # User schema
│   └── Animal.js            # Animal schema
│
├── routes/                   # API routes
│   ├── auth.js              # Authentication routes
│   ├── animals.js           # Animal routes
│   └── users.js             # User routes
│
├── middleware/               # Custom middleware
│   └── auth.js              # JWT authentication middleware
│
├── uploads/                 # Uploaded animal images (created automatically)
│
├── assets/                  # Static assets (images, logos)
│
├── index.html               # Homepage
├── login.html               # Login page
├── register-user.html        # User registration page
├── register.html             # Animal registration page
├── dashboard.html           # User dashboard
├── identify.html             # Animal identification page
├── animals-list.html         # Animals listing page
├── script.js                 # Frontend JavaScript
└── styles.css                # Stylesheet

🔐 API Endpoints

Authentication

• POST /api/auth/register - Register a new user
• POST /api/auth/login - Login user

Animals

• POST /api/animals/register - Register a new animal (requires auth)
• GET /api/animals - Get all animals (with optional filters)
• GET /api/animals/:id - Get animal by ID
• GET /api/animals/image/:filename - Get animal image
• POST /api/animals/identify - Identify animal (future AI implementation)

Users

• GET /api/users/me - Get current user profile (requires auth)
• GET /api/users/dashboard - Get dashboard data (requires auth)
• GET /api/users/animals - Get user's animals (requires auth)

👤 User Flow

1. Registration: Create a new account at /register-user.html
2. Login: Login at /login.html
3. Dashboard: View profile and registered animals at /dashboard.html
4. Register Animal: Register a new animal at /register.html (requires login)
5. View Animals: Browse all registered animals at /animals-list.html
6. Identify Animal: Upload image to identify an animal at /identify.html

🔒 Security Features

• Password Hashing: All passwords are hashed using bcrypt
• JWT Authentication: Secure token-based authentication
• Protected Routes: Animal registration requires authentication
• Input Validation: Server-side validation for all inputs
• File Upload Security: Only image files are accepted, with size limits

📝 Database Schema

User Collection

{
  name: String,
  email: String (unique),
  password: String (hashed),
  role: String (user/admin),
  createdAt: Date
}

Animal Collection

{
  ownerId: ObjectId (ref: User),
  animalType: String (cow/buffalo/goat/other),
  breed: String,
  gender: String (male/female),
  color: String,
  markings: String,
  description: String,
  images: [String], // Array of filenames
  patternVector: [Number], // Future AI feature
  registeredAt: Date
}

🎨 Frontend Features

• Responsive Design: Works on desktop, tablet, and mobile
• Modern UI: Clean and professional interface
• Real-time Updates: Dynamic content loading
• Error Handling: User-friendly error messages
• Authentication State: Automatic UI updates based on login status

🔮 Future Enhancements

AI Pattern Recognition

• Integration of OpenCV for image processing
• Deep learning models for pattern extraction
• Feature vector generation and storage
• Similarity matching algorithms
• High-accuracy identification

Additional Features

• Mobile application
• Advanced search and filtering
• Animal health records
• Breeding history tracking
• Export/import functionality
• Admin dashboard

🐛 Troubleshooting

MongoDB Connection Issues

• Ensure MongoDB is running: mongod or check MongoDB service
• Verify connection string: mongodb://127.0.0.1:27017/animalDB
• Check MongoDB Compass connection

Port Already in Use

• Change PORT in .env file
• Or kill the process using port 3000

Image Upload Issues

• Ensure uploads/ directory exists and has write permissions
• Check file size (max 5MB per image)
• Verify file type (only images allowed)

📄 License

This project is created for educational purposes as a university final-year project.

👨‍💻 Development Notes

• The project is designed to be AI-ready with clear integration points
• Pattern vectors are stored but not yet populated (awaiting AI implementation)
• All code is well-commented for educational purposes
• The structure follows best practices for scalability

🤝 Contributing

This is a university project. For questions or suggestions, please contact the project maintainer.

---

Built with ❤️ for animal protection and agricultural development