# 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

```text
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

```powershell
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.

```env
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:

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

Create the first admin account:

```powershell
flask create-admin
```

## Run Locally

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

Open `http://127.0.0.1:5000`.

## Tests

```powershell
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`.