FaceGuard

FaceGuard is a maintained course MVP for face-recognition access monitoring. It combines an administrator web application, a FastAPI backend, PostgreSQL storage, a device-side recognition agent, local camera hardware, and a customer-facing LED access indicator.

Current Status

• Current public trial release: v2.1.0
• Final Assignment 6 / MVP v3 work and customer acceptance: documented in reports/week7/README.md
• Week 6 trial evidence: reports/week6/README.md
• Hosted documentation: FaceGuard documentation
• Customer handover guide: docs/customer-handover.md
• Public sanitized MVP v2 demo: two-minute demo video

The product is usable as a local/private-network deployment. Full real-time recognition still depends on a configured camera, Raspberry Pi-compatible environment, local model data, and non-public credentials. Final customer acceptance for independent use was recorded in the Week 7 handover review; this does not by itself evidence a customer-side production deployment.

Product Components

Component	Location	Purpose
Administrator frontend	frontend/faceguard-web	People management, dashboard, access logs, camera status, and operator controls
Central backend	backend-service	FastAPI API for auth, people, photos, devices, events, telemetry, commands, and audit data
Database	backend-service/docker-compose.yml	PostgreSQL persistence for backend data
Recognition agent	agent	Camera capture, recognition, anti-spoofing/liveness checks, offline buffering, and backend sync
Access indicator	agent/door/door_controller.py	Blue/yellow/red LED feedback for granted/calibrating/denied states
Maintained docs	docs	Architecture, testing, quality, roadmap, user stories, UAT, handover, and code reference

Runtime flow:

Admin browser -> React frontend -> FastAPI backend -> PostgreSQL
                                           ^
                                           |
Camera -> recognition agent -> event/sync/command API
                    |
                    v
            LED access indicator

Documentation Entry Points

• Customer handover
• Contributing guide
• Agent/operator guidance
• Roadmap
• Architecture overview
• Deployment diagram
• Testing guide
• Quality requirements
• User acceptance tests
• Code reference
• Changelog

Run Locally

Prerequisites:

• Docker and Docker Compose
• Node.js and npm
• Python 3.11-compatible environment for direct agent runs
• A webcam or Raspberry Pi camera for real recognition checks
• Git

Do not commit real credentials, API keys, customer data, biometric images, trained model files, generated datasets, private .env files, or private submission evidence.

Backend

cd backend-service
docker compose up --build

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

Useful references:

• Backend setup
• Backend API documentation
• Database migrations

Frontend

cd frontend/faceguard-web
npm install
npm run dev

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

Recognition Agent

cd agent
cp .env.example .env

PowerShell:

cd agent
Copy-Item .env.example .env

For a laptop-camera development run, keep:

HARDWARE_MODE=development
CAMERA_INDEX=0
BACKEND_URL=http://localhost:8000

For Raspberry Pi hardware, set HARDWARE_MODE=raspberry_pi, configure the camera, and wire the LED indicator using BCM GPIO numbers:

LED_GRANTED_GPIO_PIN=17
LED_CALIBRATING_GPIO_PIN=27
LED_DENIED_GPIO_PIN=22

Then start the agent:

cd agent
docker compose up --build

If Docker camera passthrough is not suitable, use the direct Python option in agent/SETUP.md.

Smoke Check

1. Start backend and database.
2. Start the frontend.
3. Start the recognition agent with a development camera or simulated camera.
4. Register or log in as an administrator.
5. Add a disposable test person with reference photos.
6. Rebuild or reload the recognition model from the UI/API.
7. Trigger a recognition attempt or inspect simulated/offline behavior.
8. Verify access events appear in Dashboard/Access Logs.
9. Verify System shows backend/device/camera/recognition status.
10. On Raspberry Pi hardware, verify LED states:
    • blue: access granted / manual open signal;
    • yellow: calibration or operator-attention signal;
    • red: unknown or denied access signal.

Verification Commands

Backend tests:

cd backend-service
pytest tests/unit -v
pytest tests/integration -v
pytest tests/qrt -m qrt -v

Frontend build and helper tests:

cd frontend/faceguard-web
npm ci
npm run build
npm test -- --run

Documentation:

mkdocs build --strict

Deployment configuration:

docker compose -f backend-service/docker-compose.yml config --quiet

Reports and Releases

• Week 2 report
• Week 3 / MVP v1 report
• Week 4 / v1.1.0 report
• Week 5 / MVP v2 report
• Week 6 / trial release report
• Week 7 / finalization report
• v1.0.0 release
• v1.1.0 release
• v2.0.0 release
• v2.1.0 trial release

License

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