TIF_E41253336/facerecognition_presensi

🎯 Sistem Presensi Cerdas Berbasis Pengenalan Wajah & Geofencing

AI-Powered Face Biometric & Geolocation Attendance System

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 • Arsitektur AI • Struktur Proyek • Panduan Instalasi • Dokumentasi API • Keamanan & Privasi

---

📖 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

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

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:

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:

# 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:

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:

# 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:

cd Website

# Pasang dependensi
npm ci

# Siapkan file environment
Copy-Item .env.example .env

Pastikan isi Website/.env mengarah ke backend Anda:

VITE_API_BASE_URL=http://localhost:8000/api/v1

Jalankan server pengembangan:

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:

cd AndroidFolder

# Pasang dependensi
npm ci

# Siapkan file environment
Copy-Item .env.example .env

Edit file AndroidFolder/.env:

• Jika menggunakan Android Emulator:

  EXPO_PUBLIC_API_URL=http://10.0.2.2:8000
  

• Jika menggunakan Perangkat HP Fisik (Expo Go):

  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:

npm start

Scan QR code yang muncul di terminal menggunakan aplikasi Expo Go pada smartphone Android Anda.

---

🧭 Alur Kerja Penggunaan Pertama Kali

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
• Anti-Spoofing: Silent-Face-Anti-Spoofing
• Pengenalan Wajah: MobileFaceNet
• Vector Search: FAISS - Meta Research

---

_{Dikembangkan dengan dedikasi untuk integritas presensi akademik berbasis Artificial Intelligence.}