How aksubudhi/attendance-system works
Project type and purpose
• Full-stack attendance system with a decoupled React frontend (Vite) and Python FastAPI backend
• Purpose: real-time facial recognition attendance tracking, camera configuration, user management, and reporting
File structure
• Top-level “frontend” and “backend” directories
– frontend/src: React pages (Attendance, Cameras, Dashboard, Employees, Login) and reusable components
– backend: FastAPI entrypoint (api.py), core logic (services.py), DB setup (setup_db.py), configuration, static assets and templates for fallback/SSR if used
• Config and environment files: backend/config.py, Dockerfile, .gitignore, package.json, requirements.txt
• WebSocket and RTSP integration indicated by camera_urls.json, attendance.js, and WebSocket client code in frontend/api/client.js
README for additional insights
• Architecture: clearly split into Python FastAPI server + React application
• Tech stack: React, Vite, FastAPI, PostgreSQL with pgvector, insightface, FAISS, JWT auth, WebSockets
• Features: real-time camera feeds, face embedding storage/search, protected routes, Excel export
a. Main components
1. External RTSP Cameras (source of video frames)
2. Frontend (React + Vite)
– UI pages, WebSocket client for live feeds, HTTP client for REST endpoints
3. API Gateway / FastAPI Server
– REST endpoints (employee management, auth, logs, config)
– WebSocket endpoint for streaming processed frames and attendance events
4. Face Recognition Service (insightface + FAISS)
– Processes incoming frames, extracts embeddings, performs identification
5. PostgreSQL Database with pgvector
– Stores user profiles, face embeddings (vectors), attendance logs, camera configs
6. JWT Authentication Module
– Issues and verifies tokens for protected routes
b. Relationships and interactions
• Cameras → FastAPI (pulls or receives frames via RTSP)
• FastAPI → Face Recognition Service (internal function calls in services.py)
• Face Recognition Service → PostgreSQL (store/search embeddings)
• FastAPI WebSocket → Frontend (broadcast processed frames/attendance events)
• Frontend HTTP → FastAPI (CRUD for employees, cameras, logs)
• Frontend UI ←→ JWT Auth (login, protected route gating)
c. Architectural patterns and principles
• Decoupled front-end/back-end (clear separation of concerns)
• Async I/O (FastAPI’s asynchronous endpoints for high throughput)
• Event-driven streaming via WebSockets
• Modular service layer (services.py, client_attendance_api.py)
• Vector similarity search (FAISS + pgvector) for millisecond face identification
d. Key technologies, frameworks, and libraries
• React + Vite for frontend bundling and HMR
• FastAPI + uvicorn for lightweight asynchronous API
• insightface for face detection/embedding
• FAISS for nearest-neighbor search
• PostgreSQL + pgvector for persistent vector store
• JWT for authentication, WebSockets for real‐time updates
Diagramming recommendations
– Blue for frontend/UI
– Green for backend/API
– Orange for external services (face recognition, DB, cameras)