FaceGuard

FaceGuard is an MVP access-control system for restricted rooms and protected areas. The current MVP line combines an administrator web application, a central backend with persistent storage, a device-side face-recognition agent, and a locally connected camera.

MVP v2 / Assignment 5 Status

Sprint 3 / Assignment 5 delivered MVP v2 documentation, architecture, process, QA, and delivery evidence:

• Week 5 report: reports/week5/README.md
• Architecture package: docs/architecture/README.md
• Development process: docs/development-process.md
• Hosted documentation source: docs/index.md and mkdocs.yml
• Hosted documentation target: FaceGuard documentation published from main.
• Public sanitized MVP v2 demo: Two-minute demo video.

MVP v2 is delivered to main and documented in the Week 5 report. The maintained documentation/evidence package was delivered through PR #63, and recognition/deployment improvements were delivered through PR #65. Hosted documentation is published at FaceGuard documentation, the MVP v2 SemVer release is v2.0.0, and relevant protected-main Quality Gates / GitHub Pages evidence is captured in the Week 5 screenshots. Customer UAT and Sprint Review are documented; the public sanitized demo video is linked. All required public screenshot evidence, including System-page service-status evidence, is included in the Week 5 report.

MVP v1 Status

MVP v1 was delivered through PR #37. The selected Sprint 1 scope covers:

• 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

The complete Assignment 3 submission index is available in the Week 3 report.

Assignment 4 / v1.1.0 Status

FaceGuard v1.1.0 was published as the Assignment 4 Sprint increment:

• Release: FaceGuard v1.1.0
• Protected-main CI: Quality gates run
• Week 4 report: Assignment 4 / Week 4 report
• Project presentation: Five-minute project presentation
• Private-network deployment: http://10.93.26.183:5173/
• Customer confirmation: Week 4 report evidence

The deployment is customer-accessible on the Innopolis University private network.

MVP v1 Architecture

MVP v1 is hardware-dependent but locally reproducible. It consists of these parts:

Component	Location	Purpose
Administrator frontend	frontend/faceguard-web	People management, dashboard, recent recognition events, camera status, and camera preview
Central backend	backend-service	FastAPI service for people, recognition events, camera-facing integration endpoints, and persistent data access
Database	Managed by backend-service	Stores authorized people, uploaded reference metadata, and recognition/access events
Recognition agent	agent	Runs on the machine connected to the camera, performs face-recognition workflow, and sends events to the backend
Camera	Local laptop, USB, virtual, or later Raspberry Pi camera	Provides the live image source for MVP v1 testing and recognition

High-level runtime flow:

Admin browser -> frontend -> central backend -> database
                                      ^
                                      |
Laptop/USB camera -> recognition agent -> recognition/access events

The frontend and backend can be started from this repository. The recognition agent runs locally on a team laptop in development mode and uses the laptop's built-in webcam, a USB webcam, or a virtual camera.

Deployment and Access Model

FaceGuard MVP v1 is not deployed as a permanent public camera stream because the recognition workflow depends on local hardware and may process biometric data.

The reproducible MVP v1 access point is:

• the source code in this repository;
• the published v1.0.0 GitHub Release and generated source archive;
• the published Assignment 4 v1.1.0 GitHub Release for the Sprint 2 increment;
• the local run instructions in this README;
• the public sanitized MVP v1 demo video;
• the public Week 4 project presentation;
• the reviewed MVP v1 integration PR: PR #37.

The Week 4 deployment is available at http://10.93.26.183:5173/ for users on the Innopolis University private network.

Project Backlog and Reports

• Product Backlog project view
• Sprint Backlog project view
• MVP v1 scope project view
• User-story index
• Roadmap
• Architecture
• Development process and configuration management
• Definition of Done
• Quality requirements
• Quality requirement tests
• Testing guide
• User acceptance tests
• Changelog
• MVP v1 release notes
• Assignment 4 release notes
• Customer review summary
• Customer review transcript
• Assignment 4 / Week 4 report
• Assignment 5 / Week 5 report

Prerequisites

Install these tools before running the full local MVP v1 workflow:

• Docker and Docker Compose
• Node.js and npm
• Python environment compatible with the recognition-agent dependencies
• A laptop webcam, USB webcam, or virtual camera
• Git

The commands below use Docker Compose v2 syntax, docker compose. If the local machine uses the legacy Compose CLI, replace it with docker-compose.

Do not commit real credentials, API keys, customer data, generated datasets, biometric images, or private .env values.

Run the Central Backend

Start the backend and its database services first:

cd backend-service
docker compose up --build

The backend API should become available on http://localhost:8000.

Useful backend references:

• Backend setup guide
• Backend API documentation
• Database migrations

Run the Frontend

Start the administrator web interface in a second terminal:

cd frontend/faceguard-web
npm install
npm run dev

Open the local URL printed by Vite, usually http://localhost:5173.

Run the Recognition Agent with a Laptop Camera

Create a local agent environment file:

cd agent
cp .env.example .env

PowerShell equivalent:

cd agent
Copy-Item .env.example .env

For laptop-camera testing, set these values in agent/.env:

HARDWARE_MODE=development
CAMERA_INDEX=0

Use CAMERA_INDEX=0 for the default built-in webcam. If an external or virtual camera is used, change the index according to the local machine.

The backend URL must point to the running central backend. For local development, use the value documented in agent/QUICKSTART.md for the selected run mode.

Then start the agent using the current agent quickstart:

cd agent
docker compose up --build

If Docker camera passthrough is not suitable on the local operating system, use the Python/direct-run option documented in agent/QUICKSTART.md.

MVP v1 Smoke Test

Use this repeatable check to verify the delivered increment:

1. Start the backend and database.
2. Start the frontend.
3. Start the recognition agent with HARDWARE_MODE=development and CAMERA_INDEX=0.
4. Open the administrator interface in the browser.
5. Verify that the People page loads authorized people from the backend.
6. Add a person with reference photos.
7. Refresh the browser and verify that the person remains stored.
8. Verify that the camera preview/status is visible in the web interface.
9. Trigger or simulate a recognition attempt.
10. Verify that recognition/access events appear in the dashboard.
11. Verify that dashboard metrics, recent events, and charts use backend data.
12. Remove a test person and verify that the People list updates.

Manual Link and Command Check

Before submitting a PR that changes this README:

git status --short

Manually check that:

• the backend command matches backend-service;
• the frontend command matches frontend/faceguard-web;
• the agent camera configuration matches agent/QUICKSTART.md;
• repository links render correctly in GitHub;
• no secret, private .env, biometric image, or generated dataset is included.

Repository Layout

• frontend/faceguard-web - active administrator web application for MVP v1
• backend-service - central FastAPI backend and persistent data layer
• agent - local recognition and camera agent
• docs - current user stories, roadmap, and Definition of Done
• reports/week2 - Assignment 2 / MVP v0 report
• reports/week3 - Assignment 3 / MVP v1 report
• reports/week4 - Assignment 4 / Week 4 report, quality gates, embedded evidence, UAT, and release documentation

License

This project is licensed under the MIT License. See LICENSE.