add welcome page and README.md

README.md

@@ -1,21 +1,58 @@
 # Face Attendance
 
-A modern Flask attendance application with staff authentication, role-based access control, face enrollment, camera-based recognition, and attendance reporting.
+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
 
-- `admin`: manages staff accounts, enrolls people, records attendance, and views reports.
-- `operator`: enrolls people, uses the attendance kiosk, and views reports.
-- `viewer`: read-only access to people and attendance reports.
+| 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`/`dlib` may be required by your OS.
+- 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
@@ -25,15 +62,28 @@ pip install -r requirements.txt
 Copy-Item .env.example .env
 ```
 
-Edit `.env` and set a strong `SECRET_KEY`. For production, set `APP_ENV=production` and use a durable database URL.
+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
 
-Initialize the database with migrations:
+Apply migrations:
 
 ```powershell
 $env:FLASK_APP = "wsgi:app"
 flask db upgrade
+```
+
+Create the first admin account:
+
+```powershell
 flask create-admin
 ```
 
@@ -44,7 +94,7 @@ $env:FLASK_APP = "wsgi:app"
 flask run
 ```
 
-Open `http://127.0.0.1:5000` and sign in with the admin account created above.
+Open `http://127.0.0.1:5000`.
 
 ## Tests
 
@@ -52,23 +102,30 @@ Open `http://127.0.0.1:5000` and sign in with the admin account created above.
 pytest
 ```
 
-The tests use an isolated SQLite database and disable CSRF only for test requests.
+The test suite uses an in-memory SQLite database and disables CSRF only for test requests.
 
-## Production Notes
+## Production Deployment
 
-- Use HTTPS. Production config enables secure cookies.
-- Set `SECRET_KEY`, `DATABASE_URL`, and `APP_ENV=production`.
-- Run `flask db upgrade` during deployment.
-- Run behind a reverse proxy that forwards HTTPS headers correctly.
-- Treat face encodings as biometric data. Restrict database access, define a retention policy, and back up securely.
+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.
 
-## What Changed
+Production config enables secure cookies. Do not run the Flask development server in production.
 
-- Replaced the legacy single-file Flask script with an application factory and Blueprints.
-- Added SQLAlchemy models and Alembic migrations.
-- Added Flask-Login authentication, admin-created accounts, password hashing, and role checks.
-- Replaced raw SQL with ORM queries.
-- Removed global enrollment state.
-- Rebuilt the UI in English with reusable templates and responsive Bootstrap-based layouts.
-- Added CSRF protection, secure cookie settings, security headers, validation, and error pages.
-- Added pytest coverage for authentication, roles, models, and attendance recording.
+## 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`.