Smart Attendance Predictor

A full-stack attendance eligibility dashboard for college students. Students can add subject-wise attendance details, see whether they are safe for exam eligibility, and understand how many classes they need to attend or can miss.

Tech Stack

• Frontend: React, Vite, Tailwind CSS
• Backend: Node.js, Express
• Database: MongoDB with Mongoose
• Logic: JavaScript attendance prediction formulas

Features

• Overall attendance dashboard
• Multi-menu app navigation: Dashboard, Subjects, Timetable, Calendar, Date Planner, Analytics, Account, Help
• Add, edit, and delete subjects
• Subject fields: name, total classes, attended classes, required percentage
• Default minimum required attendance: 75%
• Login screen with user ID and password
• Create account flow with email OTP verification
• First-time AI setup for new accounts: upload a timetable image/PDF and paste attendance details to auto-fill subjects and timetable
• Status labels: Safe, Warning, Shortage
• Classes needed to reach the minimum percentage
• Classes that can be missed while staying above the minimum
• Date planner synced with the weekly timetable to project attendance till a selected future date
• Calendar view for selecting any date and marking that date's scheduled classes
• Weekly timetable builder for adding subjects to days like DSA on Monday
• Drag-and-drop timetable ordering within each day
• Subject cards with progress bars
• Simple attendance analytics charts
• Responsive, beginner-friendly UI
• Seed data for 12 subjects

Formula Logic

attendancePercentage = (attended / total) * 100;

Classes needed finds the smallest x where:

(attended + x) / (total + x) >= requiredPercentage / 100;

Classes that can be missed finds the largest x where:

attended / (total + x) >= requiredPercentage / 100;

Folder Structure

client/
  src/
    App.jsx
    api.js
    main.jsx
    styles.css
    utils/attendance.js
server/
  src/
    config/db.js
    controllers/subjectController.js
    models/Subject.js
    models/User.js
    models/TimetableEntry.js
    routes/subjectRoutes.js
    routes/authRoutes.js
    routes/timetableRoutes.js
    services/emailService.js
    utils/attendance.js
    utils/password.js
    seed.js
    server.js
README.md

Setup

1. Install Node.js and npm.

2. Start MongoDB locally, or use a MongoDB Atlas connection string.

3. Create the server environment file:

cp server/.env.example server/.env

Update server/.env if needed:

PORT=5001
MONGODB_URI=mongodb://127.0.0.1:27017/smart_attendance_predictor
AUTH_USER_ID=student
AUTH_PASSWORD=attend123
GEMINI_API_KEY=
GEMINI_MODEL=gemini-2.5-pro
SMTP_HOST=
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=
SMTP_PASS=
SMTP_FROM=

For Gmail SMTP, use an app password:

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your_email@gmail.com
SMTP_PASS=your_gmail_app_password
SMTP_FROM=your_email@gmail.com

If SMTP is blank, account creation still works in dev mode and the OTP is printed in the server terminal.

For AI onboarding import, add your Gemini API key:

GEMINI_API_KEY=your_google_ai_studio_key
GEMINI_MODEL=gemini-2.5-pro

4. Install dependencies:

npm install
npm run install:all

5. Add the sample data:

npm run seed

6. Run the full project:

npm run dev

The React app runs at http://localhost:5173. The Express API runs at http://localhost:5001.

Demo login:

User ID: student
Password: attend123

Create Account:

1. Click Create on the login screen.
2. Enter a user ID, email ID, and password.
3. Enter the OTP sent to the email. In dev mode, use the OTP shown in the server terminal.
4. On a brand-new account with no data, use the AI setup card on the dashboard to upload a timetable and paste attendance details.

API Endpoints

Method	Endpoint	Purpose
POST	/api/auth/login	Login with user ID and password
POST	/api/auth/register/request-otp	Send account creation OTP
POST	/api/auth/register/verify-otp	Verify OTP and create account
POST	/api/import/setup	Use Gemini to import timetable and attendance for the current user
GET	/api/subjects	Get all subjects with calculated metrics
POST	/api/subjects	Add a subject
PUT	/api/subjects/:id	Edit a subject
DELETE	/api/subjects/:id	Delete a subject
GET	/api/timetable	Get weekly timetable entries
POST	/api/timetable	Add a timetable entry
PUT	/api/timetable/:id	Edit a timetable entry
DELETE	/api/timetable/:id	Delete a timetable entry

Notes

If the frontend cannot reach the backend, the demo student account still shows sample data in local sample mode so the dashboard can be viewed. Newly created accounts stay empty until they add data.