🐾 WildLanka - Wildlife Safari Management System

A comprehensive Wildlife Safari Management System built specifically for Sri Lankan wildlife tourism. This full-stack MERN application provides an end-to-end solution for managing safari bookings, staff operations, wildlife conservation efforts, and customer interactions with trilingual support (English, Sinhala, Tamil).

Academic Project: This repository showcases a collaborative Y2S2 group project developed by a passionate team of five contributors, focused on wildlife conservation and modern web development practices.

---

📋 Table of Contents

• 📸 Screenshots
• 🌟 Features
• 🛠️ Tech Stack
• 📁 Project Structure
• ⚙️ Installation & Setup
• 🚀 Getting Started
• 📚 API Documentation
• 🌍 Multilingual Support
• � Security
• �👥 Contributors
• 📄 License
• 📞 Support

---

📸 Screenshots

🏠 Home & Landing Page

Beautiful landing page with wildlife imagery and awareness content

🎯 Safari Packages & Booking

Comprehensive safari package listings with detailed itineraries

Wildlife calendar for planning your safari adventures

📸 Photo Marketplace & Gallery

Wildlife photo marketplace with direct sales and bidding system

💼 Admin & Staff Dashboards

Comprehensive admin panel with analytics and management tools

Driver dashboard for managing assignments and schedules

Tour guide dashboard with booking and customer information

👤 User Features

User account management and profile settings

Customer reviews and feedback system

� Information & Support Pages

About WildLanka and our mission

Contact page for customer inquiries

Frequently asked questions and support

� Legal & Privacy

Click to view legal pages

Privacy policy and data protection

Terms of service and usage guidelines

Cookie policy and consent management

---

🌟 Features

🦁 Core Safari Management

• 📅 Smart Booking System: Real-time availability and calendar integration
• 🎯 Package Management: Customizable safari packages with detailed itineraries and photo galleries
• 🎨 Custom Safari Requests: Personalized safari package creation based on customer preferences
• 🚗 Fleet Management: Vehicle tracking, assignment, and maintenance scheduling
• 👨‍💼 Staff Coordination: Driver and tour guide management with role-based dashboards
• ⏰ Attendance Tracking: Comprehensive staff attendance monitoring and reporting

💼 Business Operations

• 💳 Secure Payments: Stripe integration for bookings, donations, and photo purchases
• 📊 Analytics Dashboard: Comprehensive admin panel with booking trends and insights
• 💰 Payroll System: Staff payment tracking and automated payroll management
• 📸 Wildlife Photo Marketplace:
  • Direct photo sales with secure payment processing
  • 🎯 Real-time Bidding System: Live auction platform for exclusive wildlife photography
  • Automated bid scheduling with countdown timers
  • Instant winner notifications and purchase reminders
  • Secure photo delivery with time-limited download links (7-day expiry, 5 downloads max)
  • Digital watermarking and copyright protection
• 📝 Contact Management: Structured customer inquiry and message handling system
• 🔍 Admin Audit Trail: Comprehensive tracking of all administrative actions

🤖 AI-Powered Features

• 🗣️ Trilingual Chatbot: Intelligent AI assistant with context awareness in English, Sinhala, and Tamil
• 🌤️ Weather Integration: Real-time weather data for optimal safari planning
• 🔔 Smart Notifications: Multi-channel automated notifications system
  • Bidding updates and winner alerts
  • Photo delivery confirmations
  • Purchase reminders
  • Booking confirmations and updates
  • System-wide announcements

🎨 Modern User Experience

• 📱 Responsive Design: Mobile-first approach with TailwindCSS
• 🎭 Smooth Animations: Framer Motion powered interactions
• � Theme Support: Dark/Light mode switching
• ♿ Accessibility: WCAG compliant design standards

🌍 Conservation Focus

• 💚 Donation System: Support wildlife conservation efforts
• 📈 Conservation Tracking: Wildlife monitoring and data visualization
• 🎓 Educational Content: Awareness and educational resources

---

🛠️ Tech Stack

Backend

🔧 Runtime & Framework
├── Node.js (Latest LTS)
├── Express.js 5.1.0
└── ES6 Modules

🗄️ Database & ODM
├── MongoDB (Latest)
└── Mongoose 8.17.1

🔐 Authentication & Security
├── JWT (jsonwebtoken 9.0.2)
├── bcryptjs 3.0.2
└── CORS 2.8.5

💳 Payment & Services
├── Stripe 18.4.0
├── Cloudinary 2.7.0
├── Nodemailer 7.0.5
└── PDFKit 0.17.1

