AI-Powered Attendance Management System (AAMS)

A comprehensive, production-ready attendance management system with face recognition capabilities, built with modern technologies for scalability and reliability.

Overview

The AI-Powered Attendance Management System (AAMS) is an intelligent attendance tracking solution that combines:

Face Recognition Technology for automated attendance marking
REST API Backend built with Spring Boot for robust server-side operations
Interactive Web Frontend for user management and real-time attendance tracking
Python AI Service for face recognition and image processing

This system eliminates manual attendance processes and provides real-time analytics and reporting capabilities.

Features

Core Features

✅ Face Recognition-Based Attendance - Automated attendance marking using AI
✅ User Management - Add, update, and manage users with profiles
✅ Real-time Attendance Tracking - Live attendance monitoring and updates
✅ Email Notifications - Automated email alerts for attendance events
✅ Semester Management - Organize students and classes by semester
✅ Group Management - Create and manage student groups
✅ Comprehensive Reporting - View attendance history and statistics
✅ RESTful API - Complete API for integration with other systems

Security Features

Environment-based configuration for sensitive data
Input validation and error handling
CORS configuration for secure cross-origin requests

Tech Stack

Backend

Framework: Spring Boot (Java)
Database: (Configurable via application.properties)
Build Tool: Maven
JSON Processing: Jackson

Frontend

Frontend Framework: Vanilla JavaScript
Styling: CSS3
Architecture: Module-based structure
Templating: HTML5

AI Service

Language: Python 3.x
Face Recognition: Python-based image processing
HTTP Communication: REST API integration

DevOps & Tools

Version Control: Git
Build: Maven (Java), pip (Python)
Containerization: Docker-ready structure
CI/CD: GitHub Actions compatible

Project Structure

AAMS/
├── .gitignore              # Git ignore rules
├── README.md              # Project documentation
├── backend/               # Spring Boot backend service
│   ├── src/
│   │   ├── main/java/
│   │   │   └── com/laxmanpoudel/attendance/
│   │   │       ├── controller/      # REST API endpoints
│   │   │       ├── service/         # Business logic
│   │   │       ├── entity/          # JPA entities
│   │   │       ├── repository/      # Data access layer
│   │   │       ├── dto/             # Data transfer objects
│   │   │       └── configuration/   # Spring configuration
│   │   └── resources/
│   │       ├── application.properties
│   │       └── templates/           # Email templates
│   └── pom.xml           # Maven configuration
├── frontend/              # Web frontend
│   ├── public/
│   │   ├── css/          # Stylesheets
│   │   ├── js/           # JavaScript modules
│   │   └── images/       # Static images
│   └── views/            # HTML templates
└── ai-service/           # Python AI service
    ├── recognition.py    # Face recognition logic
    ├── register.py       # User registration with face data
    └── requirement.txt   # Python dependencies

Prerequisites

System Requirements

Java: JDK 11 or higher
Python: Python 3.7 or higher
Node.js: Optional, for frontend development
Maven: 3.6+
Git: For version control

Required Software

Git for version control
A modern web browser (Chrome, Firefox, Safari, Edge)
Command line terminal/PowerShell

Installation

1. Clone the Repository

git clone https://github.com/yourusername/AAMS.git
cd AAMS

2. Backend Setup

Install Java Dependencies

cd backend
mvn clean install

This command will:

Clean previous build artifacts
Download all Maven dependencies
Compile the Java source code
Run unit tests

3. Frontend Setup

No installation required for vanilla JavaScript frontend. Simply ensure:

Static files are served from the frontend/public directory
HTML files are served from frontend/views directory

4. AI Service Setup

Create Python Virtual Environment

cd ai-service

# Windows
python -m venv venv
venv\Scripts\activate

# macOS/Linux
python3 -m venv venv
source venv/bin/activate

Install Python Dependencies

pip install -r requirement.txt

Configuration

Backend Configuration

Edit backend/src/main/resources/application.properties:

# Server Configuration
server.port=8080
server.servlet.context-path=/api

# Database Configuration
spring.datasource.url=jdbc:mysql://localhost:3306/aams_db
spring.datasource.username=root
spring.datasource.password=your_password
spring.jpa.hibernate.ddl-auto=update

# Email Configuration
spring.mail.host=smtp.gmail.com
spring.mail.port=587
spring.mail.username=${MAIL_USERNAME}
spring.mail.password=${MAIL_PASSWORD}
spring.mail.properties.mail.smtp.auth=true
spring.mail.properties.mail.smtp.starttls.enable=true

# CORS Configuration
cors.allowed-origins=http://localhost:3000,http://localhost:8080

Environment Variables

