AI Face Attendance Platform

Multi-tenant SaaS attendance platform built phase by phase.

Current Status

• The backend and frontend are wired to persistent storage and live APIs only. No sample organisations, offices, employees, shifts, or monitor devices are auto-created.
• Bootstrap creates roles plus the first super-admin account from environment variables. All tenant data is expected to be created through the application after login.

Phase Plan

1. Phase 1: Setup backend, auth, RBAC, DB
2. Phase 2: Super admin + organisation CRUD
3. Phase 3: Office + employee CRUD
4. Phase 4: Photo upload + validation
5. Phase 5: AI embedding + FAISS
6. Phase 6: Monitor + camera + attendance
7. Phase 7: Anti-spoof + mask + multi-face
8. Phase 8: Shifts + rules
9. Phase 9: Reports
10. Phase 10: UI polish + Docker + tests hardening

Phase 1-10 Delivered

• FastAPI backend scaffold under backend/
• SQLAlchemy 2.0 models for:
  • roles
  • organisations
  • offices
  • employees
  • employee_photos
  • employee_face_embeddings
  • monitor_devices
  • attendance_logs
  • recognition_events
  • shifts
  • shift_rules
  • employee_shift_assignments
  • users
  • audit_logs
  • impersonation_logs
• Soft-delete support fields on phase-1 entities where required:
  • is_active
  • deleted_at
• JWT authentication
• Password hashing
• RBAC dependency guards
• Standard API response envelope:

{
  "success": true,
  "message": "string",
  "data": {},
  "errors": []
}

• Alembic migration for initial schema
• Bootstrap command for default roles and the first super admin
• Super admin APIs for:
  • create organisation
  • list organisations
  • update organisation
  • activate/deactivate organisation
  • impersonate organisation admin
• Automatic org admin creation during organisation onboarding
• Login lockout for org-bound users when their organisation is inactive or soft-deleted
• Audit log entries for organisation create/update/status changes
• Impersonation log entries with:
  • actual_user_id
  • acting_as_user_id
  • organisation_id
  • action
  • timestamp
• Automated tests for auth, RBAC, organisation CRUD, impersonation, and tenant lockout after deactivation
• Organisation admin APIs for:
  • create office
  • list offices
  • update office
  • soft delete office
  • create employee
  • list employees
  • update employee
  • soft delete employee
• Employee uniqueness rules scoped per organisation for:
  • employee_code
  • email
  • mobile
• Office timezone validation using IANA timezone names such as Asia/Dubai
• Tenant isolation checks for office and employee operations
• Automated tests for office CRUD, employee CRUD, per-organisation uniqueness, and org-admin route protection
• Employee photo enrollment APIs for:
  • upload employee photo
  • list employee photos
  • delete employee photo
  • get enrollment status
• Local file storage for employee photos under STORAGE_ROOT
• Photo validation for:
  • empty file rejection
  • max upload size
  • JPEG/PNG/WEBP detection by file signature
  • consent-gated biometric enrollment
• Enrollment status tracking with minimum 3 active photos required
• Automated tests for consent enforcement, upload validation, enrollment counting, and file deletion behavior
• Embedding generation per employee photo with DB-backed vectors in employee_face_embeddings
• Rebuildable organisation face index stored under STORAGE_ROOT/indexes/...
• Real provider wiring for:
  • insightface face detection and embeddings
  • faiss vector indexing and search
• Deterministic embedding and JSON index backends remain available only as explicit non-default dev/test modes
• Org-admin APIs for:
  • get embedding status
  • generate embeddings
  • rebuild face index
  • search face index
• Automated tests for minimum-photo embedding prerequisites, embedding generation, face-index rebuild, and similarity search
• Monitor APIs for:
  • list monitor offices
  • start monitor session
  • process recognition frame
• Org-admin APIs for:
  • create monitor user credentials
  • list monitor users
  • list monitor devices
• Attendance flow implemented for monitor scans:
  • first valid scan marks IN
  • next valid scan marks OUT
  • duplicate scans inside the configured window are ignored
  • unknown faces are logged but never marked present
• Device session persistence through monitor_devices
• Recognition and attendance event storage in:
  • recognition_events
  • attendance_logs
• Automated tests for monitor session start, recognition, duplicate prevention, IN/OUT toggling, and unknown-face handling
• Monitor anti-spoof and safety gates for:
  • no-face rejection
  • multi-face rejection
  • liveness failure rejection
  • masked-face confirmation requirement
  • stricter thresholding for masked recognition
• Recognition responses now return:
  • mask_detected
  • liveness_status
  • fallback_required
  • explicit rejection messages for kiosk guidance
• Automated tests for multi-face rejection, liveness failure, masked-face confirmation, and masked successful recognition
• Shift APIs for:
  • create/list/update shifts
  • assign shifts to employees
  • list assignments
  • evaluate attendance for a selected day
• Shift rule support for:
  • grace period
  • late mark
  • half day
  • early exit
  • overtime
  • weekly off
  • holiday dates
  • night shift / cross-day evaluation
• Automated tests for late arrival, early exit, overtime, and night-shift evaluation
• Reporting APIs for:
  • daily summary
  • monthly summary
  • employee-wise report
  • office-wise report
  • shift-wise report
  • late/absent report
  • CSV export
• Report generation reuses the shift evaluation engine so attendance classification is consistent across monitor flow, evaluation, and reports
• Automated tests for daily summary, late/absent filtering, and CSV export
• Deployment packaging:
  • backend Dockerfile
  • frontend Dockerfile
  • root docker-compose.yml for backend + frontend + PostgreSQL
• React frontend shell under frontend/ with:
  • unified login
  • super admin organisation view
  • org admin operational panels
  • monitor session and frame-submit screen
• Final verification completed for:
  • backend automated test suite
  • frontend production build
  • Docker Compose configuration parsing
• Manual attendance correction endpoints with required reason and audit log entries
• Browser monitor frontend now supports:
  • Webcam API preview
  • Fullscreen monitor mode
  • periodic frame capture
  • camera permission / no-camera / disconnect handling
  • offline frame queue with retry after reconnect
  • backend-derived face count and liveness handling instead of browser-supplied recognition flags

Local Run

The current implementation defaults to SQLite for local verification. PostgreSQL remains the target production database and can be enabled through DATABASE_URL.

cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -e '.[dev,ai]'
cp .env.example .env
alembic upgrade head
python -m app.db.init_data
uvicorn app.main:app --reload

Set FIRST_SUPERADMIN_EMAIL and FIRST_SUPERADMIN_PASSWORD in backend/.env before running python -m app.db.init_data. The bootstrap command will stop if the placeholder admin password is still present.

Provision the InsightFace model pack locally under STORAGE_ROOT/models/insightface/models/buffalo_l before using photo embedding generation, face search, or monitor recognition. The backend no longer falls back to downloading model assets at runtime.

Open http://127.0.0.1:8000/docs.

For the packaged stack:

docker compose up --build

Then open:

• Frontend: http://127.0.0.1:3000
• Backend docs: http://127.0.0.1:8000/docs

Frontend verification:

cd frontend
npm install --cache /tmp/afras-npm-cache
npm run build

Bootstrap Credentials

The bootstrap command reads these values from .env:

• FIRST_SUPERADMIN_EMAIL=admin@your-domain.com
• FIRST_SUPERADMIN_PASSWORD=replace-this-before-first-run
• STORAGE_ROOT=./storage
• EMPLOYEE_PHOTO_MAX_SIZE_MB=5
• FACE_EMBEDDING_PROVIDER=insightface
• FACE_INDEX_BACKEND=faiss
• FACE_ANALYSIS_MODEL_NAME=buffalo_l
• FACE_ANALYSIS_MODEL_ROOT=./storage/models/insightface
• MONITOR_SIGNAL_SOURCE=backend
• FACE_MATCH_THRESHOLD=0.98
• ATTENDANCE_DUPLICATE_WINDOW_MINUTES=5

No other data is bootstrapped.

Verified Endpoints

• GET /api/v1/health
• POST /api/v1/auth/login
• GET /api/v1/auth/me
• GET /api/v1/auth/rbac-check
• GET /api/v1/org-admin/offices
• POST /api/v1/org-admin/offices
• PATCH /api/v1/org-admin/offices/{office_id}
• DELETE /api/v1/org-admin/offices/{office_id}
• GET /api/v1/org-admin/employees
• POST /api/v1/org-admin/employees
• PATCH /api/v1/org-admin/employees/{employee_id}
• DELETE /api/v1/org-admin/employees/{employee_id}
• GET /api/v1/org-admin/employees/{employee_id}/photos
• POST /api/v1/org-admin/employees/{employee_id}/photos
• DELETE /api/v1/org-admin/employees/{employee_id}/photos/{photo_id}
• GET /api/v1/org-admin/employees/{employee_id}/enrollment-status
• GET /api/v1/org-admin/employees/{employee_id}/embedding-status
• POST /api/v1/org-admin/employees/{employee_id}/embeddings/generate
• POST /api/v1/org-admin/face-index/rebuild
• POST /api/v1/org-admin/face-search
• GET /api/v1/org-admin/monitor-users
• POST /api/v1/org-admin/monitor-users
• GET /api/v1/org-admin/monitor-devices
• GET /api/v1/org-admin/shifts
• POST /api/v1/org-admin/shifts
• PATCH /api/v1/org-admin/shifts/{shift_id}
• GET /api/v1/org-admin/shift-assignments
• POST /api/v1/org-admin/shift-assignments
• GET /api/v1/org-admin/attendance-evaluation
• GET /api/v1/org-admin/reports/daily
• GET /api/v1/org-admin/reports/monthly
• GET /api/v1/org-admin/reports/employee
• GET /api/v1/org-admin/reports/office
• GET /api/v1/org-admin/reports/shift
• GET /api/v1/org-admin/reports/late-absent
• GET /api/v1/org-admin/reports/export/csv
• GET /api/v1/org-admin/attendance-logs
• PATCH /api/v1/org-admin/attendance-logs/{attendance_log_id}/manual-correction
• GET /api/v1/monitor/offices
• POST /api/v1/monitor/session/start
• POST /api/v1/monitor/recognize
• GET /api/v1/super-admin/organisations
• POST /api/v1/super-admin/organisations
• PATCH /api/v1/super-admin/organisations/{organisation_id}
• PATCH /api/v1/super-admin/organisations/{organisation_id}/status
• POST /api/v1/super-admin/impersonations/{target_user_id}

Notes For Next Phase

• The repository now defaults to backend-owned recognition inputs rather than browser-supplied demo flags.
• A local InsightFace model pack and AI runtime dependencies are still required in the target environment for enrollment, indexing, and live recognition.