Smart Attendance Agent

A portfolio-grade full-stack attendance management system built for fresher developer interviews.

Screenshots & visual guide

Full walkthrough with annotated screenshots: docs/screenshots/README.md

Project synopsis (Markdown with screenshots): docs/PROJECT_SYNOPSIS.md

Synopsis PDF (local only, not in repo): run python scripts/generate-synopsis-pdf.py → docs/Smart-Attendance-Synopsis.pdf

Login & demo roles
Student dashboard
Mark attendance
Architecture

Regenerate anytime: python scripts/capture-screenshots.py (requires running app — see screenshot README).

Problem Statement

Manual attendance tracking is slow, error-prone, and hard to analyze. This project demonstrates a role-based web app where teachers mark attendance, students view records, and admins manage classes with audit-friendly reporting.

Tech Stack

• Backend: Node.js, Express, TypeScript, Prisma, JWT
• Frontend: React, Vite, TypeScript, React Router
• Streamlit UI: Python dashboard at http://localhost:8501
• Database: SQLite (easy local setup; PostgreSQL-ready via Prisma)
• Quality: ESLint, Prettier, Vitest, GitHub Actions CI
• API Docs: Swagger UI at /api/docs

Architecture

flowchart LR
  ui[ReactFrontend] -->|REST + JWT| api[ExpressAPI]
  api --> authMod[AuthModule]
  api --> classMod[ClassesModule]
  api --> attMod[AttendanceModule]
  api --> reportMod[ReportsModule]
  authMod --> db[SQLitePrisma]
  classMod --> db
  attMod --> db
  reportMod --> db
  reportMod --> csv[CSVExport]

Loading

Features

• User registration and login with access + refresh tokens
• Role-based access control (ADMIN, TEACHER, STUDENT)
• Class creation and student enrollment
• Session-based attendance marking (Present/Absent/Late)
• Filterable reports with analytics cards
• CSV export with authenticated download
• Audit logs for attendance changes
• Swagger API documentation
• Seed data for demo interviews

Project Structure

• backend/src/modules - feature-based API modules
• backend/prisma - schema, seed, migrations
• frontend/src/pages - route pages
• frontend/src/context - auth state persistence
• docs - API docs, Postman collection, demo script, screenshots gallery
• docs/screenshots - UI screenshots + how the project works
• scripts - screenshot capture and utilities

Quick Start

Easiest way (Windows): run everything from the project root:

.\start.ps1          # Backend + Streamlit
.\start.ps1 -All     # Backend + Streamlit + React

Manual setup

1) Backend

cd backend
npm install
copy ..\.env.example .env
npm run prisma:generate
npm run prisma:push
npm run prisma:seed
npm run dev

2) Frontend

cd frontend
npm install
copy .env.example .env
npm run dev

3) Streamlit UI

cd streamlit
python -m pip install -r requirements.txt
streamlit run app.py

Open:

• React frontend: http://localhost:5173
• Streamlit UI: http://localhost:8501
• Backend health: http://localhost:4000/health
• Swagger docs: http://localhost:4000/api/docs

Demo Credentials

Role	Email	Password
Admin	admin@smart.com	Admin@123
Teacher	teacher@smart.com	Teacher@123
Student	student@smart.com	Student@123
Student	student2@smart.com	Student@123

API Endpoints

• POST /api/auth/register
• POST /api/auth/login
• POST /api/auth/refresh
• POST /api/auth/logout
• GET /api/auth/me
• GET /api/users/students
• GET /api/classes
• POST /api/classes
• POST /api/classes/:id/enroll
• GET /api/attendance/session
• POST /api/attendance/mark
• GET /api/attendance/my
• GET /api/reports/attendance
• GET /api/reports/attendance.csv

Detailed docs: docs/api.md

Testing

cd backend
npm run test

Interview Demo Flow

1. Login as teacher and show dashboard analytics.
2. Create class and enroll student.
3. Mark attendance for today.
4. Open reports, apply filters, export CSV.
5. Login as student and show personal attendance page.

See docs/demo-script.md.

Resume Bullet Examples

• Built a full-stack attendance platform with JWT auth, RBAC, and REST APIs in Node.js/Express.
• Implemented Prisma data modeling, session-based attendance tracking, and CSV reporting.
• Added React dashboard with role-aware routing, analytics cards, and authenticated exports.
• Configured CI pipeline with linting and integration tests using Vitest + Supertest.

Known Limitations

• SQLite is used for zero-config local development.
• First admin/teacher accounts are primarily created via seed script.
• Production deployment (Docker/cloud) is intentionally left as an extension task.