Spaces:
Sleeping
Sleeping
File size: 6,738 Bytes
9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 9e7b45f 3aa98cf 11bf621 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 | ---
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
1. Overview
2. System Architecture
3. Caching Architecture
4. Configuration and Environment Variables
5. Local Run (Docker-only)
6. Hugging Face Spaces Deployment
7. API and Data Notes
8. 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
1. React frontend is built during Docker image build.
2. Flask serves API routes and built frontend assets.
3. Gunicorn runs Flask workers.
4. Redis cache is started in-container by entrypoint for cache-backed responses.
### Project Structure (high-level)
- `backend/app`: Flask app, routes, services, extensions
- `frontend/src`: React application
- `Dockerfile`: multi-stage image build and runtime
- `docker-entrypoint.sh`: starts Redis and then application process
### Dashboard Layout Persistence (MongoDB)
Faculty widget positions are stored in MongoDB collection `faculty_layouts`:
- `desktop_layout` for 12-column layout
- `mobile_layout` for 6-column layout
Server-side constraints ensure:
- layout sanitization
- vertical gravity compaction
- bounds checking per breakpoint
Endpoints:
- `GET /api/faculty/dashboard/layout`
- `POST /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.py`
- `backend/app/routes/api_routes.py`
### Cache backend behavior
- If `CACHE_REDIS_URL` is set, Redis is used.
- If unavailable, app can fall back to in-memory cache (`SimpleCache`).
- Docker image defaults are Redis-friendly and start `redis-server` in-container.
### TTL defaults
- `CACHE_DEFAULT_TIMEOUT=60`
- `DASHBOARD_CACHE_TTL=60`
- `REPORT_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 string
- `MONGODB_DB`: database name (example: `attendance_db`)
- `SECRET_KEY`: Flask session secret
### Common optional
- `PORT` (default `7860`)
- `BASE_DIR` (important on ephemeral environments)
- `INFERENCE_SERVICE_URL`
- `FACE_RECOGNITION_MODE`
### Caching
- `CACHE_TYPE` (default in container: `RedisCache`)
- `CACHE_REDIS_URL` (default in container: `redis://127.0.0.1:6379/0`)
- `CACHE_DEFAULT_TIMEOUT`
- `DASHBOARD_CACHE_TTL`
- `REPORT_CACHE_TTL`
To force in-memory caching only:
- set `CACHE_TYPE=SimpleCache`
## 5) Local Run (Docker-only)
No Docker Compose is required.
### Build
```bash
docker build -t facemarkpro:latest .
```
### Run (minimum)
```bash
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)
```bash
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
1. Create a new Space.
2. Choose Docker SDK.
3. Push this repository.
### Required Space secrets/variables
- `MONGO_URI` (secret)
- `MONGODB_DB` (variable, default `attendance_db`)
- `SECRET_KEY` (secret)
Optional:
- `BASE_DIR` (defaults to `/tmp` behavior in app logic)
- `INFERENCE_SERVICE_URL`
- `FACE_RECOGNITION_MODE`
- cache TTL overrides
### Port and process
- Frontmatter sets `app_port: 7860`.
- Gunicorn binds to `${PORT}` (default `7860`).
### Post-deploy verification
- `GET /health` returns `200`
- 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/whoami` should be used to verify active role and identity.
### Student dashboard payload
Student dashboard endpoint returns:
- `todayClasses`
- `attendanceSummary`
- `recentAttendance`
- `weeklyHeaders`
- `weeklyTimetable`
### 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_layouts` collection is writable
- check `POST /api/faculty/dashboard/layout` response
### 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/whoami` and 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_TTL` and `REPORT_CACHE_TTL`
### Space build fails
- root-level `Dockerfile` must 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. |