AAMS

Professional multi-tenant Attendance Management System for institutions, powered by a Spring Boot backend, a responsive web frontend, PostgreSQL persistence, real-time face recognition, and an optional local AI assistant.

Overview

AAMS is designed for institutions that need a modern, secure, and automated way to manage student attendance. The system supports institution registration, authentication, student enrollment, biometric face registration, real-time attendance marking, attendance reporting, SMTP/email configuration, and an AI assistant for attendance-related questions.

The application is organized as a full-stack SaaS-style platform:

The frontend provides institution login, signup, dashboard, student management, attendance marking, report views, and settings screens.
The backend exposes secured REST APIs, manages tenants/institutions, stores students and attendance records, sends emails, and integrates with local AI services.
The AI service uses FastAPI WebSockets and InsightFace/ArcFace to capture student face embeddings and recognize attendance from live camera frames.
Nginx acts as the reverse proxy for the frontend, backend APIs, and WebSocket routes.

Features

Institution onboarding with email verification.
Secure login, logout, JWT access tokens, and refresh-token session handling.
Multi-tenant institution context for isolating student and attendance data.
Student registration, search, update, department grouping, and semester grouping.
Face enrollment using webcam capture and ArcFace embeddings.
Real-time attendance recognition over WebSockets.
Bulk attendance marking with duplicate/cooldown protection.
Department, semester, and global attendance reports.
Institution settings for profile, SMTP configuration, coordinator accounts, and deactivation.
Email notification templates for verification and attendance events.
Optional local AI assistant backed by an Ollama-compatible chat endpoint.
Dockerized frontend, backend, and Nginx reverse proxy setup.

Tech Stack

Layer	Technology
Frontend	HTML5, CSS3, JavaScript ES modules
Frontend hosting	Nginx
Backend	Java 25, Spring Boot 4.0.6, Maven
Security	Spring Security, JWT, refresh tokens
Database	PostgreSQL, Spring Data JPA, Hibernate
Email	Spring Mail, Thymeleaf email templates
AI assistant	Ollama-compatible local LLM API
Face recognition	Python, FastAPI, WebSockets, InsightFace, ArcFace, OpenCV
Containerization	Docker, Docker Compose
Reverse proxy	Nginx

Architecture

Browser
  |
  | http://localhost:5501
  v
Nginx reverse proxy
  |-- /                -> frontend static site
  |-- /api             -> Spring Boot backend on port 8080
  |-- /ws              -> face registration service on port 5000
  |-- /ws/attendance   -> attendance recognition service on port 8000

Spring Boot backend
  |-- PostgreSQL database
  |-- SMTP provider
  |-- Ollama-compatible LLM endpoint
  |-- Python face services

Python AI services
  |-- register.py      -> captures student face embeddings
  |-- recognition.py   -> recognizes faces and marks attendance

Project Structure

AAMS_SaaS/
├── ai-service/
│   ├── register.py
│   ├── recognition.py
│   └── requirement.txt
├── backend/
│   ├── src/main/java/np/com/laxmanpaudel/aams/
│   │   ├── config/
│   │   ├── controller/
│   │   ├── dto/
│   │   ├── entity/
│   │   ├── repositories/
│   │   ├── service/
│   │   └── tenancy/
│   ├── src/main/resources/
│   ├── Dockerfile
│   └── pom.xml
├── frontend/
│   ├── public/
│   │   ├── css/
│   │   ├── image/
│   │   └── js/
│   ├── aams.html
│   ├── index.html
│   ├── login.html
│   ├── signup.html
│   └── Dockerfile
├── nginx/
│   ├── Dockerfile
│   └── nginx.conf
├── script/
│   ├── aams.bat
│   ├── recognition.bat
│   └── register.bat
├── docker-compose.yml
└── .gitignore

Prerequisites

Install the following before running the project:

Docker Desktop and Docker Compose
Java 25, if running the backend outside Docker
Maven, or use the included Maven wrapper
Python 3.11 or newer for the AI services
PostgreSQL database
Optional: NVIDIA GPU/CUDA environment for faster face recognition
Optional: Ollama or another compatible local LLM server for the AI assistant

Environment Configuration

Create a .env file in the project root. The real .env file is intentionally ignored by Git and must not be committed.

DB_URL=jdbc:postgresql://localhost:5432/aams
DB_USERNAME=postgres
DB_PASSWORD=change_me

JWT_SECRET=replace_with_a_long_random_secret_at_least_64_characters
APP_BASE_URL=http://localhost:5501

MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=your_email@example.com
MAIL_PASSWORD=your_email_app_password
MAIL_FROM=your_email@example.com

ARCFACE_STUDENT_REGISTER_URL=http://host.docker.internal:5000/ws
ARCFACE_RECOGNITION_URL=http://host.docker.internal:8000/ws/attendance

LLM_API_URL=http://host.docker.internal:11434
LLM_MODEL=gemma4:e2b
LLM_TAG_NAME=codeLab

For local development without Docker, use localhost-based values where appropriate:

APP_BASE_URL=http://localhost:5501
LLM_API_URL=http://localhost:11434

The Python registration service can also use Cloudinary credentials for uploading the best captured student frame:

$env:CLOUDINARY_API_KEY="your_cloudinary_api_key"
$env:CLOUDINARY_API_SECRET="your_cloudinary_api_secret"

The attendance recognition service supports these optional API overrides:

$env:AAMS_FACES_API_URL="http://localhost:5501/api/python/faces"
$env:AAMS_ATTENDANCE_API_URL="http://localhost:5501/api/attendance/bulk"

Run with Docker

