Absense

Smart multi-layered attendance verification system with biometric verification, geolocation, device binding, and role-based access control for educational institutions.

Features

• Multi-layered verification — QR codes (30-second rotation), GPS geofencing, device ID binding, and facial recognition
• Role-based access — Separate dashboards and workflows for students, lecturers, and administrators
• Cross-platform — Web app (Next.js) and mobile app (React Native / Expo) for students
• Lecturer tools — Create sessions, display rotating QR codes, capture GPS location, manage geofence radius, view attendance reports
• Admin oversight — Manage courses, users, sessions, flagged records, device resets, and manual attendance overrides
• Student check-in — QR scan + selfie + geolocation on each attendance submission

Tech Stack

• Backend: FastAPI, PostgreSQL, SQLAlchemy, Alembic
• Web: Next.js 16, React 19, Tailwind CSS, Radix UI
• Mobile: Expo (React Native), Expo Router
• Verification: DeepFace (facial), QR rotation, GPS geofencing
• Language: TypeScript (web, mobile), Python (backend)

Prerequisites

• Node.js 18+
• Python 3.10+
• PostgreSQL (for production) or SQLite (for development)

Getting Started

1. Clone and install

git clone https://github.com/your-username/attendance-app.git
cd attendance-app

Backend:

cd backend
python -m venv .venv
source .venv/bin/activate   # or .venv\Scripts\activate on Windows
pip install -r requirements.txt

Web:

cd web
npm install

Mobile (optional):

cd mobile
npm install

2. Environment variables

Variable	Required	Description
Backend (backend/.env)
SECRET_KEY	Yes	Secret for JWT signing
DATABASE_URL	Yes	sqlite:///./absense_dev.db (dev) or PostgreSQL URL (prod)
CORS_ALLOW_ORIGINS	Yes	* (dev) or allowed origins (prod)
Web (web/.env.local)
NEXT_PUBLIC_API_URL	Yes	http://localhost:8000/api/v1
NEXT_PUBLIC_ADMIN_PORTAL_CODE	No	Admin portal password (default: AdminPortal123!)
Mobile (mobile/constants/config.ts)
BASE_URL	Yes	http://YOUR_LOCAL_IP:8000/api/v1 (use your machine's IP for device testing)

3. Run the app

Web development (backend + Next.js):

./start-dev.sh

• Web app: http://localhost:3000
• API: http://localhost:8000
• API docs: http://localhost:8000/docs

Mobile development (backend + Expo):

./start-mobile.sh

Update mobile/constants/config.ts with your local IP. Scan the QR code with Expo Go.

See backend/README.md for migrations, seeding, and production deployment.

4. Create admin (local or production)

cd backend
python scripts/init_fresh_db.py   # first time only
python scripts/create_admin.py

Edit scripts/create_admin.py for email/password. Other users register through the app.

Project Structure

attendance-app/
├── backend/              # FastAPI backend
│   ├── app/              # Application code
│   └── scripts/          # Admin, DB init, face worker, migrations
├── web/                  # Next.js web application
│   ├── app/              # App router (student, lecturer, admin routes)
│   │   ├── admin/        # Admin dashboard & pages
│   │   ├── lecturer/     # Lecturer dashboard & pages
│   │   └── student/      # Student dashboard & mark-attendance
│   ├── components/      # Shared UI components
│   └── lib/              # API client, utilities
├── mobile/               # Expo React Native app (student-focused)
│   ├── app/              # Expo Router screens
│   ├── screens/          # Screen components
│   └── components/      # Reusable components
├── start-dev.sh          # Start web + backend
└── start-mobile.sh       # Start mobile + backend

Scripts

Command	Description
./start-dev.sh	Start backend + web dev servers
./start-mobile.sh	Start backend + Expo for mobile
cd backend && ./scripts/dev.sh	Backend only (port 8000)
cd web && npm run dev	Web only (port 3000)
cd mobile && npx expo start	Mobile only
cd backend && python scripts/create_admin.py	Create admin user
cd backend && ./scripts/migrate.sh	Run Alembic migrations (existing DB)

Application Functionality

Student

• Web: Dashboard with enrolled courses, attendance stats, mark attendance (QR scan + selfie + location), course enrollment
• Mobile: Same flow with camera-based QR scanning, face capture, and geolocation
• Verification: One-time face enrollment, device binding, QR + selfie + GPS on each check-in

Lecturer

• Web: Create and manage courses, create attendance sessions with optional GPS capture, display rotating QR codes, set geofence radius, view attendance lists, confirm/flag records, session analytics

Admin

• Web: Dashboard, manage courses and users, view all sessions and attendance, review flagged records, approve device resets, manual attendance override, activity logs

API Overview

Base URL: http://localhost:8000/api/v1

Area	Key Endpoints
Auth	POST /auth/register, POST /auth/login, GET /auth/me
Student	POST /student/enroll-face, POST /student/device/bind, POST /student/attendance, GET /student/courses
Lecturer	GET/POST /lecturer/courses, POST /lecturer/sessions, GET /lecturer/qr/{id}/display, GET /lecturer/sessions/{id}/attendance
Admin	GET /admin/users, GET /admin/sessions, POST /admin/attendance/manual-mark, GET /admin/flagged

Full API documentation: http://localhost:8000/docs

Deploy

The web app can be deployed to Vercel or any Node.js host. The backend can run on any Python host (e.g. systemd + Gunicorn). Add the same environment variables in your deployment platform. For production, use PostgreSQL and set CORS_ALLOW_ORIGINS to your frontend URL(s).

License

Proprietary. All rights reserved.