FaceAttend is a high-performance, hybrid attendance management solution for educational institutions. It combines a lightweight operational mobile app for real-time attendance with a comprehensive web ERP portal for management and analytics.
The system uses a triple-tier architecture separated into a robust Node.js backend, a high-precision Python FaceNet authentication service, and distinct client interfaces for faculty operations.
- Mobile Client (React Native + Expo): A streamlined, high-speed app dedicated to the "field work"—taking live attendance and viewing schedules.
- Web ERP Portal (React + Vite): The command center. Handles all administrative tasks: student registration, profile management, timetable configuration, and detailed reporting.
- Core Backend (Express + TypeScript): The central orchestration API managing authentication, web-tier logic, and database operations.
- Distributed Processing Pipeline (Redis + BullMQ): Handles high-frequency ML payload requests. Validates, deduplicates, and manages ML confidence windows natively in Redis memory.
- FaceNet Microservice (Python): A dedicated AI service for generating 512-dimensional face embeddings and performing cosine-similarity matching.
- Centralized Management: The only place for adding/editing students and managing faculty profiles.
- Remote Capture: Initiate a photo capture request from the Web Portal that instantly triggers the camera on your logged-in mobile device for wireless registration.
- Timetable Manager: Interactive drag-and-drop style interface to configure weekly schedules.
- Attendance Reconciliation: Automated background sync that verifies session counts against the latest student enrollments to ensure 100% data integrity.
- Security Console: (My Devices) Monitor active sessions, trust/untrust specific mobile devices, and force-logout suspicious connections.
- Audit Logs: Real-time surveillance tracking every login, data change, and attendance event.
- Reports & Analytics: Export professional PDF/CSV reports and view live attendance metrics.
- Focused UI: Clutter-free interface designed purely for speed and efficiency in the classroom.
- Secure Kiosk Mode: Dedicated Lock-Task/Kiosk implementation with biometric authentication (Fingerprint/FaceID) for exit, including a robust admin password fallback.
- High-Speed Frame Processing: Accelerated continuous throttled background scanning combined with dynamic JPEG payload compression.
- Smart Dashboard: Shows ongoing and upcoming classes with "One-Tap" attendance start.
- Zero-Lag Asynchrony: Pushes face buffers to an async queue (BullMQ), yielding 4ms node-response times, updating UI fully offline using realtime WebSocket broadcasts.
- Real-Time Sync: Instantly reflects timetable changes and student updates made on the Web Portal.
- Event-Driven Inference: Mobile uploads trigger BullMQ parallel workers (running 20+ concurrent threads) to communicate seamlessly with Python models.
- Multi-Embedding Profiles: Tracks a rolling set of 5+ unique face embeddings per student to handle variations in lighting, angles, and appearance changes.
- Anti-Proxy Shield: Real-time cross-verification during registration prevents duplicate or proxy student enrollments using cosine similarity benchmarks (>0.8).
- Redis Acceleration: Implements a Read-through Cache for high-frequency data (like Timetables) with automatic invalidation on updates.
- Redis Real-Time State: Buffers tracking "live attendance state", detection window cooldowns, and cryptographic hash deduplication caching directly in fast memory.
- Socket.IO Real-time Loop: AI output, UI updates, and remote trust management reflect on the mobile app within milliseconds.
- FaceNet Embeddings: State-of-the-art deep learning model for high-accuracy face verification.
web/
├── src/
│ ├── components/
│ │ ├── Dashboard.tsx # Main layout & widget orchestrator
│ │ ├── StudentManagement.tsx # Filter/Sort/Edit Students
│ │ ├── StudentRegistration.tsx # Remote Capture & Form
│ │ ├── TimetableManager.tsx # Schedule & Clash Detection
│ │ ├── AttendanceReports.tsx # PDF/CSV Logic
│ │ ├── AuditLog.tsx # Security visualizer
│ │ └── MyDevices.tsx # Hardware trust management
│ ├── api/ # Axios client
│ └── lib/ # Utilitiesclient/
├── app/
│ ├── index.tsx # Login & Auth Check
│ ├── dashboard.tsx # Status & Quick Actions
│ ├── take-attendance.tsx # Camera & Recognition Loop
│ ├── timetable.tsx # Read-only Schedule View
│ └── settings.tsx # App Preferences
├── components/
│ ├── live-attendance.tsx # Real-time Face Processing
│ └── GlobalCaptureModal.tsx # Socket-triggered cameraserver/(Node.js): Tiered REST API, BullMQ worker configuration, WebSocket emitters, and Background Sync services.facenet_service/(Python): Inference-only Flask microservice exposingPOST /api/recognize(512-dim embedding extraction via frozen InceptionResnetV1) andGET /health.redis(In-Memory Datastore): Holds JWT session sets, Read-through caches for timetables, message brokerage queues, and ML face-caching hashes.
- Node.js (v18+) & Python (v3.9+)
- MongoDB (Local or Atlas)
- Redis Server (Local or Docker)
- Expo Go app (for mobile testing)
Step 1: Start the AI Service
cd facenet_service
# Create venv if needed
pip install -r requirements.txt
python face_recognition_service.pyStep 2: Start the Backend API
cd server
npm install
cp .env.example .env # Configure environment variables
npm run devStep 3: Start the Web Portal
cd web
npm install
cp .env.example .env # Configure VITE_API_URL
npm run devStep 4: Start the Mobile App
cd client
npm install
cp .env.example .env # Configure EXPO_PUBLIC_API_URL
npx expo start- Biometric Kiosk Authorization: Hardware-level biometric escape from Kiosk/Lock-Task mode with mandatory cross-verification during setup.
- Context-Aware 2FA: Dynamic two-factor email authentication triggered only for untrusted devices or suspicious login attempts.
- Multi-Device Session Management: Set-based Redis architecture allowing concurrent active sessions on web and mobile simultaneously.
- Device Fingerprinting: Every mobile login captures device ID, model, and OS version.
- Trust Policy: Admin/Faculty must explicitly "Trust" a mobile device from the Web Portal before it can be used for taking attendance.
- Audit Trails: Real-time surjective tracking for every login, data change, and attendance event.
- JWT + Refresh Tokens: Secure session management with automatic expiration and Redis-backed invalidation.
FaceAttend — Secure, Fast, and Smart Classroom Management.