🛡️ Sentry

AI-Powered Face Recognition Attendance System

Sentry is a full-stack web application that automates classroom attendance using YOLO object detection and ArcFace facial recognition. Teachers upload a single photograph of their classroom, and the system identifies every student present — no manual roll calls required.

Features · Architecture · Quick Start · API Reference · Project Structure

✨ Features

🎯 Core

Feature	Description
AI Attendance	Upload a classroom photo → YOLO detects faces → ArcFace identifies students → attendance is auto-recorded
Real-Time Updates	Socket.IO pushes live notifications so dashboards refresh instantly
Role-Based Access	Separate dashboards and permissions for students and teachers
Appeal System	Students can appeal incorrect attendance marks; teachers approve or reject with notes

👨‍🏫 Teacher Portal

Class Management — Create, delete, and manage courses with schedules and semesters
Student Roster — Add or remove students from classes by student ID
Attendance Analytics — Per-class and per-student attendance statistics with at-risk detection (< 75%)
Session History — View every attendance session with recognized faces and confidence scores
Announcements — Post and manage class announcements
Appeal Resolution — Review, approve, or reject student attendance appeals

🎓 Student Portal

Dashboard — Overview of enrollment, attendance rates, and upcoming classes
Course View — Browse enrolled courses in grid or list layout
Attendance Summary — Detailed attendance history per course with status breakdowns
Join/Leave Classes — Self-enroll into classes using class codes
Submit Appeals — Contest absent marks with a reason (one appeal per record)

🏗 Architecture

┌──────────────────────────────────────────────────────────────┐
│                        Frontend                              │
│              React 19 · Vite 8 · Tailwind CSS 4              │
│         Axios · React Router · Socket.IO Client              │
├──────────────────────────────────────────────────────────────┤
│                     REST API + WebSocket                     │
├──────────────────────────────────────────────────────────────┤
│                        Backend                               │
│           Express.js · Mongoose · JWT · Socket.IO            │
│             Helmet · Multer · express-validator              │
├──────────────────────────────────────────────────────────────┤
│                      Data Layer                              │
│                    MongoDB Atlas                             │
├──────────────────────────────────────────────────────────────┤
│                  AI Recognition Service                      │
│            YOLO (Detection) + ArcFace (Recognition)          │
│                  External FastAPI / Modal                     │
└──────────────────────────────────────────────────────────────┘

How Attendance Works

Teacher uploads photo
        │
        ▼
  Image saved to /uploads
        │
        ▼
  Sent to YOLO + ArcFace API ──► Detects & identifies faces
        │
        ▼
  Identity suffixes matched to enrolled students
        │
        ▼
  Present / Absent records created
        │
        ▼
  Socket.IO emits "refresh-data" ──► All dashboards update live

🚀 Quick Start

Prerequisites

Tool	Version
Node.js	18 or higher
npm	9+
MongoDB	Atlas cluster (or local instance)
Face Recognition API	YOLO + ArcFace service running (e.g., via FastAPI)

1. Clone the Repository

git clone https://github.com/XGNoir95/Sentry.git
cd Sentry

2. Backend Setup

cd Backend
npm install

Create a .env file from the example:

cp .env.example .env

Configure the environment variables:

PORT=5000
MONGODB_URI=mongodb+srv://<username>:<password>@cluster0.xxxxx.mongodb.net/sentry?retryWrites=true&w=majority
JWT_SECRET=change_this_to_a_long_random_secret_string_42
JWT_EXPIRES_IN=7d
FACE_RECOGNITION_API_URL=http://localhost:8000/face-recognition
UPLOAD_DIR=uploads

Start the backend server:

# Development (with auto-reload)
npm run dev

# Production
npm start

The API will be available at http://localhost:5000

3. Frontend Setup

cd Frontend
npm install

Optionally create a .env file to override the API URL:

VITE_API_URL=http://localhost:5000/api

Note: In development, the Vite dev server proxies /api requests to localhost:5000 automatically, so this is only needed for production builds or non-default setups.

Start the frontend dev server:

npm run dev

The app will be available at http://localhost:5173

4. Seed Sample Data (Optional)

cd Backend
npm run seed

🔐 API Reference

All endpoints are prefixed with /api. Protected routes require a Bearer token in the Authorization header.

Authentication

Method	Endpoint	Description	Auth
`POST`	`/api/auth/signup`	Register a new user	✗
`POST`	`/api/auth/login`	Login and receive JWT	✗
`POST`	`/api/auth/logout`	Logout (client-side)	✓
`GET`	`/api/auth/me`	Get current user profile	✓

