Geo-Location Based Attendance Tracking System

A comprehensive Django-based web application for tracking student attendance using face recognition and geo-fencing technology. The system ensures students are physically present within designated geographic boundaries when marking attendance.

🎯 Features

Core Functionality

• Multi-Role Authentication: Support for Student, Staff, and Admin roles with different access levels
• Face Recognition: CNN-based facial verification using OpenCV and face_recognition library
• Geo-Fencing: GPS-based location verification using polygon algorithms and Google Maps API
• Real-time Dashboard: Live attendance monitoring and analytics for all user roles
• Class Management: Create, edit, and manage classes with student enrollment
• Attendance Analytics: Comprehensive reports and visualizations using Chart.js

User Roles

Student

• Register with face image capture
• View enrolled classes and schedules
• Mark attendance with face and location verification
• View attendance history
• Interactive map display showing class locations

Staff

• Staff dashboard with class overview
• Create and manage classes
• Student enrollment management
• Geo-fence creation and management using Google Maps
• Monitor attendance in real-time
• Generate attendance reports

Admin

• Full system access and user management
• System analytics and performance metrics
• Attendance analytics and reporting
• Geo-fence management across all classes
• User role assignment and permissions

🛠️ Technology Stack

Backend

• Python 3.8+ - Programming language
• Django 3.1.12 - Web framework
• Djongo 1.3.7 - MongoDB connector for Django
• PyMongo 3.11.4 - MongoDB driver
• Django REST Framework 3.11.2 - API framework
• Django CORS Headers 3.10.1 - CORS support

Database

• MongoDB - NoSQL database for flexible data storage
• GridFS - File storage system (for media files)

Face Recognition

• OpenCV 4.8.0+ - Computer vision library
• NumPy 1.24.0+ - Numerical computing
• Pillow 10.0.0+ - Image processing
• face_recognition - Face detection and recognition library

Frontend

• HTML5/CSS3 - Semantic markup and styling
• JavaScript (ES6+) - Interactive functionality
• Bootstrap 5 - Responsive UI framework
• Google Maps JavaScript API - Mapping and location services
• Chart.js - Analytics visualization

Utilities

• python-decouple 3.8+ - Environment variable management
• requests 2.31.0+ - HTTP library

📁 Project Structure

GAS/
├── attendance_system/          # Main project settings
│   ├── __init__.py
│   ├── settings.py            # Django settings with MongoDB config
│   ├── urls.py               # Main URL configuration
│   ├── wsgi.py               # WSGI configuration
│   └── asgi.py               # ASGI configuration
│
├── userview/                  # Student and general user app
│   ├── __init__.py
│   ├── apps.py
│   ├── models.py             # User, Class, GeoFence, Attendance models
│   ├── forms.py              # Registration and login forms
│   ├── views.py              # Authentication and student views
│   ├── urls.py               # App URL configuration
│   ├── admin.py              # Django admin configuration
│   └── migrations/           # Database migrations
│
├── adminview/                 # Staff and admin app
│   ├── __init__.py
│   ├── apps.py
│   ├── forms.py              # Class and geo-fence management forms
│   ├── views.py              # Staff and admin views
│   └── urls.py               # App URL configuration
│
├── templates/                 # HTML templates
│   ├── base.html             # Base template
│   ├── userview/             # User templates
│   │   ├── login.html
│   │   ├── register.html
│   │   └── student_home.html
│   └── adminview/            # Admin templates
│       ├── staff_home.html
│       ├── admin_dashboard.html
│       ├── class_list.html
│       ├── class_form.html
│       ├── geofence_list.html
│       ├── geofence_form.html
│       ├── class_enrollment.html
│       └── attendance_analytics.html
│
├── static/                    # Static files (CSS, JS, images)
├── media/                     # User-uploaded files
│   ├── profiles/             # User profile pictures
│   └── faces/                # Face recognition data
│
├── TEST/                      # Test files and documentation
│   ├── README.md
│   ├── PROJECT_SCHEMA.md
│   ├── test_basic_setup.py
│   ├── test_face_recognition.py
│   ├── test_google_maps.py
│   └── test_maps.html
│
├── requirements.txt           # Python dependencies
├── manage.py                 # Django management script
├── config.env.example        # Environment variables template
├── PROJECT_ARCHITECTURE.md   # Detailed architecture documentation
└── README.md                 # This file

🚀 Installation and Setup

Prerequisites

• Python 3.8 or higher
• MongoDB 4.4 or higher (running locally or remote)
• Google Maps API key (for geo-fencing functionality)
• Git (for cloning the repository)

Step 1: Clone the Repository

git clone <repository-url>
cd GAS

Step 2: Create Virtual Environment

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Windows
venv\Scripts\activate

# On macOS/Linux
source venv/bin/activate

Step 3: Install Dependencies

pip install -r requirements.txt

Note: If you encounter issues installing dlib (required for face_recognition), you may need to install it separately:

# On Windows (using conda)
conda install -c conda-forge dlib