⚙️ Utilities
├── Multer 2.0.2 (File uploads)
├── node-cron 4.2.1 (Scheduling)
├── dotenv 17.2.1 (Environment)
└── mongoose-paginate-v2 1.7.4

Frontend

⚛️ Core Framework
├── React 19.1.1
├── React DOM 19.1.1
└── Vite (Build tool)

🛣️ Routing & State
├── React Router DOM 7.8.0
└── React Context API

🎨 Styling & Animation
├── TailwindCSS 4.1.11
└── Framer Motion 12.23.12

🌍 Internationalization
├── i18next 25.5.2
└── react-i18next 15.7.3

📊 Data Visualization
├── Recharts 2.15.4
└── jsPDF 2.5.1

🔧 Utilities
├── Axios 1.11.0
├── React Calendar 6.0.0
└── EmailJS Browser 4.4.1

---

📁 Project Structure

WildLanka/
│
├── 📄 Configuration Files
│   ├── README.md
│   ├── LICENSE
│   ├── package.json
│   └── PROJECT_STRUCTURE_DOCUMENTATION.md
│
├── 🔧 backend/                     # Server-side Application
│   ├── server.js                   # Entry point
│   ├── config/                     # Configuration files
│   ├── controllers/                # Business logic (15 controllers)
│   ├── middleware/                 # Authentication & upload middleware
│   ├── models/                     # MongoDB schemas (14 models)
│   ├── routes/                     # API endpoints (15 route files)
│   ├── services/                   # Background services
│   └── temp/                       # Temporary file storage
│
└── 🎨 frontend/                    # Client-side Application
    ├── public/                     # Static assets
    ├── src/
    │   ├── components/             # Reusable UI components (40+ components)
    │   ├── pages/                  # Full page components (25+ pages)
    │   ├── context/                # React Context providers
    │   ├── hooks/                  # Custom React hooks
    │   ├── services/               # API service functions
    │   ├── translations/           # i18n language files
    │   └── utils/                  # Utility functions
    └── vite.config.js              # Build configuration

📖 For detailed project structure, see PROJECT_STRUCTURE_DOCUMENTATION.md

---

⚙️ Installation & Setup

Prerequisites

✅ Node.js >= 18.0.0
✅ npm >= 9.0.0
✅ MongoDB >= 6.0
✅ Git

Environment Variables

This project uses environment variables for sensitive configuration. The actual .env files are not included in the repository for security reasons.

Backend Environment Variables:

# Copy example file and configure
cp backend/.env.example backend/.env

# Server Configuration
PORT=5000

# Database Connection
MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/wildlanka

# Image Upload Service
IMGBB_API_KEY=your_imgbb_api_key_here

# Frontend URLs (for CORS)
CLIENT_ORIGIN=http://localhost:5173
FRONTEND_URL=http://localhost:5173

# Authentication
JWT_SECRET=your-super-secret-jwt-key-change-this

# Payment Processing
STRIPE_SECRET_KEY=sk_test_your_stripe_secret_key_here

# Weather Service
OPEN_WEATHER_MAP_API_KEY=your_openweathermap_api_key_here

Frontend Environment Variables:

# Copy example file and configure
cp frontend/.env.example frontend/.env

# API Configuration
VITE_API_BASE_URL=http://localhost:5000

⚠️ CRITICAL SECURITY NOTE:

• NEVER commit .env files to GitHub - they contain sensitive API keys and secrets
• Use .env.example files as templates to create your own .env files locally
• Each developer must obtain their own API keys and credentials
• See SECURITY.md for detailed security guidelines and setup instructions

---

🚀 Getting Started

1. Clone Repository

git clone https://github.com/OsandaMadugalle/WildLanka.git
cd WildLanka

2. Install Dependencies

# Install root dependencies
npm install

# Install backend dependencies
cd backend
npm install

# Install frontend dependencies
cd ../frontend
npm install

3. Configure Environment

# Set up backend environment
cd backend
cp .env.example .env
# Edit .env with your configuration

# Set up frontend environment
cd ../frontend
cp .env.example .env
# Edit .env with your configuration

4. Start Development Servers

Terminal 1 - Backend Server:

cd backend
npm run dev
# Server runs on http://localhost:5000

Terminal 2 - Frontend Development Server:

cd frontend
npm run dev
# Client runs on http://localhost:3000

5. Access Application

• Frontend: http://localhost:3000
• Backend API: http://localhost:5000
• API Health Check: http://localhost:5000/health

---

📚 API Documentation

Authentication Endpoints