From the project root:

docker compose up --build

Then open:

http://localhost:5501

Docker Compose starts:

aams-nginx on port 5501
aams-frontend
aams-backend on the internal Docker network

The face registration and attendance recognition services are run separately on the host machine because they use the local camera and ML runtime. Nginx proxies WebSocket traffic to them through host.docker.internal.

Run Locally for Development

Backend

cd backend
.\mvnw.cmd spring-boot:run

The backend runs on:

http://localhost:8080

Frontend

The frontend is a static web application. For the Docker flow, Nginx serves it automatically at http://localhost:5501.

For simple local previewing, you can serve the frontend folder with any static server. API calls may require the backend to be running on http://localhost:8080.

cd frontend
python -m http.server 5501

Database

Create a PostgreSQL database that matches your DB_URL. Example:

CREATE DATABASE aams;

Spring Data JPA is configured with spring.jpa.hibernate.ddl-auto=update, so tables are created/updated automatically during development.

AI and Face Recognition Services

Create and activate a Python virtual environment:

cd ai-service
py -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirement.txt

Start the face registration WebSocket service:

python register.py

Registration service:

ws://localhost:5000/ws

Start the attendance recognition WebSocket service in a second terminal:

python recognition.py

Attendance recognition service:

ws://localhost:8000/ws/attendance

On Windows, the provided helper scripts can also be used:

script\register.bat
script\recognition.bat

API Overview

Institution and Authentication

Method	Endpoint	Purpose
POST	`/api/institution/register`	Register a new institution
POST	`/api/institution/login`	Log in and receive access credentials
POST	`/api/institution/refresh`	Refresh access token
POST	`/api/institution/logout`	End session
GET	`/api/institution/verify-email`	Verify institution email
GET	`/api/institution/me`	Get current institution settings
PUT	`/api/institution/me/smtp`	Update SMTP settings
POST	`/api/institution/me/accounts/coordinators`	Create coordinator account
POST	`/api/institution/me/deactivate`	Deactivate institution

Students and Attendance

Method	Endpoint	Purpose
POST	`/api/student/register`	Register student with biometric data
GET	`/api/students/search`	Search students
GET	`/api/students/{studentId}`	Get one student
GET	`/api/students/deptSem`	Get students by department and semester
PUT	`/api/students/update/{studentId}`	Update student details
POST	`/api/attendance/bulk`	Mark attendance in bulk
GET	`/api/attendance/studentId`	Get attendance by student ID
POST	`/api/semesters/promote`	Promote semester group

Reports, AI, and Face Data

Method	Endpoint	Purpose
GET	`/api/reports/global`	Global attendance report
GET	`/api/reports/department`	Department attendance report
GET	`/api/reports/semester`	Semester attendance report
POST	`/api/ai/chat`	Ask the local AAMS assistant
GET	`/api/python/faces`	Return face encodings for recognition

WebSocket Routes

Route	Service	Purpose
`/ws`	`ai-service/register.py`	Student face registration
`/ws/attendance`	`ai-service/recognition.py`	Real-time attendance recognition

Repository Hygiene

The repository is configured to ignore local secrets and generated files, including:

.env and .env.*
backend/target/
frontend/node_modules/
ai-service/.venv/
ai-service/__pycache__/
ai-service/students/
IDE folders and OS metadata

Before pushing to GitHub, confirm that no secrets or generated artifacts are staged:

git status
git diff --cached --name-only

Recommended files to keep private:

Real database credentials
JWT secrets
SMTP usernames and app passwords
Cloudinary API credentials
Captured student face images
Local ML model caches

Troubleshooting

Backend cannot connect to PostgreSQL

Check that PostgreSQL is running and that DB_URL, DB_USERNAME, and DB_PASSWORD are correct.

Email verification is not sending

Confirm SMTP configuration in .env. For Gmail, use an app password instead of your normal account password.

WebSocket registration or recognition does not connect

Make sure both Python services are running:

register.py    -> port 5000
recognition.py -> port 8000

When using Docker, Nginx forwards /ws and /ws/attendance to those host ports.

AI assistant is unavailable

Start Ollama or your compatible local LLM server, then confirm:

LLM_API_URL=http://host.docker.internal:11434

For local backend development outside Docker, use:

LLM_API_URL=http://localhost:11434

Face recognition is slow or fails to initialize

Face recognition works best with a GPU-enabled Python environment. For CPU-only environments, review the InsightFace provider and ctx_id settings in ai-service/recognition.py.

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

Issue: Docker Engine is not running

Solution: Start Docker Desktop or Docker Engine service and verify it is running before executing Docker commands.

Issue: Docker Compose command not working

Solution: Ensure Docker Compose is installed correctly and use the appropriate command (docker compose or docker-compose) based on your Docker version.

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

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
ai-service		ai-service
backend		backend
frontend		frontend
nginx		nginx
.gitignore		.gitignore
README.md		README.md
docker-compose.yml		docker-compose.yml

Folders and files

Latest commit

History

Repository files navigation

AAMS

Table of Contents

Overview

Features

Tech Stack

Architecture

Project Structure

Prerequisites

Environment Configuration

Run with Docker

Run Locally for Development

Backend

Frontend

Database

AI and Face Recognition Services

API Overview

Institution and Authentication

Students and Attendance

Reports, AI, and Face Data

WebSocket Routes

Repository Hygiene

Troubleshooting

Backend cannot connect to PostgreSQL

Email verification is not sending

WebSocket registration or recognition does not connect

AI assistant is unavailable

Face recognition is slow or fails to initialize

Support

Getting Help

Common Issues

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages