Spaces:
Sleeping
Download README.md from jinksQspider/FaceMarkPro2: direct link, hf CLI and curl.
- Browser
- Download file 6.74 kB
-
https://huggingface.co/spaces/jinksQspider/FaceMarkPro2/resolve/main/README.md
- Command line
-
hf download hf://spaces/jinksQspider/FaceMarkPro2/README.md
-
curl -L -o README.md https://huggingface.co/spaces/jinksQspider/FaceMarkPro2/resolve/main/README.md
title: FaceMarkPro - Facial Recognition Attendance System
emoji: 👤
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false
license: mit
app_port: 7860
FaceMarkPro
FaceMarkPro is a full-stack attendance platform that combines facial recognition, attendance workflows, reports, and role-based dashboards for faculty, students, and admins.
This repository is configured for Docker-first deployment and runs cleanly on Hugging Face Spaces (Docker SDK) without Docker Compose.
Table of Contents
- Overview
- System Architecture
- Caching Architecture
- Configuration and Environment Variables
- Local Run (Docker-only)
- Hugging Face Spaces Deployment
- API and Data Notes
- Operations and Troubleshooting
1) Overview
Core Capabilities
- Facial recognition attendance marking (live and uploaded media workflows)
- Faculty and admin dashboards with analytics and reports
- Student dashboard with timetable and attendance views
- Role-based authentication and session-aware routing
- Dashboard layout persistence (faculty desktop and mobile)
Tech Stack
- Backend: Flask + Gunicorn
- Frontend: React + Vite (built static assets served by Flask in production)
- Database: MongoDB
- Caching: Flask-Caching, Redis-backed when configured
- Runtime: single Docker container
2) System Architecture
Runtime Flow
- React frontend is built during Docker image build.
- Flask serves API routes and built frontend assets.
- Gunicorn runs Flask workers.
- Redis cache is started in-container by entrypoint for cache-backed responses.
Project Structure (high-level)
backend/app: Flask app, routes, services, extensionsfrontend/src: React applicationDockerfile: multi-stage image build and runtimedocker-entrypoint.sh: starts Redis and then application process
Dashboard Layout Persistence (MongoDB)
Faculty widget positions are stored in MongoDB collection faculty_layouts:
desktop_layoutfor 12-column layoutmobile_layoutfor 6-column layout
Server-side constraints ensure:
- layout sanitization
- vertical gravity compaction
- bounds checking per breakpoint
Endpoints:
GET /api/faculty/dashboard/layoutPOST /api/faculty/dashboard/layout
3) Caching Architecture
What is cached
Read-heavy JSON payloads are cached:
- Student dashboard API
- Faculty dashboard API
- Admin dashboard API
- Faculty report filters
- Faculty reports
- Admin report filters
- Admin reports
Where cache is implemented
- Cache extension init:
backend/app/extensions.py - App wiring:
backend/app/__init__.py - Cached routes:
backend/app/routes/student_routes.pybackend/app/routes/api_routes.py
Cache backend behavior
- If
CACHE_REDIS_URLis set, Redis is used. - If unavailable, app can fall back to in-memory cache (
SimpleCache). - Docker image defaults are Redis-friendly and start
redis-serverin-container.
TTL defaults
CACHE_DEFAULT_TIMEOUT=60DASHBOARD_CACHE_TTL=60REPORT_CACHE_TTL=120
Important caveat
This cache layer currently optimizes reads by TTL and does not yet do aggressive write-triggered invalidation for every mutation path. For strict freshness, reduce TTL values.
4) Configuration and Environment Variables
Required
MONGO_URI: MongoDB connection stringMONGODB_DB: database name (example:attendance_db)SECRET_KEY: Flask session secret
Common optional
PORT(default7860)BASE_DIR(important on ephemeral environments)INFERENCE_SERVICE_URLFACE_RECOGNITION_MODE
Caching
CACHE_TYPE(default in container:RedisCache)CACHE_REDIS_URL(default in container:redis://127.0.0.1:6379/0)CACHE_DEFAULT_TIMEOUTDASHBOARD_CACHE_TTLREPORT_CACHE_TTL
To force in-memory caching only:
- set
CACHE_TYPE=SimpleCache
5) Local Run (Docker-only)
No Docker Compose is required.
Build
docker build -t facemarkpro:latest .
Run (minimum)
docker run --rm -p 7860:7860 \
-e PORT=7860 \
-e MONGO_URI="<your-mongodb-uri>" \
-e MONGODB_DB="attendance_db" \
-e SECRET_KEY="<your-secret>" \
facemarkpro:latest
Run (with cache overrides)
docker run --rm -p 7860:7860 \
-e MONGO_URI="<your-mongodb-uri>" \
-e MONGODB_DB="attendance_db" \
-e SECRET_KEY="<your-secret>" \
-e DASHBOARD_CACHE_TTL=90 \
-e REPORT_CACHE_TTL=180 \
facemarkpro:latest
Open:
http://localhost:7860
6) Hugging Face Spaces Deployment
Space setup
- Create a new Space.
- Choose Docker SDK.
- Push this repository.
Required Space secrets/variables
MONGO_URI(secret)MONGODB_DB(variable, defaultattendance_db)SECRET_KEY(secret)
Optional:
BASE_DIR(defaults to/tmpbehavior in app logic)INFERENCE_SERVICE_URLFACE_RECOGNITION_MODE- cache TTL overrides
Port and process
- Frontmatter sets
app_port: 7860. - Gunicorn binds to
${PORT}(default7860).
Post-deploy verification
GET /healthreturns200- auth works for all roles
- dashboards load without asset 404
- faculty widget layout save/load works
- reports load and export endpoints respond
7) API and Data Notes
Auth/session
- API auth state is session-based.
/api/auth/whoamishould be used to verify active role and identity.
Student dashboard payload
Student dashboard endpoint returns:
todayClassesattendanceSummaryrecentAttendanceweeklyHeadersweeklyTimetable
Frontend asset serving
Flask serves built assets from frontend dist in production mode and has explicit /assets/<path> handling.
8) Operations and Troubleshooting
Faculty layout not restoring
- verify MongoDB permissions and connectivity
- verify
faculty_layoutscollection is writable - check
POST /api/faculty/dashboard/layoutresponse
Reload shows old hashed asset 404
- ensure production serves matching built assets
- in local dev with Vite, avoid proxying frontend app routes to backend
- hard refresh browser cache
Login role mismatch
- call
/api/auth/whoamiand verify role - clear stale session cookies if switching roles often
APIs slow under load
- confirm cache vars are set
- verify Redis started in container logs
- reduce expensive filter combinations
- tune
DASHBOARD_CACHE_TTLandREPORT_CACHE_TTL
Space build fails
- root-level
Dockerfilemust exist - dependencies must install from
backend/requirements.txt - ensure no private package/network restrictions block
pip
Security Notes
- Never commit real secrets to git.
- Use Spaces secrets (or secure runtime secrets) in production.
- Restrict MongoDB access by IP/network and least-privilege credentials.