# On macOS/Linux
# Install cmake first
sudo apt-get install cmake  # Ubuntu/Debian
brew install cmake          # macOS

pip install dlib

Step 4: MongoDB Setup

1. Install MongoDB on your system:

   • Windows: Download from MongoDB Download Center
   • macOS: brew install mongodb-community
   • Linux: Follow MongoDB Installation Guide

2. Start MongoDB service:

   # Windows
   net start MongoDB
   
   # macOS/Linux
   sudo systemctl start mongod
   # or
   mongod

3. Verify MongoDB is running:

   mongosh
   # or
   mongo

Step 5: Environment Configuration

1. Copy the example environment file:

   cp config.env.example .env

2. Edit .env file with your configuration:

   # Django Settings
   SECRET_KEY=your-secret-key-here-change-this-in-production
   DEBUG=True
   
   # Database Settings
   DB_NAME=attendance_system
   DB_HOST=localhost
   DB_PORT=27017
   DB_USERNAME=
   DB_PASSWORD=
   
   # Google Maps API
   GOOGLE_MAPS_API_KEY=your-google-maps-api-key-here
   
   # Face Recognition Configuration
   FACE_RECOGNITION_TOLERANCE=0.6
   FACE_RECOGNITION_MODEL=hog
   GEO_FENCING_BUFFER=10

3. Get Google Maps API Key:

   • Go to Google Cloud Console
   • Create a new project or select existing one
   • Enable "Maps JavaScript API" and "Geocoding API"
   • Create credentials (API Key)
   • Add the API key to your .env file

Step 6: Database Migrations

# Create migrations
python manage.py makemigrations

# Apply migrations
python manage.py migrate

Step 7: Create Superuser

python manage.py createsuperuser

Follow the prompts to create an admin user.

Step 8: Collect Static Files

python manage.py collectstatic --noinput

Step 9: Run the Development Server

python manage.py runserver

The application will be available at http://localhost:8000

📖 Usage Guide

Student Workflow

1. Registration:

   • Navigate to the registration page
   • Fill in username, email, password, and role (student)
   • Allow camera access when prompted
   • Capture face image for face recognition
   • Submit registration

2. Login:

   • Enter username and password
   • Access student dashboard

3. Mark Attendance:

   • View enrolled classes on the dashboard
   • Select a class to mark attendance
   • Enable camera for face recognition
   • Allow location access for GPS verification
   • Click "Mark Attendance" button
   • System verifies face and location
   • Attendance is recorded if both checks pass

4. View Attendance History:

   • Check attendance records on the dashboard
   • View attendance statistics

Staff Workflow

1. Login: Access staff dashboard with staff/admin credentials

2. Class Management:

   • Create new classes
   • Edit existing classes
   • Delete classes
   • View all classes

3. Student Enrollment:

   • Select a class
   • Add/remove students from enrollment
   • View enrolled students

4. Geo-fence Management:

   • Create geo-fences using Google Maps drawing tools
   • Draw polygon boundaries on the map
   • Assign geo-fences to classes
   • Edit or delete geo-fences

5. Attendance Monitoring:

   • View real-time attendance for classes
   • Monitor student attendance status
   • Generate attendance reports

Admin Workflow

1. Login: Access admin dashboard

2. User Management:

   • View all users
   • Create/edit user accounts
   • Assign roles (student, staff, admin)
   • Manage user permissions

3. System Analytics:

   • View comprehensive attendance analytics
   • Monitor system performance
   • Generate reports

4. Geo-fence Management:

   • Manage all geo-fences across the system
   • View geo-fence usage statistics

🔌 API Endpoints

Authentication

• GET / - Login page
• POST /login/ - User login
• POST /register/ - User registration
• GET /logout/ - User logout

Student Endpoints

• GET /student-home/ - Student dashboard
• POST /mark-attendance/<class_id>/ - Mark attendance for a class
• GET /profile/ - User profile (if implemented)

Staff/Admin Endpoints

• GET /adminview/staff-home/ - Staff dashboard
• GET /adminview/admin-dashboard/ - Admin dashboard
• GET /adminview/classes/ - List all classes
• POST /adminview/classes/create/ - Create new class
• GET /adminview/classes/<id>/update/ - Edit class
• POST /adminview/classes/<id>/delete/ - Delete class
• GET /adminview/classes/<id>/enrollment/ - Manage class enrollment
• GET /adminview/geofences/ - List all geo-fences
• POST /adminview/geofences/create/ - Create new geo-fence
• GET /adminview/geofences/<id>/update/ - Edit geo-fence
• POST /adminview/geofences/<id>/delete/ - Delete geo-fence
• GET /adminview/attendance-analytics/ - Attendance analytics

🔐 Security Features

• CSRF Protection: Built-in Django CSRF tokens
• Session Management: Secure session handling with configurable timeout
• Input Validation: Form validation and data sanitization
• Role-based Access Control: Different permissions for different user roles
• Secure Authentication: Django's built-in authentication system
• Password Validation: Strong password requirements
• CORS Configuration: Configurable cross-origin resource sharing

