Student Attendance Management System (SAMS) - Backend

A comprehensive RESTful API for managing student attendance with role-based access control, built with Node.js, Express.js, and PostgreSQL.

📋 Project Overview

SAMS is a full-featured student attendance management system designed for educational institutions. It provides secure authentication, role-based access control, and comprehensive attendance tracking capabilities.

Team Members

• Amogh Sunil
• Abhin G Das
• Aarush Lobo
• Amogh Vaidya

Project Duration

• 2 Sprints (8 days total)

🚀 Features

• JWT Authentication - Secure token-based authentication
• Role-Based Access Control - Student, Faculty, and Admin roles
• Password Hashing - Bcrypt for secure password storage
• Input Validation - Express-validator for request validation
• Error Handling - Centralized error handling middleware
• CORS Support - Cross-origin resource sharing configuration
• PostgreSQL Database - Robust relational database
• RESTful API - Clean and consistent API design

📁 Project Structure

SAMS/
├── src/
│   ├── config/
│   │   ├── database.js          # PostgreSQL connection pool
│   │   └── jwt.js               # JWT configuration
│   ├── middleware/
│   │   ├── auth.js              # Authentication & authorization
│   │   └── errorHandler.js     # Global error handling
│   ├── models/
│   │   └── User.js              # User model with database operations
│   ├── routes/
│   │   └── auth.js              # Authentication routes
│   ├── controllers/
│   │   └── authController.js   # Authentication logic
│   ├── utils/
│   │   └── responses.js         # Standard API responses
│   └── app.js                   # Express app configuration
├── tests/
│   ├── unit/                    # Unit tests
│   └── integration/             # Integration tests
├── .env.example                 # Environment variables template
├── .gitignore                   # Git ignore rules
├── .eslintrc.json              # ESLint configuration
├── jest.config.js              # Jest testing configuration
├── package.json                # Dependencies and scripts
└── server.js                   # Server entry point

🛠️ Tech Stack

• Runtime: Node.js
• Framework: Express.js v5
• Database: PostgreSQL
• Authentication: JWT (jsonwebtoken)
• Password Hashing: bcrypt
• Validation: express-validator
• Testing: Jest + Supertest
• Linting: ESLint (Airbnb style guide)

📦 Installation

Prerequisites

• Node.js (v14 or higher)
• PostgreSQL (v12 or higher)
• npm or yarn

Steps

1. Clone the repository

   git clone <repository-url>
   cd SEmini

2. Install dependencies

   npm install

3. Set up environment variables

   cp .env.example .env

   Edit .env with your configuration:

   PORT=3000
   NODE_ENV=development
   
   DB_HOST=localhost
   DB_PORT=5432
   DB_NAME=sams_db
   DB_USER=your_username
   DB_PASSWORD=your_password
   
   JWT_SECRET=your-super-secret-jwt-key
   JWT_EXPIRATION=24h
   
   CORS_ORIGIN=http://localhost:3001

4. Set up the database

   -- Create database
   CREATE DATABASE sams_db;
   
   -- Connect to database
   \c sams_db
   
   -- Create users table
   CREATE TABLE users (
     id SERIAL PRIMARY KEY,
     email VARCHAR(255) UNIQUE NOT NULL,
     password VARCHAR(255) NOT NULL,
     first_name VARCHAR(100) NOT NULL,
     last_name VARCHAR(100) NOT NULL,
     role VARCHAR(20) NOT NULL CHECK (role IN ('student', 'faculty', 'admin')),
     registration_number VARCHAR(50) UNIQUE,
     is_active BOOLEAN DEFAULT true,
     created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
     updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
   );
   
   -- Create indexes
   CREATE INDEX idx_users_email ON users(email);
   CREATE INDEX idx_users_role ON users(role);
   CREATE INDEX idx_users_registration_number ON users(registration_number);

5. Start the server

   # Development mode with auto-reload
   npm run dev
   
   # Production mode
   npm start

🧪 Testing

# Run all tests with coverage
npm test

# Run tests in watch mode
npm run test:watch

# Run linting
npm run lint

# Check linting without fixing
npm run lint:check

📚 API Documentation

Base URL

http://localhost:3000/api

Authentication Endpoints

1. Register User

