Face Recognition Time & Attendance System (Java / Spring Boot)

A production-style face recognition attendance system backend for workforce time and attendance and biometric access control. Employees clock in at a kiosk with their face: the service runs passive liveness / anti-spoofing, identifies the person with 1:N face recognition, and records a timestamped attendance entry — all on-premises, with no image ever leaving your network.

This repository is a small, idiomatic Java 17 + Spring Boot 3 example that shows how to wire the licensed native engine into a real REST backend for employee clock-in and access-control workflows.

Part of the FaceOnLive on-premises biometric SDK suite — faceonlive.com · github.com/FaceOnLive. Face recognition (1:1 & 1:N), passive liveness / anti-spoofing, ID OCR/MRZ, deepfake detection, face attributes and eKYC — all deployable on your own hardware.

Features

• Employee enrollment from a photo — extracts and stores a biometric face template.
• Kiosk clock-in — passive liveness first (anti-spoofing), then 1:N recognition.
• Attendance log — timestamped records with match and liveness scores.
• On-premises — the FaceOnLive engine runs locally; no cloud calls.
• Runtime JNI binding — compiles with just the JDK; the licensed native library is loaded at runtime, so builds don't need the .so/.dll.
• Honest failure modes — if the SDK or license is missing, endpoints fail with a clear error instead of returning fabricated matches.

Requirements

• Java 17+ (JDK)
• Maven 3.9+
• The FaceOnLive biometric SDK native library (libfaceonlive_sdk.so, faceonlive_sdk.dll or libfaceonlive_sdk.dylib) — required only at runtime.
• A FaceOnLive license key (free trial available).

Quickstart

1. Get a free license key and the SDK at faceonlive.com.

2. Set environment variables (native lib path + license key):

   export FACEONLIVE_LICENSE_KEY=<YOUR_LICENSE_KEY>
   export FACEONLIVE_NATIVE_LIB_PATH=/opt/faceonlive/lib

3. Run (point the JVM's library path at the native lib directory):

   mvn spring-boot:run \
     -Dspring-boot.run.jvmArguments="-Djava.library.path=$FACEONLIVE_NATIVE_LIB_PATH"

   The service starts on http://localhost:8080. Check GET /health — it reports engineReady: true once the license activates and models load.

Build without the SDK: mvn -B compile succeeds using only the JDK and Maven. The native library is resolved at runtime via System.loadLibrary, so the proprietary .so/.dll is not needed to compile.

API Reference

Method	Path	Description
POST	/api/employees/enroll	Enroll an employee. Multipart: name, image. Stores a template.
POST	/api/attendance/clock-in	Liveness + 1:N recognition from a frame; records attendance.
GET	/api/attendance	List all attendance records.
GET	/health	Engine + service health (engineReady, enrolled count).

Example curl

# Enroll an employee
curl -X POST http://localhost:8080/api/employees/enroll \
  -F "name=Ada Lovelace" \
  -F "image=@ada.jpg"

# Clock in from a live kiosk frame
curl -X POST http://localhost:8080/api/attendance/clock-in \
  -F "image=@kiosk-frame.jpg"

# List attendance records
curl http://localhost:8080/api/attendance

# Health
curl http://localhost:8080/health

How the SDK integration works

The Java code here is a complete, MIT-licensed example. The biometric math (detection, passive liveness, template extraction and 1:N matching) lives in FaceOnLive's proprietary native engine, which this app loads at runtime.

The integration seam is FaceEngine.java:

• native method declarations describe the C ABI exposed by the FaceOnLive JNI bridge — nativeActivate, nativeInit, nativeDetectAndLiveness, nativeExtractTemplate, nativeMatch1ToN. They have no Java bodies; the implementations are in the native library.
• A static initializer calls System.loadLibrary("faceonlive_sdk") — this is where the licensed library plugs in at runtime. Because it runs on class load rather than at compile time, the project builds without the library.
• activate(<YOUR_LICENSE_KEY>) unlocks the engine and init() loads the models at startup. If the library or license is missing, FaceEngine throws a clear exception — it never fabricates results.

To go live, drop the FaceOnLive native library on java.library.path and set FACEONLIVE_LICENSE_KEY. No Java changes are required.

License & links

• License: MIT (this example only; the FaceOnLive SDK is licensed separately).
• Website: faceonlive.com
• Documentation: faceonlive.com/docs
• Organization: github.com/FaceOnLive
• Other Face SDK examples: .NET Face Recognition SDK · Android Face Recognition SDK
• Contact: contact@faceonlive.com