Create .env file in the root directory (ensure it's in .gitignore):

# Database
DB_HOST=localhost
DB_PORT=3306
DB_NAME=aams_db
DB_USER=root
DB_PASSWORD=your_secure_password

# Email Service
MAIL_USERNAME=your_email@gmail.com
MAIL_PASSWORD=your_app_password

# API Configuration
API_PORT=8080
API_HOST=localhost

# Frontend
FRONTEND_URL=http://localhost:3000

AI Service Configuration

Edit ai-service/config.py (if exists) or environment variables:

FACE_RECOGNITION_MODEL=path/to/model
API_BACKEND_URL=http://localhost:8080/api

Running the Application

Start Backend Service

cd backend
mvn spring-boot:run

Backend will be available at: http://localhost:8080

Start Frontend

Serve the frontend files using any HTTP server:

# Using Python (Python 3)
cd frontend
python -m http.server 3000

# Using Node.js http-server
npx http-server frontend -p 3000

Frontend will be available at: http://localhost:3000

Start AI Service

cd ai-service
source venv/bin/activate  # On Windows: venv\Scripts\activate
python recognition.py

AI service will be available at: http://localhost:5000 (configure as needed)

API Documentation

Base URL

http://localhost:8080/api

Attendance Endpoints

Mark Attendance

POST /attendance/mark
Content-Type: application/json

{
  "userId": "123",
  "timestamp": "2026-04-20T10:30:00"
}

View Attendance

GET /attendance/view?userId=123&startDate=2026-04-01&endDate=2026-04-30

User Management Endpoints

Register User

POST /user/register
Content-Type: application/json

{
  "email": "user@example.com",
  "firstName": "John",
  "lastName": "Doe"
}

Update User

PUT /user/{userId}
Content-Type: application/json

{
  "email": "new.email@example.com",
  "firstName": "Jane"
}

View Users

GET /user/view
GET /user/view/{userId}

Face Recognition Endpoints

Register Face

POST /face/register
Content-Type: multipart/form-data

- userId: "123"
- faceImage: [binary image data]

Recognize Face

POST /face/recognize
Content-Type: multipart/form-data

- faceImage: [binary image data]

Semester Endpoints

Create Semester

POST /semester/create
Content-Type: application/json

{
  "name": "Fall 2026",
  "startDate": "2026-09-01",
  "endDate": "2026-12-31"
}

List Semesters

GET /semester/list

System Architecture

Architecture Overview

┌─────────────────────────────────────────────────────┐
│              Web Browser (Frontend)                 │
│  ├─ Login & Authentication                         │
│  ├─ User Management Interface                       │
│  ├─ Attendance Tracking Dashboard                   │
│  └─ Real-time Reports                              │
└──────────────────┬──────────────────────────────────┘
                   │ HTTP/REST
┌──────────────────▼──────────────────────────────────┐
│         Spring Boot REST API (Backend)              │
│  ├─ Authentication & Authorization                 │
│  ├─ Business Logic                                 │
│  ├─ Data Validation                                │
│  └─ API Rate Limiting                              │
└──────────────────┬──────────────────────────────────┘
       ┌───────────┴───────────┬──────────────────┐
       │                       │                  │
┌──────▼─────────┐  ┌─────────▼──────┐  ┌───────▼────────┐
│    Database    │  │  Python AI     │  │  Email Service │
│    (MySQL)     │  │  (Face Recog)  │  │   (SMTP)       │
└────────────────┘  └────────────────┘  └────────────────┘

Data Flow

User Registration: User registers → Face capture → Face encoding stored
Attendance Marking: Face capture → Recognition → Attendance recorded → Email sent
Reporting: Query database → Generate statistics → Display on frontend

Contributing

Contribution Guidelines

Fork the repository on GitHub
Create a feature branch: git checkout -b feature/your-feature-name
Make your changes with clear, descriptive commits
Write/update tests for new functionality
Follow code style conventions used in the project
Submit a pull request with detailed description

Code Style Guidelines

Java: Follow Google Java Style Guide
Python: Follow PEP 8 style guide
JavaScript: Use consistent indentation (2 spaces)
Commits: Use clear, descriptive commit messages

Development Setup

# Install pre-commit hooks
pip install pre-commit
pre-commit install

# Run tests
mvn test          # Backend tests
pytest           # Python tests

Support

Getting Help

📧 Email Support: sevensemesterproject@gmail.com
🐛 Report Bugs: GitHub Issues
💬 Discussions: GitHub Discussions

Common Issues

Issue: Backend fails to start

Solution: Check if port 8080 is already in use, ensure Java is installed

Issue: Face recognition not working

Solution: Ensure Python environment is activated and all dependencies are installed

Issue: Database connection error

Solution: Verify MySQL is running and connection string in application.properties is correct

FAQ

Q: Can I deploy this on cloud platforms? A: Yes, the application is designed to be cloud-ready. See deployment guides for AWS, Azure, or GCP.

Q: How do I scale the application? A: Implement load balancing and database replication. See architecture documentation for details.

Q: Is this GDPR compliant? A: The system handles biometric data. Ensure compliance with local regulations regarding face data storage.

Last Updated: April 2026 Version: 1.0.0 Maintainer: Laxman Poudel

Name		Name	Last commit message	Last commit date
ai-service		ai-service
backend		backend
frontend		frontend
.gitignore		.gitignore
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation