# 🎯 Sistem Presensi Cerdas Berbasis Pengenalan Wajah & Geofencing
### *AI-Powered Face Biometric & Geolocation Attendance System*
[](https://python.org)
[](https://fastapi.tiangolo.com)
[](https://www.mysql.com)
[](https://react.dev)
[](https://vitejs.dev)
[](https://expo.dev)
[](https://reactnative.dev)
[](https://pytorch.org)
Solusi absensi modern, presisi, dan aman yang mengintegrasikan Computer Vision, Deep Learning, deteksi anti-spoofing wajah secara real-time, dan validasi radius lokasi GPS (Geofencing).
[Fitur Utama](#-fitur-utama) •
[Arsitektur AI](#-arsitektur--pipeline-biometrik) •
[Struktur Proyek](#-struktur-repositori) •
[Panduan Instalasi](#-panduan-instalasi--instalasi-cepat) •
[Dokumentasi API](#-dokumentasi-api) •
[Keamanan & Privasi](#-keamanan--privasi-data)
---
## 📖 Tentang Proyek
Sistem Presensi Pengenalan Wajah ini dirancang untuk mengatasi kecurangan absensi (*titip absen*, spoofing foto/layar digital) dan mempermudah rekapitulasi data kehadiran akademik secara *real-time*.
Platform ini mengadopsi arsitektur multi-klien:
1. **Backend API (`FastAPI`)**: Mesin backend asinkron berperforma tinggi yang menangani pipeline Machine Learning, manajemen database, dan otentikasi JWT.
2. **Web Dashboard (`React 19 + Vite`)**: Panel admin dan dosen untuk manajemen master data akademik, penjadwalan kelas, konfigurasi zona geofencing, hingga rekapitulasi dan ekspor laporan presensi.
3. **Aplikasi Mobile (`Expo / React Native`)**: Aplikasi mahasiswa untuk melakukan presensi mandiri dengan kamera live dan validasi koordinat GPS di area kelas.
---
## ✨ Fitur Utama
- 👤 **Pipeline Biometrik Wajah Multi-Tahap**:
- **Deteksi Wajah**: Menggunakan **YuNet** (ONNX runtime) yang ringan dan sangat akurat menangani berbagai sudut dan pencahayaan.
- **Anti-Spoofing (Liveness Detection)**: Menggunakan model **Silent-Face-Anti-Spoofing** (PyTorch) untuk mencegah penipuan presensi menggunakan foto cetak, replika, atau layar gawai.
- **Ekstraksi Fitur**: Menggunakan **MobileFaceNet** untuk mengekstrak vektor embedding biometrik berdimensi tinggi.
- **Pencarian Cepat & Fusi Skor**: Menggunakan **FAISS Indexing** dan tekstur **LBPH** dengan *Adaptive Score Fusion* untuk verifikasi identitas mahasiswa dalam hitungan milidetik.
- 📍 **Geofencing & Validasi Lokasi Presisi**:
- Penentuan titik lokasi kelas berbasis radius lingkaran atau poligon interaktif menggunakan Leaflet / OpenStreetMap.
- Pengecekan koordinat GPS mahasiswa secara *real-time* via Expo Location untuk memastikan mahasiswa berada di ruangan kelas saat presensi dibuka.
- 🔐 **Autentikasi & Keamanan Ketat**:
- Menggunakan JSON Web Token (JWT) berbasis OAuth2 Password Bearer.
- Role-based Access Control (Admin, Dosen, Mahasiswa).
- 📊 **Manajemen Akademik Komprehensif**:
- Pengelolaan Program Studi, Angkatan, Golongan, Kelas, Mata Kuliah, Dosen, dan Mahasiswa.
- Penjadwalan pertemuan terstruktur, log riwayat deteksi wajah, dan ekspor data presensi ke format Excel (`.xlsx`).
---
## 🧠 Arsitektur & Pipeline Biometrik
```mermaid
flowchart TD
subgraph Client ["📱 Klien (Mobile / Web)"]
Cam["📸 Live Camera Feed"]
GPS["📍 Real-Time GPS Coordinate"]
end
subgraph BackendGateway ["🛡️ Backend Gateway (FastAPI)"]
Auth["OAuth2 / JWT Verification"]
GeoCheck{"Validasi Radius Geofencing?"}
end
subgraph AIPipeline ["🧠 AI Pipeline (ModelBaru)"]
Det["Face Detection\n(YuNet ONNX)"]
AntiSpoof{"Anti-Spoofing Check\n(SilentFace PyTorch)"}
Embed["Feature Extraction\n(MobileFaceNet 512-d)"]
Match["Vector Similarity Search\n(FAISS + LBPH Score Fusion)"]
end
subgraph Database ["🗄️ Database & Storage"]
MySQL[("MySQL 8.0\n20 Tables")]
FAISScache[("Vector Cache & Index")]
end
Cam --> Auth
GPS --> Auth
Auth --> GeoCheck
GeoCheck -- "❌ Di luar radius" --> RejectGeo["Tolak: Lokasi di luar batas"]
GeoCheck -- "✅ Valid" --> Det
Det --> AntiSpoof
AntiSpoof -- "❌ Spoofing Terdeteksi" --> RejectSpoof["Tolak: Wajah Tidak Hidup / Fake"]
AntiSpoof -- "✅ Real Human" --> Embed
Embed --> Match
Match <--> FAISScache
Match -- "✅ Kecocokan Terpenuhi" --> Record["Simpan Status Hadir"]
Record --> MySQL
```
---
## 🛠️ Tech Stack
| Layer | Teknologi | Deskripsi |
| :--- | :--- | :--- |
| **Backend** | Python 3.11, FastAPI, SQLAlchemy, Uvicorn | RESTful API berkecepatan tinggi, ORM terstruktur, OpenAPI auto-docs |
| **Database** | MySQL 8.0 | Penyimpanan relasional terindeks untuk data akademik dan transaksi presensi |
| **AI / Computer Vision** | OpenCV, ONNX Runtime, PyTorch, FAISS | YuNet (Detection), MobileFaceNet (Embedding), SilentFaceAntiSpoofing (Liveness) |
| **Web Dashboard** | React 19, Vite, Tailwind CSS, React-Leaflet | Antarmuka web responsif dengan visualisasi peta geofencing dan tabel interaktif |
| **Aplikasi Mobile** | React Native, Expo SDK 54, Expo Router, Expo Camera | Aplikasi mobile Android dengan akses kamera native dan sensor GPS berakurasi tinggi |
---
## 📂 Struktur Repositori
```text
facerecognition_presensi/
├── backend/ # REST API FastAPI & Manajemen Database
│ ├── app/
│ │ ├── config/ # Konfigurasi aplikasi & database
│ │ ├── controllers/ # Logika bisnis dan handler
│ │ ├── models/ # Definisi model tabel SQLAlchemy (20 tabel)
│ │ ├── routes/ # Router endpoint modular (auth, presensi, dll.)
│ │ ├── schemas/ # Skema validasi Pydantic
│ │ └── services/ # Layanan biometrik, geolokasi, & token
│ ├── init_db.py # Inisialisasi skema tabel database
│ ├── seed.py # Pembuatan akun Super Admin interaktif
│ ├── requirements.txt # Dependensi pustaka Python
│ └── .env.example # Contoh variabel lingkungan backend
├── ModelBaru/ # Core AI Pipeline (YuNet, MobileFaceNet, FAISS)
│ ├── models/ # Model bobot ONNX (YuNet, MobileFaceNet)
│ ├── resources/ # Model bobot PyTorch Anti-Spoofing
│ ├── enhanced_system.py # Koordinator sistem biometrik terpadu
│ ├── anti_spoof_manager.py # Modul deteksi liveness / anti-spoof
│ └── faiss_gallery.py # Pengindeksan & pencarian vektor embedding
├── SilentFaceAntiSpoofing/ # Pustaka pendukung deteksi anti-spoofing
├── Website/ # Web Dashboard Admin & Dosen
│ ├── src/ # Komponen UI, Halaman, dan Konfigurasi Route
│ ├── package.json # Dependensi frontend React 19 & Tailwind
│ └── .env.example # Contoh variabel lingkungan frontend
└── AndroidFolder/ # Aplikasi Mobile Mahasiswa
├── app/ # Routing navigasi (Expo Router)
├── package.json # Dependensi Expo SDK 54 & React Native
└── .env.example # Contoh konfigurasi URL API mobile
```
---
## 🚀 Panduan Instalasi & Menjalankan Sistem
### 📋 Prasyarat Sistem
Pastikan perangkat Anda telah terpasang:
- **Python**: Versi `3.10` atau `3.11` *(Disarankan 3.11 untuk kompatibilitas ONNX/TensorFlow)*
- **Node.js**: Versi `20.19+` atau `22.12+` dan npm
- **Database**: MySQL Server 8.x aktif
- **Mobile Development**: Expo Go pada perangkat Android fisik atau Android Studio Emulator
---
### 1️⃣ Konfigurasi Database (MySQL)
Buka MySQL Client / phpMyAdmin / DBeaver, lalu buat database dan pengguna khusus:
```sql
CREATE DATABASE skripsi_presensi CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'presensi_app'@'localhost' IDENTIFIED BY 'PasswordKuatAnda123!';
GRANT ALL PRIVILEGES ON skripsi_presensi.* TO 'presensi_app'@'localhost';
FLUSH PRIVILEGES;
```
---
### 2️⃣ Konfigurasi & Menjalankan Backend
Buka terminal PowerShell pada direktori root proyek:
```powershell
# 1. Masuk ke folder backend
cd backend
# 2. Buat virtual environment Python 3.11
py -3.11 -m venv venv
.\venv\Scripts\Activate.ps1
# 3. Perbarui pip dan pasang pustaka
python -m pip install --upgrade pip
pip install -r requirements.txt
# 4. Buat file .env dari template
Copy-Item .env.example .env
```
Buka dan sesuaikan file `backend/.env`:
```env
DB_HOST=localhost
DB_PORT=3306
DB_USER=presensi_app
DB_PASSWORD=PasswordKuatAnda123!
DB_NAME=skripsi_presensi
# Generate secret key dengan: python -c "import secrets; print(secrets.token_hex(32))"
SECRET_KEY=masukkan_secret_key_acak_minimal_32_karakter_disini
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=60
DEBUG=false
FACE_MODEL_TYPE=enhanced
PRELOAD_ML_MODEL=false
UPLOAD_DIR=uploads
DATASET_DIR=datasets
```
Inisialisasi tabel database dan buat akun Admin pertama:
```powershell
# Inisialisasi 20 tabel database otomatis
python init_db.py
# Buat akun Admin utama secara interaktif
python seed.py
# Jalankan server FastAPI
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```
> 🌐 **Backend aktif di**: `http://localhost:8000`
> 📑 **Dokumentasi Swagger API**: `http://localhost:8000/api/docs`
> 💓 **Health Check**: `http://localhost:8000/api/health`
---
### 3️⃣ Menjalankan Web Dashboard (React + Vite)
Buka terminal baru dari root direktori proyek:
```powershell
cd Website
# Pasang dependensi
npm ci
# Siapkan file environment
Copy-Item .env.example .env
```
Pastikan isi `Website/.env` mengarah ke backend Anda:
```env
VITE_API_BASE_URL=http://localhost:8000/api/v1
```
Jalankan server pengembangan:
```powershell
npm run dev
```
> 💻 Akses dashboard melalui browser pada tautan lokal yang ditampilkan Vite (biasanya `http://localhost:5173`).
---
### 4️⃣ Menjalankan Aplikasi Mobile (Expo / Android)
Buka terminal baru dari root direktori proyek:
```powershell
cd AndroidFolder
# Pasang dependensi
npm ci
# Siapkan file environment
Copy-Item .env.example .env
```
Edit file `AndroidFolder/.env`:
- **Jika menggunakan Android Emulator**:
```env
EXPO_PUBLIC_API_URL=http://10.0.2.2:8000
```
- **Jika menggunakan Perangkat HP Fisik (Expo Go)**:
```env
EXPO_PUBLIC_API_URL=http://192.168.x.x:8000
```
*(Ganti `192.168.x.x` dengan alamat IPv4 LAN komputer Anda yang satu jaringan Wi-Fi dengan HP)*.
Mulai aplikasi Expo:
```powershell
npm start
```
Scan QR code yang muncul di terminal menggunakan aplikasi **Expo Go** pada smartphone Android Anda.
---
## 🧭 Alur Kerja Penggunaan Pertama Kali
```text
1. Login Admin di Web Dashboard
└── Buat data master: Program Studi, Angkatan, Golongan, Kelas, Dosen, Mahasiswa.
│
2. Pendaftaran Wajah (Enrollment)
└── Ambil/unggah foto wajah mahasiswa berwenang untuk membentuk template embedding biometrik.
│
3. Konfigurasi Jadwal & Pertemuan
└── Tentukan lokasi kelas (titik koordinat & radius geofence) dan buka sesi pertemuan.
│
4. Presensi Mandiri Mahasiswa (Mobile)
└── Mahasiswa membuka aplikasi -> Verifikasi lokasi GPS -> Pindai wajah (Liveness + Face Match).
│
5. Rekapitulasi & Monitoring
└── Admin/Dosen memantau data kehadiran live dan dapat mengunduh rekapitulasi nilai presensi ke Excel.
```
---
## 📡 Ringkasan Endpoint API
Dokumentasi lengkap dan interaktif dapat diuji langsung melalui Swagger UI di `http://localhost:8000/api/docs`.
| Modul | Method | Endpoint | Deskripsi |
| :--- | :---: | :--- | :--- |
| **Auth** | `POST` | `/api/v1/auth/login` | Otentikasi pengguna & generate JWT bearer token |
| **Akademik** | `GET/POST` | `/api/v1/mahasiswa/` | Manajemen data mahasiswa |
| | `GET/POST` | `/api/v1/dosen/` | Manajemen data dosen |
| | `GET/POST` | `/api/v1/jadwal/` | Penjadwalan mata kuliah & kelas |
| **Geolokasi** | `GET/POST` | `/api/v1/geolokasi/` | Konfigurasi koordinat dan radius geofencing |
| **Biometrik** | `POST` | `/api/v1/enhanced-recognition/recognize` | Presensi wajah dengan YuNet + Anti-Spoofing + FAISS |
| | `POST` | `/api/v1/arcface-enrollment/enroll` | Pendaftaran sampel wajah mahasiswa baru |
| **Presensi** | `POST` | `/api/v1/presensi/` | Pencatatan transaksi presensi mahasiswa |
| | `GET` | `/api/v1/history-presensi/` | Riwayat dan log deteksi presensi |
---
## 🗄️ Skema Database
Skrip `init_db.py` secara otomatis menginisialisasi 20 tabel relasional yang saling terhubung:
| Kategori | Tabel-tabel Terkait |
| :--- | :--- |
| **Otentikasi & Akun** | `users` |
| **Struktur Akademik** | `prodi`, `angkatan`, `golongan`, `kelas`, `matakuliah` |
| **Sivitas Akademika** | `dosen`, `mahasiswa` |
| **Kurikulum & Kelas** | `penawaran_matakuliah`, `penawaran_kelas`, `pengajar` |
| **Perkuliahan & Jadwal** | `geolokasi`, `jadwal`, `pertemuan`, `pengajar_pertemuan` |
| **Biometrik Wajah** | `dataset_wajah`, `registrasi_wajah`, `log_deteksi` |
| **Presensi & Rekap** | `presensi`, `history_presensi` |
---
## 🔒 Keamanan & Privasi Data
- 🛑 **Jangan Unggah Data Pribadi**: File foto wajah mahasiswa, database dump produksi, dan file cache embedding (`face_metadata.pkl`, `face_mahasiswa/`, `uploads/`, `datasets/`) sudah masuk ke dalam `.gitignore`.
- 🔑 **Kerahasiaan Kunci (.env)**: Selalu gunakan nilai acak `SECRET_KEY` yang unik pada setiap instalasi server. Jangan pernah commit file `.env`.
- 🛡️ **Proteksi Liveness**: Algoritma anti-spoofing aktif secara otomatis menolak masukan gambar dari layar smartphone, tablet, atau kertas foto cetak untuk mencegah kecurangan absensi.
---
## 📄 Lisensi & Kredit
Proyek ini dikembangkan untuk kebutuhan riset dan sistem presensi akademik.
- **Deteksi Wajah**: [OpenCV Zoo YuNet](https://github.com/opencv/opencv_zoo/tree/master/models/face_detection_yunet)
- **Anti-Spoofing**: [Silent-Face-Anti-Spoofing](https://github.com/minivision-ai/Silent-Face-Anti-Spoofing)
- **Pengenalan Wajah**: [MobileFaceNet](https://github.com/sirius-ai/MobileFaceNet_TF)
- **Vector Search**: [FAISS - Meta Research](https://github.com/facebookresearch/faiss)
---