Method	Endpoint	Description
POST	/api/auth/register	User registration
POST	/api/auth/login	User login
POST	/api/auth/staff-login	Staff login
POST	/api/auth/forgot-password	Password reset
GET	/api/auth/verify-token	Token verification

Core Business Endpoints

Resource	Endpoints	Description
Packages	/api/packages	Safari package management
Bookings	/api/bookings	Booking system operations
Safari Requests	/api/safariRequests	Custom safari package requests
Users	/api/users	User account management
Staff	/api/staff	Staff management system
Vehicles	/api/vehicles	Fleet management
Reviews	/api/reviews	Customer review system
Donations	/api/donations	Wildlife conservation donations
Gallery	/api/gallery	Photo gallery and bidding management
Gallery Purchases	/api/galleryPurchase	Photo purchase and delivery system
Bidding Admin	/api/biddingAdmin	Real-time bidding administration
Weather	/api/weather	Weather data integration

Admin & Management

Resource	Endpoints	Description
Attendance	/api/attendance	Staff attendance tracking
Payroll	/api/payroll	Payroll management
Notifications	/api/notifications	System notifications
Contact Messages	/api/contactMessages	Customer inquiry management

📖 For complete API documentation with request/response examples, see the PROJECT_STRUCTURE_DOCUMENTATION.md

---

🌍 Multilingual Support

WildLanka supports three languages to serve the diverse Sri Lankan community:

Language	Code	Coverage
English	en	Complete UI, API responses, documentation
සිංහල (Sinhala)	si	Complete UI, chatbot, customer-facing content
தமிழ் (Tamil)	ta	Complete UI, chatbot, customer-facing content

Implementation Features:

• 🔄 Dynamic Language Switching: Real-time language changes
• 🤖 AI Chatbot: Trilingual support with context awareness
• 📱 Responsive Text: Proper text rendering for all scripts
• 🎯 Cultural Adaptation: Region-specific date/time formats
• 📊 Admin Dashboard: Multi-language content management

---

� Security

Environment Variables & API Keys

This project uses sensitive API keys and credentials that must NOT be committed to GitHub.

Important Files:

• 🚫 .env files are git-ignored and contain your actual secrets
• ✅ .env.example files are templates showing required variables
• 📖 SECURITY.md - Complete security guidelines and setup instructions

Setup Process:

1. Copy .env.example to .env in both backend/ and frontend/ directories
2. Fill in your own API keys and credentials
3. Never commit or share your .env files

Required Services:

• MongoDB: Database connection (MongoDB Atlas)
• ImgBB: Image hosting service (ImgBB)
• Stripe: Payment processing (Stripe Dashboard)
• OpenWeatherMap: Weather data API (OpenWeatherMap)

🔒 For detailed security guidelines, key management, and what to do if keys are exposed, see SECURITY.md

---

�👥 Contributors

This project is developed and maintained by a dedicated team of five developers who contributed equally to all aspects of the system, led by Osanda Madugalle:

Osanda Madugalle 🎯 Project Leader 💻 Full-Stack Developer	Kalana Jayawardana 💻 Full-Stack Developer	Ravindu Bandara 💻 Full-Stack Developer
Malinda Samarasekara 💻 Full-Stack Developer	Ikshuka Malhengoda 💻 Full-Stack Developer

Equal Contribution: All team members worked collaboratively across frontend, backend, testing, and documentation. See detailed contributions in CONTRIBUTORS

---

� License

This project is protected under a custom license.

⚖️ Usage Terms:
❌ No forking or downloading without permission
❌ No commercial use without authorization  
❌ No code reuse without written consent
✅ Public viewing for educational purposes
✅ Academic reference with proper citation

Please refer to the LICENSE file for detailed terms and conditions.

Copyright © 2024 WildLanka Development Team. All rights reserved.

---

📞 Support

Getting Help

• 📖 Documentation: Check PROJECT_STRUCTURE_DOCUMENTATION.md
• 🐛 Bug Reports: Use GitHub Issues
• 💡 Feature Requests: Submit via GitHub Issues with enhancement label
• 📧 Direct Contact: Reach out to any team member via GitHub profiles

Development Support

• 🔧 Setup Issues: Check environment configuration
• 🚀 Deployment: Follow the getting started guide
• 🔄 Updates: Watch repository for latest changes
• 🤝 Collaboration: Contact team for partnership opportunities

---

🐾 WildLanka - Protecting Wildlife, Empowering Tourism 🌿

Made with ❤️ by the WildLanka Team | Sri Lanka 🇱🇰