FACIAL ATTENDANCE SYSTEM - PROJECT OVERVIEW
===========================================

1. PROJECT PURPOSE & FEATURES
-----------------------------
This project is a Django-based facial attendance system that allows employees to mark their attendance and logout using face recognition. It combines Python-based recognition (insightface) for backend verification and browser-based face detection (face-api.js) for a seamless, automatic camera experience. Key features:
- User registration with face images (webcam or upload)
- Automatic attendance and logout via live camera (no button press needed)
- Recent logs and user management
- CSV export of attendance records
- Admin interface for management

2. TECHNOLOGY STACK
-------------------
- Backend: Django (Python)
- Face Recognition: insightface, onnxruntime, OpenCV
- Frontend: HTML, Bootstrap, JavaScript
- Browser Face Detection: face-api.js (TensorFlow.js)
- Database: SQLite (default, can be changed)

3. SYSTEM ARCHITECTURE (HIGH-LEVEL)
-----------------------------------
- User opens attendance/logout page → browser loads face-api.js models
- Live video stream is analyzed in-browser; when a face is detected, a frame is sent to the backend
- Backend extracts face embedding (insightface) and matches against registered users
- Attendance or logout is marked in the database if a match is found
- Logs and user management are available via web UI

4. SETUP STEPS (SUMMARY)
------------------------
- Create and activate a Python virtual environment
- Install dependencies: pip install -r requirements.txt
- Download face-api.js model weights and place in app/static/models/
- Run Django migrations: python manage.py migrate
- (Optional) Collect static files: python manage.py collectstatic
- Start the server: python manage.py runserver
- Access at http://127.0.0.1:8000/

5. ATTENDANCE & LOGOUT FLOW
---------------------------
- User stands in front of the camera on the attendance/logout page
- face-api.js detects a face in real time
- When a face is detected, a frame is captured and sent to the backend
- Backend uses insightface to extract embedding and compares with stored user embeddings
- If a match is found:
    - For attendance: marks 'login' event (if not already marked today)
    - For logout: marks 'logout' event (if not already logged out today)
- User sees confirmation or error message in the browser

6. DIRECTORY STRUCTURE (KEY FOLDERS/FILES)
------------------------------------------
- attendance/           # Django app (views, models, templates)
- app/static/models/    # face-api.js model weights (downloaded)
- app/static/js/        # Custom JS for attendance/logout
- media/                # Uploaded/captured user images
- db.sqlite3            # Default database
- requirements.txt      # Python dependencies & setup instructions
- PROJECT_OVERVIEW.txt  # This file

7. NOTES FOR DEVELOPERS
-----------------------
- To add new features, create new Django views/templates or extend JS logic
- For debugging, use browser console (frontend) and Django logs (backend)
- To support more face recognition models, add them to the backend and update registration/verification logic
- For production, use a proper WSGI/ASGI server and secure static/media file serving
- Always keep model files and static paths consistent with the documentation

For more details, see requirements.txt and README.md (if present).