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.