Student Routes

Method	Endpoint	Description	Auth
`GET`	`/api/student/dashboard`	Dashboard overview	✓
`GET`	`/api/student/courses`	List enrolled courses	✓
`GET`	`/api/student/attendance`	All attendance records	✓
`GET`	`/api/student/attendance/:classId`	Attendance for a class	✓
`POST`	`/api/student/join-class`	Join a class by code	✓
`POST`	`/api/student/leave-class`	Leave a class	✓
`POST`	`/api/student/appeal`	Submit an attendance appeal	✓
`GET`	`/api/student/appeals`	List submitted appeals	✓

Teacher Routes

Method	Endpoint	Description	Auth
`GET`	`/api/teacher/stats`	Dashboard statistics	✓
`GET`	`/api/teacher/classes`	List owned classes	✓
`POST`	`/api/teacher/classes`	Create a new class	✓
`DELETE`	`/api/teacher/classes/:classId`	Delete a class	✓
`POST`	`/api/teacher/classes/:classId/students`	Add students to class	✓
`DELETE`	`/api/teacher/classes/:classId/students/:studentId`	Remove a student	✓
`GET`	`/api/teacher/attendance/:classId`	Class attendance records	✓
`GET`	`/api/teacher/session/:sessionId`	Session detail & results	✓
`GET`	`/api/teacher/appeals`	List all pending appeals	✓
`PATCH`	`/api/teacher/appeals/:appealId`	Approve/reject an appeal	✓
`POST`	`/api/teacher/classes/:classId/announcements`	Post announcement	✓
`DELETE`	`/api/teacher/classes/:classId/announcements/:id`	Delete announcement	✓

Attendance

Method	Endpoint	Description	Auth
`POST`	`/api/attendance/upload`	Upload classroom image (`multipart/form-data`)	✓

Health Check

Method	Endpoint	Description	Auth
`GET`	`/api/health`	API health status	✗

📁 Project Structure

Sentry/
├── Backend/
│   ├── config/
│   │   └── db.js                    # MongoDB connection
│   ├── controllers/
│   │   ├── authController.js        # Signup, login, profile
│   │   ├── attendanceController.js  # Image upload & processing
│   │   ├── studentController.js     # Student dashboard & actions
│   │   └── teacherController.js     # Teacher dashboard & management
│   ├── middlewares/
│   │   ├── auth.js                  # JWT verification & role guard
│   │   ├── upload.js                # Multer file upload config
│   │   └── validate.js              # express-validator runner
│   ├── models/
│   │   ├── Appeal.js                # Attendance appeal schema
│   │   ├── AttendanceRecord.js      # Per-student attendance entry
│   │   ├── AttendanceSession.js     # Photo session metadata
│   │   ├── Class.js                 # Course/class schema
│   │   ├── Student.js               # Student profile schema
│   │   ├── Teacher.js               # Teacher profile schema
│   │   └── User.js                  # Base user (auth) schema
│   ├── routes/
│   │   ├── auth.js                  # Auth endpoints
│   │   ├── attendance.js            # Upload endpoints
│   │   ├── student.js               # Student endpoints
│   │   └── teacher.js               # Teacher endpoints
│   ├── services/
│   │   ├── attendanceService.js     # Attendance processing logic
│   │   └── faceRecognitionService.js# YOLO + ArcFace API client
│   ├── utils/
│   │   ├── ApiError.js              # Custom error class
│   │   ├── apiResponse.js           # Standardized JSON responses
│   │   ├── catchAsync.js            # Async error wrapper
│   │   ├── seed.js                  # Database seeder
│   │   └── socket.js                # Socket.IO initialization
│   ├── .env.example                 # Environment template
│   ├── package.json
│   ├── run_task.js                  # Data migration script
│   └── server.js                    # App entry point
│
├── Frontend/
│   ├── public/                      # Static assets
│   ├── src/
│   │   ├── components/
│   │   │   ├── AuthLeftPanel.jsx     # Login/register branding panel
│   │   │   ├── Footer.jsx            # App footer
│   │   │   ├── MobileAuthBrand.jsx   # Mobile auth branding
│   │   │   ├── Navbar.jsx            # Student navigation bar
│   │   │   ├── ProtectedRoute.jsx    # Route guard by role
│   │   │   └── TeacherNavbar.jsx     # Teacher navigation bar
│   │   ├── context/
│   │   │   ├── AuthContext.jsx       # Auth state provider
│   │   │   ├── NavContext.jsx        # Student nav state
│   │   │   └── TeacherNavContext.jsx  # Teacher nav state
│   │   ├── Layouts/
│   │   │   ├── DashboardLayout.jsx   # Student layout shell
│   │   │   └── TeacherDashboardLayout.jsx # Teacher layout shell
│   │   ├── pages/
│   │   │   ├── LoginPage.jsx         # Login form
│   │   │   ├── RegisterPage.jsx      # Registration form
│   │   │   ├── student/
│   │   │   │   ├── StudentDashboard.jsx  # Student overview
│   │   │   │   ├── StudentCourses.jsx    # Course listings
│   │   │   │   └── StudentSummary.jsx    # Attendance summary
│   │   │   └── teacher/
│   │   │       ├── TeacherPage.jsx           # Teacher shell
│   │   │       ├── TeacherDashboard.jsx      # Stats & overview
│   │   │       ├── TeacherCourses.jsx        # Course management
│   │   │       ├── TeacherCourseDetails.jsx  # Detailed class view
│   │   │       └── TeacherAppeals.jsx        # Appeal management
│   │   ├── services/
│   │   │   ├── api.js                # Axios instance & API methods
│   │   │   └── socket.js             # Socket.IO client
│   │   ├── App.jsx                   # Root component & routing
│   │   ├── main.jsx                  # App entry point
│   │   └── index.css                 # Global styles
│   ├── index.html
│   ├── vite.config.js                # Vite + Tailwind + proxy config
│   ├── vercel.json                   # Vercel SPA routing
│   └── package.json
│
└── README.md

