# BIOMETRIC ATTENDENCE MANAGEMENT SYSTEM

A simple, self-hosted attendance management system built with a Next.js frontend, Convex for backend/data, and facial recognition for enrollment and verification (webcam-based). This repository contains the code and resources to run a local attendance server (web), enroll users' faces, and generate attendance reports.

Table of contents
- About
- Key features
- Tech stack
- Quick start
- Configuration
- Usage
- Troubleshooting
- Project structure
- Tests
- Contributing
- License
- Contact

About
-----
This project provides an attendance management solution using biometric facial recognition. It is designed for small organizations (schools, offices, clubs) that want reliable, tamper-resistant attendance logging without fingerprint hardware — everything runs from a browser (webcam) and a Convex backend.

Key features
------------
- Face enrollment (capture face data via webcam)
- Face verification for check-in / check-out (live webcam)
- User management (create, edit, delete)
- Attendance logs with timestamps stored in Convex
- Exportable attendance reports (CSV / Excel / PDF)
- Role-based access (Admin / Staff / Student) — optional depending on implementation
- Local-first flow with Convex as the backend datastore and serverless functions

Tech stack
----------
- Frontend: Next.js (React)
- Backend / Database: Convex (functions + document store)
- Facial recognition: browser-based models (e.g., face-api.js / TensorFlow.js or an external provider if configured)
- Authentication: NextAuth or a custom auth provider (project-specific)
- Database for exports: CSV/Excel generation libraries on the server or client
- Other tools: Node.js (v18+ recommended), npm or yarn, optional Docker for deployment

Quick start
-----------
1. Clone the repository
   ```bash
   git clone https://github.com/bos-com/BIOMETRIC-ATTENDENCE-MANAGEMENT-SYSTEM.git
   cd BIOMETRIC-ATTENDENCE-MANAGEMENT-SYSTEM

2. Install dependencies

   npm install
   # or
   yarn

3. Configure environment variables

   • Copy .env.example to .env.local (or create .env.local) and set the values:
     • NEXT_PUBLIC_CONVEX_URL: your Convex deployment URL (if using hosted Convex)
     • CONVEX_API_KEY (if your setup requires a key for server-side usage)
     • NEXTAUTH_URL and any auth provider secrets (if applicable)
     • FACE_MODEL_PATH (optional) if your app loads models from a custom path or CDN

   Example .env.local:

   NEXT_PUBLIC_CONVEX_URL=https://your-convex-url.convex.cloud
   NEXT_PUBLIC_FACE_MODEL_URL=/models
   NEXTAUTH_URL=http://localhost:3000
   

4. Run Convex locally (development)

   • If you have Convex functions in the repo and want to run locally:

   npx convex dev

   • To deploy Convex:

   npx convex deploy

5. Start the Next.js app

   npm run dev
   # or
   yarn dev

   Open http://localhost:3000

Configuration

• .env.local / Vercel environment variables:

  • NEXT_PUBLIC_CONVEX_URL — Convex deployment URL
  • CONVEX_API_KEY — (optional) server-side Convex key if using server functions that require it
  • NEXTAUTH_URL — app URL for NextAuth (if used)
  • Any provider-specific keys for optional external face-recognition services

• Camera / permissions:

  • The app requires camera access (getUserMedia). Make sure the browser has permission to use the webcam and that HTTPS is used in production.

Facial recognition details

• This project uses browser-based facial recognition (no physical fingerprint devices).
• Typical implementations use face-api.js (built on TensorFlow.js) or a lightweight face-detection model (e.g., MediaPipe) to:
  • Detect faces in the webcam feed
  • Compute face descriptors/embeddings for enrollment
  • Compare embeddings to match users at check-in
• If you prefer a cloud provider (AWS Rekognition, Azure Face API, etc.), you can swap the client-side logic to call your provider; update env variables and server-side functions accordingly.

Usage

Typical workflow:

1. Admin signs in and enrolls users by capturing face data (one or more captures recommended).
2. The system stores face embeddings in Convex along with user profile data.
3. At check-in, users present their face to the webcam; the app computes an embedding and searches for a matching user.
4. Matches are logged as attendance entries (timestamp, user id).
5. Admins generate reports (daily, monthly, per-user) and export them as CSV/Excel.

Troubleshooting

• If camera is not accessible:

  • Ensure your browser has permission to use the camera.
  • Check that no other app is using the camera.
  • On insecure origins (HTTP), some browsers block getUserMedia — use HTTPS in production or localhost for development.

• If face matching is failing:

  • Re-enroll the user ensuring consistent lighting and framing.
  • Increase the number of enrollment captures if supported.
  • Tune the matching threshold in the app settings (if exposed).

• Convex issues:

  • Ensure NEXT_PUBLIC_CONVEX_URL and any Convex secrets are set correctly.
  • Run npx convex dev to test the backend locally.

Project structure (updated for Next.js + Convex)

• /app or /src - Next.js application code (pages/app router or pages directory)
• /components - React components (camera, enrollment modal, attendance UI)
• /convex - Convex functions and schema (if included)
• /public/models - face model files (if bundling face-api.js models locally)
• /public - static assets
• package.json - dependencies and scripts
• README.md - this file

Tests

If tests exist, run them with:

npm test
# or
yarn test

Consider adding tests for:

• Face-enrollment flow (integration / UI)
• Matching logic (unit tests for embedding comparison)
• API/Convex function behavior

Contributing

Contributions are welcome. Suggested process:

1. Fork the repository
2. Create a feature branch: git checkout -b feat/your-feature
3. Commit your changes with clear messages
4. Push and open a Pull Request explaining the change
5. Add tests for new functionality

License

This project is available under the MIT License. Replace with the actual license if different.

Contact

Maintainer: (please add maintainer name and contact email or GitHub handle)

Acknowledgements

• Convex (backend + data platform)
• Next.js and React ecosystem
• face-api.js / TensorFlow.js or other face-detection/recognition libraries used