face-attendance/README.md

Face Attendance

Face Attendance is a modern Flask application for managing attendance with face recognition. It includes staff authentication, role-based authorization, person enrollment, a webcam kiosk, attendance reporting, database migrations, and a responsive English UI.

Features

• Application factory pattern with modular Blueprints.
• Admin-created staff accounts with admin, operator, and viewer roles.
• Secure login/logout with Flask-Login and Werkzeug password hashing.
• CSRF-protected forms and secure session/cookie defaults.
• Person enrollment with one to four face reference images.
• Webcam-based recognition kiosk for check-in and check-out events.
• Attendance reports with person, timestamp, source, confidence, and staff user.
• SQLAlchemy models with Flask-Migrate/Alembic migrations.
• Pytest coverage for authentication, roles, and attendance behavior.
• Modern Bootstrap-based UI with an English welcome page.

Roles

Role	Permissions
admin	Manage staff accounts, enroll people, use the kiosk, and view reports.
operator	Enroll people, use the kiosk, and view reports.
viewer	View people and attendance reports only.

Only admins can create staff accounts.

Requirements

• Python 3.11 or 3.12 is recommended for production.
• Native build prerequisites for face-recognition and dlib.
• SQLite for local development, or PostgreSQL/MySQL for production.
• A production WSGI server such as Gunicorn on Linux or Waitress on Windows.

Project Structure

app/
  __init__.py          Application factory
  config.py            Environment-based configuration
  extensions.py        Flask extensions
  auth/                Login/logout
  admin/               Staff account management
  attendance/          Kiosk and attendance reports
  people/              Person enrollment and profiles
  recognition/         Recognition API routes
  models/              SQLAlchemy models
  services/            Business logic
  templates/           Jinja templates
  static/              CSS, JS, and images
migrations/            Alembic migrations
tests/                 Pytest suite
wsgi.py                WSGI entrypoint

Setup

py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
Copy-Item .env.example .env

Edit .env before running the app.

APP_ENV=development
SECRET_KEY=replace-with-a-long-random-secret
DATABASE_URL=sqlite:///instance/face_attendance.sqlite3
FACE_MATCH_TOLERANCE=0.55
MAX_CONTENT_LENGTH=8388608

Database

Apply migrations:

$env:FLASK_APP = "wsgi:app"
flask db upgrade

Create the first admin account:

flask create-admin

Run Locally

$env:FLASK_APP = "wsgi:app"
flask run

Open http://127.0.0.1:5000.

Tests

pytest

The test suite uses an in-memory SQLite database and disables CSRF only for test requests.

Production Deployment

1. Set APP_ENV=production.
2. Set a strong SECRET_KEY.
3. Set DATABASE_URL to your production database.
4. Install native dependencies for face-recognition/dlib.
5. Run flask db upgrade.
6. Serve through a production WSGI server behind HTTPS.
7. Configure your reverse proxy to forward HTTPS headers correctly.

Production config enables secure cookies. Do not run the Flask development server in production.

Security Notes

• Face encodings are biometric data. Restrict database access and define a retention policy.
• Keep .env out of version control.
• Use HTTPS in production.
• Rotate staff accounts when operators leave the organization.
• Review database backups and access logs regularly.

Troubleshooting

• If recognition endpoints return a dependency error, install face-recognition on Python 3.11 or 3.12 with the required dlib build tools.
• If the default Flask port is blocked on Windows, run flask run --port 8000.
• If database tables are missing, run flask db upgrade.