FaceGuard MVP v2

FaceGuard MVP v2

FaceGuard v2.0.0 delivers the MVP v2 increment with improved recognition score handling, operator-facing service monitoring, recognition model management, updated deployment configuration, and maintained project documentation.

This release strengthens both the user-facing administrator interface and the technical foundation of the system.

Highlights

Service status monitoring

The System page now provides visibility into the current state of the main FaceGuard services:

• backend/server API;
• edge device and recognition agent;
• camera;
• recognition service.

Statuses are displayed using clear visual indicators:

• Online — green;
• Warning — yellow;
• Offline — red.

Backend health is refreshed automatically every 30 seconds. Camera and recognition states are derived from the latest available device heartbeat data.

Recognition confidence correction

Recognition score handling has been corrected and unified across the system.

• Raw recognition distance is preserved internally.
• Lower LBPH distance continues to represent a stronger match.
• The administrator interface receives a normalized higher-is-better confidence value.
• Strong matches are displayed as strong and weak matches as weak.
• Dashboard, Access Logs, Live Camera, and event details use consistent recognition-score semantics.

Recognition pipeline improvements

• Added a common recognition interface.
• Added configurable LBPH and DeepFace recognition models.
• Added configurable liveness detection for basic anti-spoofing support.
• Improved recognition agent shutdown and background-task cleanup.
• Added recognition model rebuild control through the System page.
• Improved handling of unavailable camera and edge-device states.

Administrator interface improvements

• Added clearer service status indicators.
• Improved Access Logs presentation.
• Added real-time Access Logs updates through WebSocket events.
• Added camera stream pause and fullscreen controls.
• Improved confirmation flows for destructive actions.
• Improved user-facing recognition confidence presentation.

Architecture and documentation

This release adds maintained project documentation published through GitHub Pages:

• system architecture overview;
• component diagram;
• recognition workflow sequence diagram;
• deployment diagram;
• Architecture Decision Records;
• development and configuration-management process;
• testing strategy;
• quality requirements and QRTs;
• Definition of Done;
• User Acceptance Tests;
• roadmap and user-story documentation.

Documentation:

https://innopolis-robotics-society.github.io/FaceGuardV1/

Testing and quality assurance

The MVP v2 increment includes:

• backend unit and integration tests;
• recognition threshold tests;
• recognition confidence presentation tests;
• frontend automated tests;
• frontend production build validation;
• Ruff linting;
• critical-module coverage checks;
• automated quality-requirement tests;
• Docker Compose configuration validation;
• MkDocs strict documentation build;
• protected-main CI quality gates.

Completed scope

This release includes work related to:

• US-05 — Monitor service status;
• BUG-01 — Recognition agent model update workflow;
• BUG-02 — Recognition confidence displayed in reverse;
• MVP v2 architecture documentation;
• development and configuration process;
• QA and CI improvements;
• Assignment 5 delivery evidence.

Deployment notes

FaceGuard consists of:

• administrator frontend;
• central backend API;
• PostgreSQL database;
• edge recognition agent;
• locally connected camera.

The frontend reads service state from the backend. The backend receives edge-device, camera, and recognition-service state through recognition-agent heartbeat data.

Direct low-level monitoring of camera and recognition internals remains hardware-dependent and will continue to be improved incrementally.

Known limitations

• A physical camera and edge device are required for full real-time face-recognition validation.
• The public deployment may show the camera or edge agent as Offline when no hardware device is connected.
• Some hardware-dependent recognition workflows require local or private-network deployment.
• Anti-spoofing and advanced recognition models require additional environment-specific configuration.

Related pull requests and issues

• Documentation and Assignment 5 evidence: PR #63
• Recognition pipeline and deployment improvements: PR #65
• Service monitoring: Issue #17
• Recognition model update workflow: Issue #35
• Recognition confidence correction: Issue #58

What's Changed

• docs(a4): add Week 4 demo video evidence by @Sparta2016840 in #54
• Docs/a4 week4 report by @Sparta2016840 in #55
• docs: record private customer UAT evidence by @Sparta2016840 in #56
• Delete reports/week4/images/16_customer_confirmation.png by @Sparta2016840 in #57
• docs: align MVP v2 backlog and clean draft files by @Sparta2016840 in #63
• feat: improve recognition pipeline, confidence handling and system configuration by @privel in #65

Full Changelog: v1.1.0...v2.0.0

FaceGuard MVP v1

FaceGuard MVP v1 - Release Notes

Tag: v1.0.0

Release title: FaceGuard MVP v1

Target: final Assignment 3 commit on main

Summary

FaceGuard MVP v1 delivers the first end-to-end access-control increment. It connects the administrator frontend, central backend, persistent database, local recognition agent, and camera integration path.

MVP v1 is hardware-dependent. The frontend and backend are runnable from the repository, while the recognition agent runs locally on a team laptop in development mode using a built-in or USB camera. This model was selected because the customer recommended stabilizing the recognition workflow on Ubuntu/laptop cameras before moving to Raspberry Pi and a fixed entrance camera.

Implemented User Stories

• US-01: View all people with access
• US-02: Add a person to the access list
• US-03: View system dashboard
• US-11: View connected entrance camera

Supporting PBIs

• PBI-01: Persist authorized people in the central backend
• PBI-02: Connect the People page to the backend API
• PBI-03: Implement the add-person flow with reference photographs
• PBI-04: Implement authorized-person removal
• PBI-05: Integrate the real camera and face-recognition agent
• PBI-06: Expose camera image and status to the web application
• PBI-07: Store recognition and access events
• PBI-08: Display recent recognition events on the dashboard
• PBI-09: Connect dashboard metrics and charts to real data
• PBI-10: Integrate and verify the MVP v1 end-to-end workflow

Access and Run Instructions

Use the root README.md for exact local run instructions.

For laptop-camera testing:

HARDWARE_MODE=development
CAMERA_INDEX=0

The camera and recognition agent are not exposed as a permanent public stream because they depend on local hardware and may process biometric data.

Evidence

• MVP v1 integration PR #37
• Week 3 report
• Public sanitized demo video

Known Limitation

After a person is added or removed, the recognition agent currently requires restart or model rebuild before the recognition model uses the updated data. This is tracked as BUG-01 / issue #35.

Notes for GitHub Release Publication

When publishing the GitHub Release:

• create tag v1.0.0;
• set release title to FaceGuard MVP v1;
• target the final Assignment 3 commit on main;
• paste these release notes into the GitHub release description;
• verify that the automatically generated source-code ZIP/tar.gz archives are available.