README.md

Smart Attendance System

An asynchronous, AI-powered multi-layered attendance verification system designed to eliminate buddy punching, proxy check-ins, and attendance fraud. The project consists of a FastAPI backend using TensorFlow/DeepFace, a Next.js web application for administration/teachers, and a Flutter mobile application for students.

---

🚀 Key Features

1. Multi-Layered AI Verification

To mark attendance, the student uploads a live selfie which undergoes three independent stages of verification:

• Facial Recognition: Matches the student's live face embedding against their registered template using the FaceNet model (via DeepFace) with 128-dimensional vector embeddings stored in PostgreSQL using pgvector.
• Liveness Detection: Employs a custom-trained MobileNetV2 model to check if the submission is a real person, preventing spoofing attempts using photos, videos, or masks.
• Background Validation: Utilizes a custom MobileNetV1 model to verify that the background of the image matches the expected classroom environment.

2. Location & Geofencing

• Verifies student's physical location against active class coordinates.
• Teachers define geofenced regions (latitude, longitude, and radius in meters).
• Submissions outside the geofence boundary are automatically flagged or rejected.

3. Device Binding (Anti-Proxy)

• Restricts each student account to a single mobile device.
• Generates and binds a unique hardware UUID (device_uuid) on first login.
• Students must submit a Device Change Request to be approved by administrators/teachers before they can log in on a new device.

4. Real-time Communication & Notifications

• Websocket-based live connection to push real-time attendance updates to teachers' dashboards.
• Firebase Cloud Messaging (FCM) integration to dispatch push notifications for new sessions, reminders, and leave status updates.

5. Gamification Suite

• Encourages student attendance through engagement features including current/highest streaks, levels, leaderboards, and point systems.

---

🛠️ Technology Stack & Versions

Layer	Technology	Version / Specification	Key Libraries
Backend	Python 3.11 / FastAPI	0.115.6	Prisma ORM, TensorFlow 2.15.0, DeepFace 0.0.93, OpenCV 4.10.0, Redis 5.2.1
Frontend	Next.js (React 19)	16.2.6	Tailwind CSS 4.x, Recharts 3.8.1, Zustand 5.0.13, Leaflet Map 1.9.4
Mobile	Flutter SDK	^3.8.0	Riverpod ^2.6.1, Dio ^5.7.0, Geolocator ^13.0.2, Hive ^2.2.3
Database	PostgreSQL	15+	pgvector extension enabled for biometric representations

---

📂 Project Structure

.
├── backend/            # FastAPI python application, database migrations, and AI models
│   ├── app/            # Application source code (api, core, db, middleware, services, etc.)
│   ├── models/         # Local folder for downloading/caching TF models
│   ├── prisma/         # Prisma schema and seeding configurations
│   └── main.py         # App entrypoint
├── frontend/           # Next.js web application for admins and teachers
│   ├── src/            # Next.js pages/components
│   └── package.json    # Frontend dependency definitions
└── mobile/             # Flutter student companion app
    ├── lib/            # Flutter implementation source code
    └── pubspec.yaml    # Flutter dependency configuration

---

⚙️ Getting Started

Prerequisites

1. Python 3.11 installed on the host system.
2. Node.js 20+ and npm installed.
3. Flutter SDK (v3.8.x+) and target development environment (Android/iOS simulator or physical device).
4. PostgreSQL database with pgvector extension enabled.
5. Redis Server running locally or accessible via network.
6. A HuggingFace token (HF_TOKEN) to download pre-trained liveness & background models.

---

1. Backend Setup

1. Navigate to the directory:

   cd backend
   

2. Configure environment variables: Create a .env file by copying the template:

   cp .env.example .env
   

   Fill in the required fields (database connection strings, Redis URL, JWT Secret, and HF token if required).

3. Install dependencies:

   pip install -r requirements.txt
   

4. Prepare the database (Prisma): Ensure your PostgreSQL service is running and has the pgvector extension enabled, then run:

   python -m prisma db push
   python -m prisma generate
   

5. Seed the database (Optional):

   python prisma/seed.py
   

6. Start the server:

   uvicorn main:app --reload --port 8000
   

   Interactive API documentation will be available at http://localhost:8000/docs.

---

2. Frontend Setup

1. Navigate to the directory:

   cd frontend
   

2. Configure environment variables: Ensure a .env.local file exists:

   NEXT_PUBLIC_API_URL=http://localhost:8000/api/v1
   

3. Install dependencies:

   npm install
   

4. Start the development server:

   npm run dev
   

   The dashboard will be running at http://localhost:3000.

---

3. Mobile Setup

1. Navigate to the directory:

   cd mobile
   

2. Get Flutter packages:

   flutter pub get
   

3. Run the application: Make sure you have an active emulator or connected device:

   flutter run
   

---

🔒 Security & Verification Parameters

The verification strictness can be controlled globally via the administrator settings page or in .env:

• Face Embedding matching threshold: Standard threshold is configured to 0.75 (cosine similarity/confidence score).
• Liveness Detection threshold: Values above 0.5 denote real face image inputs.
• Geofencing validation: Distance calculated dynamically using the Haversine formula based on student's GPS reports and active class geofence boundaries.