Attendify AI

This repository contains a multi-service attendance platform built around facial recognition, academic attendance workflows, and an Ollama-backed RAG/chat assistant.

This README reflects a static repository audit performed from the codebase contents on April 18, 2026. It documents how the project is wired today, what each service does, how requests flow across the stack, what test coverage exists in the repo, and which security strengths and risks are visible from source alone.

No builds, containers, or test suites were executed as part of this audit.

1. System Overview

The project is organized as a 4-service application stack orchestrated by docker-compose.yml:

1. A React frontend in AttendifyAI/
2. A Spring Boot backend in facial-attendance-system/
3. A Python face-recognition service in facial-recognition/
4. Infrastructure services for MariaDB and Ollama

At a high level:

• The frontend handles authentication, attendance screens, professor/director dashboards, notifications, and chat UI.
• The Spring backend is the main application API and business logic layer.
• The Python service handles face-photo storage and face-recognition requests.
• MariaDB stores the application data.
• Ollama provides local LLM chat and embedding support for the RAG feature.

2. Repository Layout

Top-level directories and notable files:

• AttendifyAI/: Create React App frontend
• facial-attendance-system/: Java 21 Spring Boot backend
• facial-recognition/: Python 3.11 face-recognition service
• docker-compose.yml: main local/container orchestration file
• .env: local environment file currently containing populated secrets on disk
• .env.example: example environment file
• jenkins-report/index.html: committed static report artifact
• Jenkinsfile: helper pipeline file, but there is no meaningful .github CI definition in the repo

Generated or report-like artifacts currently committed to the repository include:

• AttendifyAI/build/: frontend production build output
• facial-recognition/coverage-report/: Python coverage report output
• jenkins-report/index.html: static Jenkins report output

3. Service Stack

Frontend

The frontend lives in AttendifyAI/package.json and is a Create React App application using:

• React 19
• react-scripts
• Tailwind CSS / PostCSS
• Testing Library + Jest
• An Nginx production image for serving the built static bundle

Key characteristics:

• Built with npm run build
• Served as static assets behind Nginx in production/container usage
• Contains API bindings in AttendifyAI/src/api/index.js
• Contains face-recognition browser flow in AttendifyAI/src/pages/Presences.js

Backend

The backend lives in facial-attendance-system/pom.xml and uses:

• Java 21
• Spring Boot 3.5
• Spring Web
• Spring Data JPA
• Spring Validation
• Spring Security
• Spring Mail
• Spring Boot Actuator
• Spring AI Ollama
• MapStruct
• Lombok
• Apache PDFBox
• JWT via jjwt
• BCrypt password hashing
• MariaDB with HikariCP

Key runtime configuration is defined in facial-attendance-system/src/main/resources/application.properties.

Python Recognition Service

The face-recognition service lives in facial-recognition/requirements.txt and is a Python 3.11 service built around:

• opencv-python
• face_recognition
• numpy
• stdlib HTTP handling
• local HTTP endpoints exposed for photo save and recognition operations

The implementation entry point highlighted by the audit is facial-recognition/main.py.

Infrastructure

The Compose stack also includes:

• MariaDB
• Ollama

MariaDB is currently configured in Compose to run with the root user, which is a security concern for non-local or production-like deployments.

4. Runtime Topology and Ports

Based on the repository configuration, the stack exposes the following main services:

