A browser-based attendance system powered by face recognition, built with Next.js, TensorFlow.js, and Cloudinary. Students register their faces and mark attendance with no login, while teachers and admins manage classes, students, and training images.
- Overview
- Features
- Tech Stack
- System Architecture
- Roles & Permissions
- Database Schema
- Installation
- Environment Variables
- Development Guide
- Project Structure
- Core Flows
- Model Training
- Security
- MVP Scope
- Roadmap
- License
FRAMS is a minimal yet functional face-recognition attendance platform. It focuses on a seamless student experience and efficient class management for teachers and admins.
- Students — register face + mark attendance (no login)
- Teachers — create classes, add students, start attendance sessions
- Admins — manage students, images, and teachers
- Register face via webcam (
/student/face) - Captures 3–5 images/sec for 5 seconds (10–20 images total)
- Mark attendance via public attendance link (no login required)
- Face matched using TensorFlow.js model
- Login via BetterAuth
- Create/manage classes
- Add students to classes
- Start attendance sessions
- Generate unique attendance session links
- View attendance logs
- Login via BetterAuth
- Manage student records
- Link Cloudinary image URLs to students
- Manage teachers
- Prepare training dataset
| Layer | Technologies |
|---|---|
| Frontend | Next.js 16, Tailwind CSS v4, Shadcn/ui |
| Backend | Next.js App Router + Server Actions |
| Database | Neon PostgreSQL + Drizzle ORM |
| Auth | BetterAuth (teacher/admin only) |
| Storage | Cloudinary |
| Face Recognition | TensorFlow.js |
| Webcam | Browser getUserMedia |
- UI rendered using App Router and shadcn/ui components
- Server Actions for attendance marking & face uploads
- Internal API handlers for Cloudinary uploads, attendance saving, class creation
- Students, Teachers, Classes, Class_Students
- Student_Faces storing image URLs
- Attendance logs with timestamps
- Trained Model
- Model exported for TensorFlow.js
- Loaded in-browser during attendance
- Live webcam feed processed
- Predictions mapped to student ID
- Attendance saved securely
- Register face
- Mark attendance
- No authentication
- Login required
- Create/manage classes
- Start sessions
- View attendance data
- Login required
- View/edit all student and teacher records
- Manage training images
- Manage classes
git clone https://github.com/whilmarbitoco/frams.git
cd framsnpm installnpm run neon:migratenpm run devCreate .env.local:
DATABASE_URL=
BETTERAUTH_SECRET=
BETTERAUTH_URL=
CLOUDINARY_CLOUD_NAME=
CLOUDINARY_API_KEY=
CLOUDINARY_API_SECRET=
NEXT_PUBLIC_TEACHABLE_MODEL_URL=
- Capture 3–5 frames/sec using webcam
- Upload frames to Cloudinary
- Store image URLs in DB
- Associate images to student record
- Teacher starts session → generates session URL
- Students open link
- Model identifies face
- If matched & student belongs to class → mark attendance
- Use BetterAuth session
- All class/student operations validated server-side
app/
student/
face/ # Student face registration
attendance/ # Attendance session
teacher/
classes/ # Teacher class dashboard
class/[id]/ # Class details, student list
attendance/[id]/ # Start attendance session
admin/
students/ # Manage students
images/ # Link images for training
teachers/ # Manage teachers
components/
ui/ # shadcn/ui wrapped components
db/
schema.ts # Drizzle schema
index.ts # DB connection
handlers/
uploads/ # Cloudinary upload endpoints
attendance/ # Attendance API handlers
lib/
cloudinary.ts # Cloudinary utilities
recognition.ts # TF.js helpers
actions/
attendance.ts # Server Action for marking attendance
upload.ts # Server Action for uploading frames
hooks/
useWebcam.ts # Webcam helper hook
public/
model/ # Exported model
- Enter student ID
- Capture ~20 frames
- Upload to Cloudinary
- Store URLs in DB
- Admin later maps the images to the model dataset
- Teacher selects class
- Clicks “Start Session”
- System generates session link
- Students scan/open the link
- TF.js loads model
- Webcam runs continuously
- Model predicts label (student ID)
- If confidence ≥ 85% → mark attendance in DB
Admin downloads Cloudinary images for each student and places them into class folders:
dataset/
student_001/
student_002/
...
- Upload dataset
- Train model
- Export model to TensorFlow.js format
- Place model in
public/model/ - Update env variable:
NEXT_PUBLIC_TEACHABLE_MODEL_URL=/tm-model/model.json
- No login required
- Public routes rate-limited
- Student IDs validated
- BetterAuth protected
- Role-based access
- Images stored securely on Cloudinary
- No raw face embeddings stored server-side
- All face recognition done client-side
✔ Student face registration ✔ Teacher class creation ✔ Teacher session generation ✔ Attendance marking via TF.js ✔ Admin student/image management ✔ Cloudinary + Neon integration
| Feature | Status |
|---|---|
| Multi-face detection | Planned |
| Mobile PWA | Planned |
| Automatic model retraining | Planned |
| Real-time dashboard | Planned |
| Kiosk mode for classroom use | Planned |
| Offline queue for poor internet | Planned |
MIT License (or update to your preferred license)