SAMS Backend

Backend API for SAMS (Smart Attendance Management System) — a classroom attendance system where students mark their presence from inside the lecture hall using a short-lived session token and Bluetooth proximity checks.

This repo is the API + data layer. The web dashboards for admin, HOD and professors live in the separate SAMS-FRONTEND repository. Students mark attendance from a mobile client that talks to this API.

How attendance works

1. A professor opens a live session for a class (subject, period number and the classroom device are selected). The server issues a rotating session token, valid for a few minutes, and pre-creates an "absent" record for every enrolled student.
2. Students in the room mark themselves present through the mobile client. The mark only counts if the client sends a valid session token and the Bluetooth signal (RSSI) from the classroom device is strong enough — i.e. the student is physically in the room, not marking from home.
3. Professors, HODs and admins watch live results on the web dashboard, and analytics highlight at-risk students (attendance below 75%) for follow-up.

There is a demo mode (a fixed DEMO_TOKEN skips the token/RSSI checks) so the whole flow can be shown without hardware.

Features

• Role-based auth — JWT login for admin, professor, hod and student roles; registration is admin-only; role middleware guards every route.
• Classes & timetable — classes with enrolled students and a weekly timetable (day, period, start/end time).
• Classroom devices — devices registered per classroom (device ID + secret key, building/floor); the API tracks online/offline state, last-seen time and tamper alerts.
• Live sessions — start a session for a class + period + device; rotating session tokens (auto-rotated by a cron job), duplicate-session prevention, absent-first records.
• Attendance marking — token validation + RSSI proximity check against a configurable threshold (RSSI_THRESHOLD, default -75).
• Analytics — dashboard aggregates for admin/HOD: device status, today's sessions and attendance, totals, at-risk students.
• CSV export — per-class attendance export for admin/HOD/professor.
• Email alerts — attendance/at-risk alerts via Nodemailer (checkAndSendAlerts).
• Demo data — scripts/seed.js populates MongoDB with realistic demo data; scripts/createAdmin.js creates the first admin account.

Tech stack

Layer	Technology
Runtime	Node.js
Framework	Express 5
Database	MongoDB (Mongoose 9)
Auth	JWT (jsonwebtoken) + bcryptjs
Scheduling	node-cron
Email	nodemailer
Extras	uuid, cors, dotenv

Project structure

SAMS-BACKEND/
├── server.js              # app entry, middleware, route mounting
├── models/                # Mongoose models: User, Class, Device, Session, Attendance
├── controllers/           # route handlers (auth, class, device, session, attendance, analytics)
├── routes/                # /api/auth, /api/users, /api/devices, /api/sessions,
│                          # /api/classes, /api/attendance, /api/analytics, /api/export
├── middleware/auth.js     # JWT protect + role authorization
├── utils/                 # token rotation, email service, cron scheduler
└── scripts/               # seed demo data, create admin

Getting started

Requirements: Node.js 18+ and a MongoDB instance (local or Atlas).

git clone https://github.com/sreevx/SAMS-BACKEND.git
cd SAMS-BACKEND
npm install

Create a .env file:

MONGO_URI=mongodb://127.0.0.1:27017/sams
PORT=5000
JWT_SECRET=change_me
JWT_EXPIRE=7d
RSSI_THRESHOLD=-75
EMAIL_USER=your_email_user      # optional, only needed for alert emails
EMAIL_PASS=your_email_password

Start the server:

npm run dev        # nodemon
# or
npm start

Seed demo data and create an admin account:

node scripts/seed.js
node scripts/createAdmin.js

The API listens on http://localhost:5000 (or the PORT you set). Health check:

curl http://localhost:5000/

API overview

Method	Endpoint	Access	Purpose
POST	/api/auth/login	public	Login, returns JWT
POST	/api/auth/register	admin	Create a user
GET	/api/auth/me	authenticated	Current user
*	/api/users	admin	User management
*	/api/devices	admin	Register / list classroom devices
*	/api/classes	role-scoped	Classes + weekly timetable
*	/api/sessions	professor/HOD	Start / manage live sessions
*	/api/attendance	authenticated	Mark & query attendance
GET	/api/analytics/dashboard	admin, HOD	Dashboard aggregates, at-risk
GET	/api/export/class/:classId/csv	admin, HOD, professor	CSV export

Notes & limitations

• This is a student project built for a hackathon/demo, so it favors a working end-to-end flow over production hardening. The RSSI check is a practical proximity heuristic, not a secure proof of presence.
• Sessions and tokens are stored in MongoDB; a production version would add rate limiting, refresh tokens, HTTPS-only cookies and stronger device attestation.
• The mobile (Flutter) client that students use to mark attendance is not part of this repository — the API contract in controllers/attendanceController.js shows the fields it sends.