# zhu-j-faceonlive/face-attendance-system-java architecture

> Architecture diagram of the GitHub repository zhu-j-faceonlive/face-attendance-system-java, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zhu-j-faceonlive/face-attendance-system-java
- Repository: https://github.com/zhu-j-faceonlive/face-attendance-system-java

## Overview

This Spring Boot backend serves employee enrollment, kiosk clock-in, attendance-log, and health endpoints. Enrollment extracts a face template and keeps it with the employee in memory. Clock-in checks passive liveness before extracting a probe and matching it against enrolled templates; only accepted matches produce timestamped records. The Java FaceEngine wrapper delegates biometric operations to a licensed on-premises JNI library. Relationships below follow the excerpted controller and service calls and README-documented SDK boundary; persistence is in-memory, not a database.

Main entry points: [`src/main/java/com/faceonlive/attendance/service/AttendanceService.java`](https://github.com/zhu-j-faceonlive/face-attendance-system-java/blob/main/src/main/java/com/faceonlive/attendance/service/AttendanceService.java) (Attendance service), [`src/main/java/com/faceonlive/attendance/controller/AttendanceController.java`](https://github.com/zhu-j-faceonlive/face-attendance-system-java/blob/main/src/main/java/com/faceonlive/attendance/controller/AttendanceController.java) (REST controller), [`src/main/java/com/faceonlive/attendance/service/FaceEngine.java`](https://github.com/zhu-j-faceonlive/face-attendance-system-java/blob/main/src/main/java/com/faceonlive/attendance/service/FaceEngine.java) (Face engine wrapper), [`src/main/java/com/faceonlive/attendance/model/Employee.java`](https://github.com/zhu-j-faceonlive/face-attendance-system-java/blob/main/src/main/java/com/faceonlive/attendance/model/Employee.java) (Employee model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["REST API"]
  node_app["Spring Boot app"]
  node_controller["REST controller"]
end

subgraph group_attendance["Attendance workflow"]
  node_service["Attendance service"]
end

subgraph group_biometrics["Biometric engine"]
  node_engine["Face engine wrapper<br/>[FaceEngine.java]"]
  node_native{{"FaceOnLive JNI SDK"}}
end

subgraph group_state["In-memory state"]
  node_employees[("Employee templates")]
  node_employee["Employee model<br/>[Employee.java]"]
  node_records[("Attendance log")]
  node_record["Attendance record"]
end

node_kiosk(("Kiosk / client"))

node_kiosk -->|"calls REST"| node_controller
node_app -.->|"initializes"| node_engine
node_controller -->|"delegates enrollment"| node_service
node_controller -->|"delegates clock-in"| node_service
node_controller -->|"lists records"| node_service
node_controller -->|"checks readiness"| node_engine
node_controller -->|"returns enrollment data"| node_employee
node_controller -->|"returns clock-in data"| node_record
node_service -->|"extracts template"| node_engine
node_service -->|"checks liveness"| node_engine
node_service -->|"matches templates"| node_engine
node_engine -->|"invokes JNI"| node_native
node_service -->|"stores and reads"| node_employees
node_service -->|"appends and lists"| node_records
node_service -->|"creates"| node_employee
node_service -->|"creates"| node_record
node_employees -->|"holds"| node_employee
node_records -->|"holds"| node_record

click node_app "https://github.com/zhu-j-faceonlive/face-attendance-system-java/blob/main/src/main/java/com/faceonlive/attendance/AttendanceApplication.java"
click node_controller "https://github.com/zhu-j-faceonlive/face-attendance-system-java/blob/main/src/main/java/com/faceonlive/attendance/controller/AttendanceController.java"
click node_service "https://github.com/zhu-j-faceonlive/face-attendance-system-java/blob/main/src/main/java/com/faceonlive/attendance/service/AttendanceService.java"
click node_engine "https://github.com/zhu-j-faceonlive/face-attendance-system-java/blob/main/src/main/java/com/faceonlive/attendance/service/FaceEngine.java"
click node_employees "https://github.com/zhu-j-faceonlive/face-attendance-system-java/blob/main/src/main/java/com/faceonlive/attendance/service/AttendanceService.java"
click node_employee "https://github.com/zhu-j-faceonlive/face-attendance-system-java/blob/main/src/main/java/com/faceonlive/attendance/model/Employee.java"
click node_records "https://github.com/zhu-j-faceonlive/face-attendance-system-java/blob/main/src/main/java/com/faceonlive/attendance/service/AttendanceService.java"
click node_record "https://github.com/zhu-j-faceonlive/face-attendance-system-java/blob/main/src/main/java/com/faceonlive/attendance/model/AttendanceRecord.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_controller,node_kiosk toneBlue
class node_service toneAmber
class node_engine,node_native toneMint
class node_employees,node_employee,node_records,node_record toneRose
```

## Components

### REST API

- [Spring Boot app](https://github.com/zhu-j-faceonlive/face-attendance-system-java/blob/main/src/main/java/com/faceonlive/attendance/AttendanceApplication.java): `src/main/java/com/faceonlive/attendance/AttendanceApplication.java`
- [REST controller](https://github.com/zhu-j-faceonlive/face-attendance-system-java/blob/main/src/main/java/com/faceonlive/attendance/controller/AttendanceController.java): `src/main/java/com/faceonlive/attendance/controller/AttendanceController.java`

### Attendance workflow

- [Attendance service](https://github.com/zhu-j-faceonlive/face-attendance-system-java/blob/main/src/main/java/com/faceonlive/attendance/service/AttendanceService.java): `src/main/java/com/faceonlive/attendance/service/AttendanceService.java`

### Biometric engine

- [Face engine wrapper](https://github.com/zhu-j-faceonlive/face-attendance-system-java/blob/main/src/main/java/com/faceonlive/attendance/service/FaceEngine.java): `src/main/java/com/faceonlive/attendance/service/FaceEngine.java`
- **FaceOnLive JNI SDK**

### In-memory state

- [Employee templates](https://github.com/zhu-j-faceonlive/face-attendance-system-java/blob/main/src/main/java/com/faceonlive/attendance/service/AttendanceService.java): `src/main/java/com/faceonlive/attendance/service/AttendanceService.java`
- [Employee model](https://github.com/zhu-j-faceonlive/face-attendance-system-java/blob/main/src/main/java/com/faceonlive/attendance/model/Employee.java): `src/main/java/com/faceonlive/attendance/model/Employee.java`
- [Attendance log](https://github.com/zhu-j-faceonlive/face-attendance-system-java/blob/main/src/main/java/com/faceonlive/attendance/service/AttendanceService.java): `src/main/java/com/faceonlive/attendance/service/AttendanceService.java`
- [Attendance record](https://github.com/zhu-j-faceonlive/face-attendance-system-java/blob/main/src/main/java/com/faceonlive/attendance/model/AttendanceRecord.java): `src/main/java/com/faceonlive/attendance/model/AttendanceRecord.java`

### Other components

- **Kiosk / client**

## Connections

- Kiosk / client → REST controller: calls REST (evidence: `README.md`)
- Spring Boot app → Face engine wrapper: initializes
- REST controller → Attendance service: delegates enrollment (evidence: `src/main/java/com/faceonlive/attendance/controller/AttendanceController.java`)
- REST controller → Attendance service: delegates clock-in (evidence: `src/main/java/com/faceonlive/attendance/controller/AttendanceController.java`)
- REST controller → Attendance service: lists records (evidence: `src/main/java/com/faceonlive/attendance/controller/AttendanceController.java`)
- REST controller → Face engine wrapper: checks readiness (evidence: `src/main/java/com/faceonlive/attendance/controller/AttendanceController.java`)
- REST controller → Employee model: returns enrollment data (evidence: `src/main/java/com/faceonlive/attendance/controller/AttendanceController.java`)
- REST controller → Attendance record: returns clock-in data (evidence: `src/main/java/com/faceonlive/attendance/controller/AttendanceController.java`)
- Attendance service → Face engine wrapper: extracts template (evidence: `src/main/java/com/faceonlive/attendance/service/AttendanceService.java`)
- Attendance service → Face engine wrapper: checks liveness (evidence: `src/main/java/com/faceonlive/attendance/service/AttendanceService.java`)
- Attendance service → Face engine wrapper: matches templates (evidence: `src/main/java/com/faceonlive/attendance/service/AttendanceService.java`)
- Face engine wrapper → FaceOnLive JNI SDK: invokes JNI (evidence: `README.md`)
- Attendance service → Employee templates: stores and reads (evidence: `src/main/java/com/faceonlive/attendance/service/AttendanceService.java`)
- Attendance service → Attendance log: appends and lists (evidence: `src/main/java/com/faceonlive/attendance/service/AttendanceService.java`)
- Attendance service → Employee model: creates (evidence: `src/main/java/com/faceonlive/attendance/service/AttendanceService.java`)
- Attendance service → Attendance record: creates (evidence: `src/main/java/com/faceonlive/attendance/service/AttendanceService.java`)
- Employee templates → Employee model: holds (evidence: `src/main/java/com/faceonlive/attendance/service/AttendanceService.java`)
- Attendance log → Attendance record: holds (evidence: `src/main/java/com/faceonlive/attendance/service/AttendanceService.java`)