Service	Purpose	Port(s)	Access
API Gateway (NEW)	Nginx reverse proxy - unified entry point	80	Public
Frontend	React UI (internal, served via gateway)	—	Via Gateway
Spring Boot backend	Main API at /api/* (internal)	—	Via Gateway
Python recognition service	Face recognition at /recognize/*, /photo/* (internal)	—	Via Gateway
Ollama	Local LLM chat and embeddings	11434	Internal
MariaDB	Application database	host 3307 -> container 3306	Internal

5. Build and Deployment Model

The repository is container-oriented and wired through Docker Compose.

Frontend build

• Source lives under AttendifyAI/
• Built with npm run build
• Produces a static asset bundle
• Production image serves the bundle with Nginx

Backend build

• Source lives under facial-attendance-system/
• Built with Maven
• Produces a Spring Boot fat JAR

Python service build

• Source lives under facial-recognition/
• Docker image installs dependencies from facial-recognition/requirements.txt

Compose orchestration

docker-compose.yml wires together:

• frontend
• spring backend
• python recognition
• MariaDB
• Ollama

Dependencies are arranged so the backend waits on database health and expects Ollama and Python recognition to be available for their respective features.

6. Main Request Flows

The stack is not a simple frontend -> backend-only system. Different features take different paths.

Standard browser API flow

Most browser requests go through the Spring backend via AttendifyAI/src/api/index.js.

This includes functionality for:

• authentication
• students
• classes
• attendance
• professors
• notifications
• admin health
• RAG chat and indexing

Face-recognition flow

Face recognition is handled differently from the rest of the app:

1. The browser calls the Python recognition service directly on :5051/recognize from AttendifyAI/src/pages/Presences.js.
2. The recognition result is then sent back to Spring at /api/attendance/process.

This means attendance recognition currently uses a browser -> Python -> browser -> Spring flow rather than a fully backend-mediated flow.

Student photo upload flow

Student photo registration follows this path:

1. Browser uploads to Spring at /api/biometric/students/photo
2. Spring forwards the request server-to-server to Python at /save-photo

Backend-to-service integrations

The Spring backend also communicates directly with:

• Python for biometric health checks and cache preload
• Ollama for chat generation and embeddings
• Gmail SMTP for email delivery

7. Configuration Notes

Important application configuration is concentrated in:

• docker-compose.yml
• facial-attendance-system/src/main/resources/application.properties
• .env
• AttendifyAI/src/api/index.js

Visible configuration themes in the repo include:

• datasource configuration for MariaDB
• JWT secret and expiration settings
• CORS allowlists
• app URL and frontend origins
• Actuator health exposure
• Ollama base URL and model selection
• Python biometric endpoint URLs
• RAG indexing settings
• multipart upload size limits

8. Testing State

Testing exists in all three application layers.

Frontend tests

The frontend includes 3 Jest / Testing Library tests.

Audit note:

• The frontend test suite appears stale.
• Some tests still import API functions that no longer exist in the current API module.
• This suggests the frontend tests are at risk of failing or no longer validating current behavior accurately.

Backend tests

The backend includes 12 JUnit / MockMvc / Mockito / H2-oriented test files.

Audit note:

• The backend test setup appears reasonably modern.
• The presence of spring-boot-starter-test, spring-security-test, and H2 indicates a solid basis for service, controller, security, and exception testing.

Python tests

The Python service includes 6 pytest-based test files and uses pytest-cov.

Audit note:

• Python testing appears to cover API helpers, recognition logic, photo handling, and service entry behavior.

9. CI/CD and Delivery Status

There is no meaningful modern CI pipeline definition under .github in the repository.

What does exist:

• helper scripts
• generated report artifacts
• a Jenkinsfile
• committed frontend build output in AttendifyAI/build/
• committed coverage/report output in facial-recognition/coverage-report/ and jenkins-report/

This means the repo currently looks more like a locally run or manually verified project than one protected by an enforced CI pipeline.

10. Security Posture

The repository does contain real security controls. This is not an entirely unprotected application.

Security controls present in the codebase

The audit found evidence of:

• stateless JWT authentication
• BCrypt password hashing
• role-based access control with DIRECTEUR and PROF
• DTO validation
• CORS allowlists
• audit logs
• reset-token expiry
• suspicious-login tracking
• school-scoped data access

Relevant backend security configuration is centered around facial-attendance-system/src/main/java/com/attendance/security/SecurityConfig.java.

Security gaps and risks identified

The audit also identified several important issues:

Secrets management

• The root .env file contains populated secrets on disk.

Privilege / account model

• Self-registration can request the DIRECTEUR role.

Token storage

• JWTs are stored in localStorage.
• This increases exposure to token theft if XSS is introduced anywhere in the frontend.

Missing transport / browser hardening layers

• No HTTPS enforcement visible in repo-level runtime config
• No Content Security Policy layer
• No explicit rate limiting
• No account lockout layer
• No dedicated security-header enforcement layer

Identity trust bug

• PUT /api/professors/profile trusts an email address from the request body instead of deriving identity from the authenticated principal.

XSS surface

• Both chat widgets use dangerouslySetInnerHTML.

Health and service exposure

• The frontend directly probes raw health endpoints over HTTP.

Python service trust boundary

• The Python recognition endpoints rely on CORS but do not authenticate requests themselves.

Database privilege model

• Compose runs MariaDB as root.

11. AI / RAG State

The repository includes an implemented RAG feature, backed by Spring AI and Ollama.

However, the backend knowledge/ directory is effectively empty except for .gitkeep.

Practical implication:

• document question-answering currently depends more on uploaded PDFs or database-backed data than on a preloaded repository knowledge base

12. Architecture Summary

In practical terms, the project behaves like this:

• The React application is the main user interface.
• Spring Boot is the central API, authentication, business logic, email, and orchestration layer.
• Python handles biometric storage and recognition operations.
• MariaDB stores the operational data.
• Ollama powers local chat and embeddings for the assistant/RAG feature.

The unusual part of the architecture is that facial recognition is not fully mediated by Spring. The browser talks directly to the Python recognition endpoint during the attendance flow, then sends processed results back to Spring. That split trust boundary is one of the most important design characteristics of the current implementation.

13. Key Files for Fast Orientation

If you need to understand the current architecture quickly, start with these files:

• docker-compose.yml
• AttendifyAI/src/api/index.js
• AttendifyAI/src/pages/Presences.js
• facial-attendance-system/src/main/resources/application.properties
• facial-attendance-system/src/main/java/com/attendance/security/SecurityConfig.java
• facial-recognition/main.py

14. Audit Scope and Limitations

This README is intentionally descriptive of the repository as it exists in source control.

What this audit did not do:

• run the frontend build
• run the backend Maven build
• run the Python test suite
• execute Docker Compose
• validate runtime behavior against a live environment
• confirm whether every configured security control is fully effective at runtime

Accordingly, this document should be read as a static architecture and code-surface audit, not a runtime penetration test or a verified deployment guide.