FIVUCSAS is a multi-tenant biometric authentication platform for secure identity verification. It supports ten authentication methods (password, email/SMS OTP, TOTP, QR code, face, voice, fingerprint, hardware key, NFC document) composable into tenant-configured MFA flows, and exposes a production-grade OAuth 2.0 / OIDC authorization server with hosted-first redirective login.
Engineering Project at Marmara University's Computer Engineering Department — CSE4297 / CSE4197.
Our unique active liveness detection algorithm requires users to perform a random sequence of facial actions (smile, blink, look left/right), making it highly resistant to spoofing attacks.
┌──────────────────────────────────────────────────────────────┐
│ FIVUCSAS Platform │
├──────────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌──────────────┐ ┌─────────────────┐ │
│ │ Mobile App │ │ Web App │ │ Desktop App │ │
│ │ (KMP) │ │ (React) │ │ (KMP) │ │
│ └──────┬──────┘ └──────┬───────┘ └────────┬────────┘ │
│ └────────────────┼───────────────────┘ │
│ ┌───────▼────────┐ │
│ │ API Gateway │ │
│ │ (NGINX) │ │
│ └───────┬────────┘ │
│ ┌────────────────┴────────────────┐ │
│ ┌──────▼──────────┐ ┌───────────▼─────────┐ │
│ │ Identity Core │◄────────►│ Biometric │ │
│ │ API (Spring) │ │ Processor (FastAPI)│ │
│ └────────┬────────┘ └───────────┬─────────┘ │
│ ┌────────▼────────┐ ┌───────────▼─────────┐ │
│ │ PostgreSQL │ │ Redis │ │
│ │ + pgvector │ │ (Cache & Queue) │ │
│ └─────────────────┘ └──────────────────────┘ │
└──────────────────────────────────────────────────────────────┘
| Component | Technology | Purpose |
|---|---|---|
| Backend Core | Spring Boot 3.4.7 (Java 21) | Identity & Auth Management, OAuth 2.0 / OIDC |
| AI/ML Service | FastAPI (Python 3.12) | Biometric Processing (DeepFace, MediaPipe, YOLO) |
| Mobile App | Kotlin Multiplatform + Compose | Cross-platform (Android/iOS/Desktop) |
| Web Dashboard | React 18 + TypeScript 5 + Vite 8 | Admin Panel, MUI, InversifyJS DI |
| Hosted Login / Widget | verify.fivucsas.com | Hosted-first redirective + iframe step-up MFA |
| Database | PostgreSQL 17 + pgvector | Data & HNSW vector indexes |
| Cache / Session | Redis 7.4 | OTP TTL, rate limits, JWKS cache |
| Edge / Routing | Traefik v3.6 | TLS, per-route CSP, redirect-URI allowlist |
FIVUCSAS/
├── biometric-processor/ # FastAPI ML service (submodule)
├── identity-core-api/ # Spring Boot microservice (submodule)
├── client-apps/ # Kotlin Multiplatform apps (submodule)
├── web-app/ # React admin dashboard (submodule)
├── spoof-detector/ # Anti-spoof research + browser TypeScript port (submodule)
├── docs/ # Comprehensive documentation (submodule)
├── practice-and-test/ # R&D experiments (submodule)
├── bys-demo/ # BYS demo site → demo.fivucsas.com
├── landing-website/ # Landing page → fivucsas.com
├── links-website/ # Links hub → links.fivucsas.com
├── verify-widget/ # Embeddable auth widget → verify.fivucsas.com
├── docs-site/ # Documentation site → docs.fivucsas.com
├── nginx/ # API Gateway configuration
├── monitoring/ # Prometheus/Grafana configs
├── load-tests/ # Performance testing
├── scripts/ # Utility scripts
├── infra/ # Traefik, runbooks, infrastructure config
├── poster/ # Conference poster assets
├── archive/ # Archived dated docs
├── docker-compose.yml # Main development environment
├── docker-compose.dev.yml # Development overrides
├── docker-compose.prod.yml # Production configuration
└── .env.example # Environment variables template
git clone --recurse-submodules https://github.com/Rollingcat-Software/FIVUCSAS.git
cd FIVUCSAS
# Or initialize submodules if already cloned:
git submodule update --init --recursive# 1. Configure environment
cp .env.example .env
# Edit .env with your settings
# 2. Start all services
docker-compose up -d
# 3. Check status
docker-compose ps
# 4. View logs
docker-compose logs -f| Service | URL |
|---|---|
| API Gateway | http://localhost:8000 |
| Identity Core API | http://localhost:8080 |
| Biometric Processor | http://localhost:8001 |
| Swagger UI (Spring) | http://localhost:8080/swagger-ui.html |
| API Docs (FastAPI) | http://localhost:8001/docs |
| Service | URL |
|---|---|
| Identity Core API | https://api.fivucsas.com |
| Swagger UI | https://api.fivucsas.com/swagger-ui.html (admin-IP-gated) |
| Web Admin Dashboard | https://app.fivucsas.com |
| Landing Page | https://fivucsas.com |
| Auth Widget / Hosted Login | https://verify.fivucsas.com |
| BYS Demo | https://demo.fivucsas.com |
| Documentation | https://docs.fivucsas.com |
| Uptime Monitor | https://status.fivucsas.com |
| Anti-Spoof Tester | https://amispoof.fivucsas.com |
| Links Hub | https://links.fivucsas.com |
# Identity Core API
cd identity-core-api
mvn spring-boot:run -Dspring-boot.run.profiles=dev
# Biometric Processor
cd biometric-processor
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8001
# Web App
cd web-app
npm install && npm run dev# Backend (identity-core-api) — Testcontainers-backed integration + unit
cd identity-core-api && mvn test
# Biometric processor — pytest
cd biometric-processor && pytest tests/unit/
# Web-app unit + component — Vitest
cd web-app && npm test
# Web-app E2E — Playwright against local or production
cd web-app && npx playwright test
# Mobile — requires Android SDK
cd client-apps && ./gradlew :shared:test- Full Documentation — start here
- Getting Started
- Architecture
- Development Guide
- API Documentation
- Multi-Modal Auth Architecture
- Active Plans — SMS activation, client-side ML split, BYOD, OAuth2 audit, multi-method 2FA
Production-deployed. 3,412 tests across all suites (1,176 JUnit api + 804 web-app Vitest + 785 bio pytest + 505 Kotlin client-apps + 142 spoof-detector pytest; measured 2026-05-28 via runner collection mode; excludes Playwright E2E specs).
- Identity Core API — Spring Boot 3.4.7 on Java 21, JWT + RBAC + multi-tenancy, all 10 auth handlers, Flyway V1–V60 (V34–V36 ship hosted-login hardening: PKCE S256 mandate for public clients, atomic code-mint replay guard, cross-client replay guard; V37 tenant_id index; V38 SPA public client flip; V59 audit_logs tenant_id backfill; V60 refresh_tokens plaintext column drop), deployed on Hetzner VPS
- Biometric Processor — FastAPI on Python 3.12, DeepFace / MediaPipe / YOLO for face enroll + verify + liveness, Resemblyzer speaker embeddings for voice, document classifier + MRZ / TC OCR, deployed on Hetzner (internal Docker network, API-key gated, no public route)
- Web Dashboard — React 18 + TypeScript 5 + Vite 8, Clean Architecture with InversifyJS DI, 17 admin pages, full i18n (en + tr), deployed to Hostinger
- Hosted Login + Widget —
verify.fivucsas.comserves a hosted-first redirective login (Auth0 / Okta pattern) at top-level browsing context; iframe widget remains available for inline step-up MFA - Client Apps — KMP for Android / iOS / Desktop, platform-native WebAuthn, Custom Tabs / ASWebAuthenticationSession for hosted-login handoff. Android v5.1.0 ships a standalone TOTP Authenticator (RFC 6238, AES-GCM EncryptedSharedPreferences vault, Compose Material 3 UI) as a drop-in for Google/Microsoft Authenticator.
- Identity Verification Pipeline — 9 step types, 7 industry templates, selfie-to-document matching
- CI/CD — self-hosted GitHub runner on the VPS; each submodule has its own
ci.yml+deploy-*.ymlworkflow; Dependabot configured - Security — PKCE S256 mandatory for public clients, OIDC nonce validation, CSP per-route with frame-ancestors allowlist, GDPR Art. 17 / Art. 20 endpoints (data export + soft-delete purge), rate-limited on authorize-complete + login + export
See client-apps/README.md for the KMP mobile + desktop app, including the v5.1.0 standalone TOTP Authenticator, the current Android feature-parity matrix (targeting 20/20), and the Phase I gap close-out plan in docs/plans/PATH_TO_20_20.md.
Marmara University - Computer Engineering Department
- Ahmet Abdullah Gultekin - Project Lead & Backend Developer
- Ayse Gulsum Eren - Mobile App Developer
- Aysenur Arici - AI/ML & Biometric Systems
Advisor: Assoc. Prof. Dr. Mustafa Agaoglu
Course: CSE4297/CSE4197 Engineering Project
Copyright 2025-2026 FIVUCSAS Team. Licensed under the MIT License.
Built with passion for security and innovation | Marmara University 2025-2026