🧪 Testing

The project includes test files in the TEST/ directory:

# Run basic setup test
python TEST/test_basic_setup.py

# Test face recognition
python TEST/test_face_recognition.py

# Test Google Maps integration
python TEST/test_google_maps.py

🐛 Troubleshooting

Common Issues

1. Face Recognition Not Working

   • Ensure OpenCV and dlib are properly installed
   • Check camera permissions in browser
   • Verify face image quality during registration
   • Ensure good lighting conditions

2. Location Not Detected

   • Enable location services in browser
   • Check HTTPS requirement for geolocation (some browsers require HTTPS)
   • Verify GPS permissions
   • Test location access in browser console

3. MongoDB Connection Issues

   • Ensure MongoDB service is running
   • Check connection string in .env file
   • Verify database credentials
   • Check MongoDB logs for errors

4. Google Maps Not Loading

   • Check API key configuration in .env
   • Verify API key has proper permissions (Maps JavaScript API enabled)
   • Check billing status for Google Cloud project
   • Verify API key restrictions (if any)

5. Djongo Errors

   • Ensure MongoDB is running
   • Check database name matches in settings
   • Some complex Django ORM queries may not work with djongo - use raw queries if needed

6. Static Files Not Loading

   • Run python manage.py collectstatic
   • Check STATIC_URL and STATIC_ROOT in settings
   • Verify static files directory exists

Debug Mode

Set DEBUG=True in .env file for detailed error messages and debugging information. Never use DEBUG=True in production!

📊 Database Schema

User Model

• Extends Django's AbstractUser
• Fields: username, email, password, role, department_id, face_data (JSON)
• Roles: student, staff, admin

Class Model

• Fields: name, staff (ForeignKey), geolocation (ForeignKey to GeoFence), students (ManyToMany)
• Relationships: One staff member, many students, one geo-fence

GeoFence Model

• Fields: name, coordinates (JSON array of {lat, lng}), created_at, updated_at
• Methods: is_point_inside(lat, lng) - Point-in-polygon algorithm

Attendance Model

• Fields: student, class_instance, timestamp, is_present, geolocation, face_verified, location_verified
• Unique constraint: student + class_instance + timestamp

🚀 Deployment

Production Considerations

1. Environment Variables: Use secure environment variables, never commit .env file
2. SECRET_KEY: Generate a new secret key for production
3. DEBUG: Set DEBUG=False in production
4. ALLOWED_HOSTS: Configure properly in settings
5. Database: Use production MongoDB instance or cluster
6. Static Files: Configure proper static file serving (Nginx, AWS S3, etc.)
7. Media Files: Use cloud storage (AWS S3, Google Cloud Storage)
8. HTTPS: Enable HTTPS for geolocation API to work properly
9. Security: Review Django security checklist
10. Monitoring: Set up logging and monitoring

Recommended Production Stack

• Web Server: Nginx
• Application Server: Gunicorn or uWSGI
• Database: MongoDB Atlas (cloud) or self-hosted MongoDB cluster
• File Storage: AWS S3 or Google Cloud Storage
• Process Manager: Supervisor or systemd
• Reverse Proxy: Nginx

📝 Configuration

Face Recognition Settings

• FACE_RECOGNITION_TOLERANCE: Lower values = stricter matching (default: 0.6)
• FACE_RECOGNITION_MODEL: 'hog' or 'cnn' (default: 'hog')

Geo-fencing Settings

• GEO_FENCING_BUFFER: Buffer zone in meters for GPS accuracy (default: 10)

Session Settings

• SESSION_COOKIE_AGE: Session timeout in seconds (default: 3600 = 1 hour)
• SESSION_EXPIRE_AT_BROWSER_CLOSE: Session expires when browser closes

🤝 Contributing

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

📄 License

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

📞 Support

For support and questions:

• Create an issue in the repository
• Contact the development team
• Check the documentation in PROJECT_ARCHITECTURE.md and TEST/PROJECT_SCHEMA.md

🔮 Future Enhancements

• Mobile App: Native mobile applications for iOS and Android
• Real-time Notifications: Push notifications for attendance updates
• Advanced Analytics: Machine learning insights and predictions
• Multi-language Support: Internationalization (i18n)
• API Documentation: Swagger/OpenAPI documentation
• Comprehensive Testing Suite: Unit tests, integration tests
• Biometric Integration: Additional biometric verification methods
• Offline Mode: Support for offline attendance marking
• Export Features: PDF/Excel export for reports
• Email Notifications: Automated email alerts for attendance

📚 Additional Documentation

• Architecture Details: See PROJECT_ARCHITECTURE.md
• Schema Documentation: See TEST/PROJECT_SCHEMA.md
• Test Documentation: See TEST/README.md

---

Note: This is a development version. Ensure all security measures are in place before deploying to production.