POST /api/auth/register
Content-Type: application/json

{
  "email": "student@example.com",
  "password": "SecurePass123",
  "firstName": "John",
  "lastName": "Doe",
  "role": "student",
  "registrationNumber": "PES1202100123"
}

Response (201):
{
  "success": true,
  "message": "User registered successfully",
  "data": {
    "user": {
      "id": 1,
      "email": "student@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "role": "student",
      "registrationNumber": "PES1202100123"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "timestamp": "2025-11-06T10:30:00.000Z"
}

2. Login

POST /api/auth/login
Content-Type: application/json

{
  "email": "student@example.com",
  "password": "SecurePass123"
}

Response (200):
{
  "success": true,
  "message": "Login successful",
  "data": {
    "user": {...},
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "timestamp": "2025-11-06T10:30:00.000Z"
}

3. Get Profile (Protected)

GET /api/auth/profile
Authorization: Bearer <token>

Response (200):
{
  "success": true,
  "message": "Profile retrieved successfully",
  "data": {
    "user": {
      "id": 1,
      "email": "student@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "role": "student",
      "registrationNumber": "PES1202100123",
      "isActive": true,
      "createdAt": "2025-11-06T10:00:00.000Z",
      "updatedAt": "2025-11-06T10:00:00.000Z"
    }
  },
  "timestamp": "2025-11-06T10:30:00.000Z"
}

4. Update Profile (Protected)

PUT /api/auth/profile
Authorization: Bearer <token>
Content-Type: application/json

{
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "jane.smith@example.com"
}

5. Change Password (Protected)

PUT /api/auth/password
Authorization: Bearer <token>
Content-Type: application/json

{
  "currentPassword": "SecurePass123",
  "newPassword": "NewSecurePass456"
}

Health Check

GET /health

Response (200):
{
  "status": "OK",
  "message": "Student Attendance Management System API is running",
  "timestamp": "2025-11-06T10:30:00.000Z",
  "uptime": 3600.5
}

🔒 Security Features

1. Password Hashing - Bcrypt with 10 salt rounds
2. JWT Authentication - Secure token-based auth
3. SQL Injection Prevention - Parameterized queries
4. Input Validation - Express-validator middleware
5. CORS Configuration - Controlled cross-origin access
6. Role-Based Access Control - Fine-grained permissions

🎯 Code Quality Standards

• ESLint Score: ≥7.5/10 (Airbnb style guide)
• Test Coverage: ≥75%
• Conventional Commits: feat:, fix:, test:, docs:
• Branch Protection: No direct commits to main
• Code Reviews: All PRs require review

📝 Development Workflow

1. Create feature branch from main
2. Implement feature with tests
3. Run linting: npm run lint
4. Run tests: npm test
5. Commit with conventional commit message
6. Push and create Pull Request
7. Wait for code review and CI/CD checks
8. Merge after approval

🔧 Scripts

Script	Description
npm start	Start production server
npm run dev	Start development server with auto-reload
npm test	Run tests with coverage report
npm run test:watch	Run tests in watch mode
npm run lint	Run ESLint and auto-fix issues
npm run lint:check	Check linting without fixing

🐛 Error Handling

All errors follow a consistent format:

{
  "success": false,
  "message": "Error description",
  "errors": {
    "field": "Specific error details"
  },
  "timestamp": "2025-11-06T10:30:00.000Z"
}

Common HTTP Status Codes:

• 200 - Success
• 201 - Created
• 400 - Bad Request / Validation Error
• 401 - Unauthorized
• 403 - Forbidden
• 404 - Not Found
• 409 - Conflict
• 500 - Internal Server Error

📊 Next Steps

1. Attendance Module - Mark and view attendance
2. Notifications - Email/SMS alerts for low attendance
3. Reports - PDF/Excel generation
4. Admin Dashboard - User management
5. Audit Logs - Track all changes
6. CI/CD Pipeline - GitHub Actions workflow

📄 License

MIT License - See LICENSE file for details

👥 Contributors

• Amogh Sunil
• Abhin G Das
• Aarush Lobo
• Amogh Vaidya

📞 Support

For issues and questions, please create an issue in the repository.

---

Built with ❤️ for PESU Software Engineering Mini Project