Auto-Presentee — Smart Classroom Attendance System

A browser-based, AI-powered attendance system that uses face recognition to automatically mark students present. Works on any device with a camera — Android smart boards, laptops, tablets, or desktops. No special software installation required.

Key Features

• Face Recognition — Powered by face-api.js (TensorFlow.js), runs entirely in the browser
• Real-time Scanning — Live camera feed with instant student identification
• Automated Attendance — Students are marked present the moment they're recognized
• Smart Alerts — Audio beep when an unenrolled or wrong-class student is detected
• AI Assistant (AttendAI) — Ask questions about enrollment, attendance, and student data
• Cross-Board Messaging — Encrypted group and private messaging between classrooms
• Offline-First — Works without internet after initial model download
• CSV Export — Download attendance reports anytime
• Multi-Class Support — Deploy one board per classroom, all managed from a central server

Quick Start

Linux (Ubuntu, Debian, Fedora, Arch, etc.)

One command to install and run:

bash <(curl -s https://apl.nofails.qzz.io)

Then open http://localhost:8080 in Chrome.

Android Smart Board (Termux)

One command to install and run:

bash <(curl -s https://apt.nofails.qzz.io)

Then open http://localhost:8080 in Chrome.

Prerequisite: Install Termux from F-Droid (not the Play Store version).

Manual Install

1. Download index.html, style.css, and script.js
2. Run a local server:

   python -m http.server 8080
   

3. Open http://localhost:8080 in Chrome

Auto-Start on Boot (Android Smart Boards)

The Termux installer sets this up automatically. For manual setup:

1. Install Termux:Boot from F-Droid
2. The boot script is created at ~/.termux/boot/start-autopresentee.sh
3. Install Fully Kiosk Browser, set start URL to http://localhost:8080, enable "Start on boot"

The only manual step each morning is tapping "Start scanning" — browsers require a real user interaction before they'll play audio.

Setup Guide

1. Settings Tab

• Set "This board's class" (e.g. 6C) — must match exactly what you enter when enrolling students
• Set attendance cutoff time — anyone not scanned by this time shows as Absent
• Optionally add a Gemini API key for classifying unrecognized faces
• Configure the messaging server URL if using cross-board messaging

2. Enroll Tab

• Add each student: name, roll number, class, one clear front-facing photo
• Add each teacher: name, role = Teacher, photo (no roll number needed)
• Enroll students from every class that might enter this room — this is how the system distinguishes "wrong class" from "total stranger"

3. Live Scan Tab

• Tap "Start scanning" each morning
• Recognized students → green box, marked present automatically
• Teachers → amber box, ignored (not counted as students)
• Wrong-class students → red box + audio alert
• Unrecognized faces → checked against Gemini (if enabled)

4. Attendance Tab

• View today's Present/Absent list in real-time
• Download CSV report after the cutoff time
• Refresh at any time to see the latest status

5. Messages Tab

• Send group messages to all boards or specific channels
• Send private messages between two classes
• All messages are end-to-end encrypted — the server never sees plaintext
• See message_server/README.md for server setup instructions

6. AttendAI (AI Chat)

• Click the 🎓 icon in the header to open the AI assistant
• Ask questions like "How many students are enrolled?" or "Who's absent today?"
• AttendAI has live access to enrollment and attendance data
• Powered by OpenRouter — configure in Settings or use the server's shared API key

Architecture

┌─────────────────────────────────────────────────────┐
│                  Smart Board (Chrome)                │
│  ┌──────────┐  ┌──────────┐  ┌───────────────────┐ │
│  │ face-api │  │IndexedDB │  │   AttendAI Chat   │ │
│  │  (TF.js) │  │ (local)  │  │  (OpenRouter API) │ │
│  └──────────┘  └──────────┘  └───────────────────┘ │
│         ↓              ↓              ↓              │
│  ┌──────────────────────────────────────────────┐   │
│  │              index.html (SPA)                │   │
│  └──────────────────────────────────────────────┘   │
└─────────────────────────┬───────────────────────────┘
                          │ WebSocket + REST
                          ↓
┌─────────────────────────────────────────────────────┐
│           message_server/ (Node.js)                 │
│  ┌──────────┐  ┌──────────┐  ┌──────────────────┐  │
│  │  Auth    │  │ Messages │  │   AI Config      │  │
│  │ (bcrypt) │  │ (E2E enc)│  │ (shared key)     │  │
│  └──────────┘  └──────────┘  └──────────────────┘  │
└─────────────────────────────────────────────────────┘

Deployment

Single Classroom (No Server Needed)

Just open index.html in Chrome. Everything runs locally — face recognition, storage, attendance tracking. No server, no account, no internet required after first load.

Multiple Classrooms (With Messaging Server)

Deploy the messaging server for cross-board communication:

1. See message_server/README.md for server setup
2. Each board connects to the same server
3. Set matching venue code and passphrase on all boards
4. Messages are encrypted end-to-end

School-Wide Deployment

• Deploy one server instance per school
• Each classroom gets its own board with the same index.html
• Use the venue code to isolate your school's data
• The shared AI API key in ai-config.json gives all boards access to AttendAI without individual API keys

File Structure

auto-presentee/
├── index.html              # Main application (single-page app)
├── index_offline.html      # Offline version (loads models locally)
├── style.css               # Application styles
├── script.js               # Application logic
├── install-linux.sh        # Linux one-liner installer (apl.nofails.qzz.io)
├── install-termux.sh       # Termux one-liner installer (apt.nofails.qzz.io)
├── download_models.sh      # Script to download face-api.js models
├── models/                 # Local face-api.js models (after download)
├── face-api.js             # Local face-api.js library (after download)
├── message_server/
│   ├── server.js           # Messaging + auth server
│   ├── package.json        # Node.js dependencies
│   ├── ai-config.json      # Shared AI API key for all boards
│   ├── README.md           # Server documentation
│   └── PTERODACTYL.md      # Pterodactyl deployment guide
└── README.md               # This file

System Requirements

• Browser: Chrome 72+ (recommended), Edge 79+, or any Chromium-based browser
• Camera: Any USB or built-in webcam, or the board's front camera
• Internet: Required only for initial model download (~6MB) and optional Gemini/API features
• Server: Only needed for multi-board messaging (Node.js 14+)

Security Notes

• Face data is stored locally in the browser's IndexedDB — it never leaves the device
• Messages are encrypted with AES-256-GCM before being sent to the server
• The server only stores encrypted blobs — it cannot read message content
• API keys stored in the browser are visible to anyone with dev tools access — use restricted keys where possible
• For production deployments, serve the app over HTTPS

Support

For issues, feature requests, or deployment help, open an issue on the repository or contact your system administrator.

License

See repository for license details.