🛠 Tech Stack

Frontend

Technology	Purpose
React 19	UI component library
Vite 8	Build tool & dev server
Tailwind CSS 4	Utility-first styling
React Router 7	Client-side routing
Axios	HTTP client
Socket.IO Client	Real-time WebSocket communication
Lucide React	Icon library

Backend

Technology	Purpose
Express.js 4	REST API framework
Mongoose 8	MongoDB ODM
JSON Web Tokens	Stateless authentication
Socket.IO 4	Real-time event broadcasting
Multer	File upload handling
Helmet	HTTP security headers
bcryptjs	Password hashing (12 salt rounds)
express-validator	Request validation

AI / ML Pipeline

Technology	Purpose
YOLOv8	Face detection in classroom images
ArcFace	Face embedding & identity matching
FastAPI	Model serving (external microservice)

Infrastructure

Service	Purpose
MongoDB Atlas	Cloud database
Vercel	Frontend deployment
Modal	AI model hosting (optional)

🔧 Environment Variables

Backend (`Backend/.env`)

Variable	Description	Default
`PORT`	Server port	`5000`
`MONGODB_URI`	MongoDB connection string	—
`JWT_SECRET`	Secret key for signing JWTs	—
`JWT_EXPIRES_IN`	Token expiration duration	`7d`
`FACE_RECOGNITION_API_URL`	URL to the YOLO + ArcFace API	—
`UPLOAD_DIR`	Directory for uploaded images	`uploads`

Frontend (`Frontend/.env`)

Variable	Description	Default
`VITE_API_URL`	Backend API base URL	`/api` (proxied)

🧩 Data Models

User ──┬── Student ──── AttendanceRecord ──── Appeal
       │                      │
       └── Teacher             │
              │                │
           Class ─────── AttendanceSession
              │
         Announcements

Model	Key Fields
User	`name`, `email`, `password`, `role` (student/teacher/admin), `student_id`, `department`
Student	`student_id`, `name`, linked `User`
Teacher	`teacher_id`, `name`, `department`, linked `User`
Class	`class_name`, `class_code`, `teacher`, `students[]`, `schedule`, `scheduleDays[]`, `announcements[]`
AttendanceSession	`class`, `teacher`, `image_uploaded`, `recognized_students[]`, `status`
AttendanceRecord	`student`, `class`, `session`, `date`, `status` (present/absent), `confidence_score`
Appeal	`student`, `class`, `attendanceRecord`, `date`, `reason`, `status` (pending/approved/rejected), `teacherNote`

🤝 Contributing

Fork the repository
Create a feature branch: git checkout -b feature/my-feature
Commit your changes: git commit -m "feat: add my feature"
Push to the branch: git push origin feature/my-feature
Open a Pull Request

📄 License

This project is open source and available under the MIT License.

Built with ❤️ by XGNoir95

Name		Name	Last commit message	Last commit date
Backend		Backend
Frontend		Frontend
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation