# 🎯 Sistem Presensi Cerdas Berbasis Pengenalan Wajah & Geofencing ### *AI-Powered Face Biometric & Geolocation Attendance System* [![Python](https://img.shields.io/badge/Python-3.11-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://python.org) [![FastAPI](https://img.shields.io/badge/FastAPI-0.100+-009688?style=for-the-badge&logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com) [![MySQL](https://img.shields.io/badge/MySQL-8.0-4479A1?style=for-the-badge&logo=mysql&logoColor=white)](https://www.mysql.com) [![React](https://img.shields.io/badge/React-19.0-61DAFB?style=for-the-badge&logo=react&logoColor=black)](https://react.dev) [![Vite](https://img.shields.io/badge/Vite-7.0-646CFF?style=for-the-badge&logo=vite&logoColor=white)](https://vitejs.dev) [![Expo](https://img.shields.io/badge/Expo-SDK_54-000020?style=for-the-badge&logo=expo&logoColor=white)](https://expo.dev) [![React Native](https://img.shields.io/badge/React_Native-0.81-61DAFB?style=for-the-badge&logo=react&logoColor=black)](https://reactnative.dev) [![PyTorch](https://img.shields.io/badge/PyTorch-Anti_Spoofing-EE4C2C?style=for-the-badge&logo=pytorch&logoColor=white)](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) ---
Dikembangkan dengan dedikasi untuk integritas presensi akademik berbasis Artificial Intelligence.