FIVUCSAS Documentation

Face and Identity Verification Using Cloud-based SaaS

Multi-tenant biometric authentication platform for face recognition, liveness detection, and identity management.

Project Status: Production-deployed (core platform live) | University: Marmara University | Department: Computer Engineering

---

🚀 Quick Start

I want to...	Go to...
Get started quickly	Getting Started
Run the applications	Running Apps
Explore the API	Backend API · Biometric Service
Understand architecture	Architecture Analysis
Start developing	Developer Guide (CLAUDE.md) ⭐
Run tests	Testing Guide
Check project status	Project Status

---

📚 Documentation Structure

0️⃣ Meta Documentation

Documentation about documentation

• Module Design - Documentation module design and analysis
• Project Artifacts - PSD, proposals, original documents
• ADD_2403.txt - Student project title page

1️⃣ Getting Started

New to FIVUCSAS? Start here!

• tenant-onboarding.md - ⭐ Tenant onboarding playbook (5-minute quickstart)
• GETTING_STARTED.md - Complete getting started guide
• RUNNING_APPS.md - Running all applications
• quick-start.md - 5-Minute staging deployment reference
• local-development.md - Full-stack local development
• INTEGRATION_GUIDE.md - Per-framework integration recipes
• EMAIL_OTP_SETUP.md - Email OTP configuration
• STEP_UP_AUTH_GUIDE.md - Mobile-native step-up authentication
• METRICS_COLLECTION_GUIDE.md - Metrics collection
• EU_AI_ACT_COMPLIANCE.md - EU AI Act compliance notes

2️⃣ Architecture

System design and architectural decisions

• ARCHITECTURE_ANALYSIS.md - Complete architecture analysis
• SYSTEM_DESIGN_ANALYSIS_AND_DECISION.md - Design decisions
• data-flow.md / event-bus.md / webhooks.md / security.md / structure.md
• BIOMETRIC_ENGINE_ARCHITECTURE.md - Biometric engine design
• VERIFICATION_PIPELINE_ARCHITECTURE.md - Verification pipeline design
• EMBEDDABLE_AUTH_WIDGET_ARCHITECTURE.md - Embeddable auth widget SDK architecture
• Diagrams - 35+ professional UML/PlantUML diagrams
• adr/ - ⭐ Architecture Decision Records (8 ADRs)

3️⃣ Development

Developer guides and implementation documentation

• CLAUDE.md - ⭐ Main developer guide - START HERE
• KOTLIN_MULTIPLATFORM_GUIDE.md - Mobile app development
• IMPLEMENTATION_GUIDE.md - Implementation details
• TECHNOLOGY_DECISIONS.md - Technology stack decisions
• PRECOMMIT_HOOKS.md - Pre-commit hooks setup
• UX_DESIGN_GUIDE.md - UX design guidelines

4️⃣ API Documentation

Interactive API documentation (auto-generated from code)

Backend API (Spring Boot)

• Swagger UI: http://localhost:8080/swagger-ui.html ⭐
• OpenAPI JSON: http://localhost:8080/v3/api-docs
• OpenAPI YAML: http://localhost:8080/v3/api-docs.yaml

Biometric Service (FastAPI)

• Interactive Docs: http://localhost:8001/docs ⭐
• ReDoc: http://localhost:8001/redoc
• OpenAPI JSON: http://localhost:8001/openapi.json

Reference Documentation

• Backend SpringDoc Setup - SpringDoc OpenAPI implementation
• Biometric FastAPI Setup - FastAPI documentation setup

5️⃣ Testing

Testing guides and test reports

• TESTING_GUIDE.md - Complete testing guide (908 lines)
• MOBILE_TESTING_GUIDE.md - Mobile app testing
• baseline-results.md / integration-testing.md / load-testing.md

6️⃣ Deployment

Deployment and operations guides

• START_ALL_SERVICES.md - Starting all services
• deployment-guide.md / monitoring.md / staging.md
• Runbook index → see 06-deployment/README.md "Runbooks" section

7️⃣ Project Status

Current project status and roadmaps

• 07-status/README.md - ⭐ Authoritative project status
• Design specs, ADRs, and diagram sources are archived in archive/2026-04-16/

8️⃣ Website & Marketing

Landing website documentation for fivucsas.com

• ADD_LANDING_WEBSITE.md - Landing website Analysis & Design Document
• Domain: fivucsas.com (Hostinger)
• Purpose: Marketing, branding, lead generation

9️⃣ Multi-Modal Authentication

Complete architecture for the multi-modal authentication system

• README.md - ⭐ Index & overview of all 10 documents
• 01-PLATFORM_CAPABILITY_MATRIX.md - Auth methods × platforms
• 02-AUTH_FLOW_ARCHITECTURE.md - Session state machine, Strategy pattern
• 03-ENROLLMENT_FLOWS.md - Per-method enrollment flows
• 04-DATABASE_SCHEMA.md - 8 new tables (V16 migration SQL)
• 05-API_SPECIFICATION.md - REST + WebSocket endpoints
• 06-SECURITY_DESIGN.md - Threat model, anti-replay
• 07-TENANT_ADMIN_UX.md - Auth flow builder UI
• 08-CROSS_DEVICE_PROTOCOL.md - QR bridge + WebSocket
• 09-IMPLEMENTATION_PHASES.md - 8-phase roadmap
• 10-VOICE_RECOGNITION_DESIGN.md - ECAPA-TDNN voice endpoints

---

🏗️ System Architecture

┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│   Desktop   │  │   Mobile    │  │     Web     │
│     App     │  │     App     │  │  Dashboard  │
│   (KMP)     │  │   (KMP)     │  │   (React)   │
└──────┬──────┘  └──────┬──────┘  └──────┬──────┘
       │                │                │
       └────────────────┴────────────────┘
                        │
              ┌─────────┴─────────┐
              │                   │
       ┌──────▼──────┐    ┌───────▼────────┐
       │  Identity   │    │   Biometric    │
       │  Core API   │◄───┤   Processor    │
       │ Spring Boot │    │    FastAPI     │
       └──────┬──────┘    └───────┬────────┘
              │                   │
       ┌──────▼──────┐    ┌───────▼────────┐
       │ PostgreSQL  │    │  Redis Cache   │
       │  + pgvector │    │ + Message Queue│
       └─────────────┘    └────────────────┘

Full Details: Architecture Analysis

---

🛠️ Technology Stack

Component	Technology	Status	Documentation
Biometric Processor	FastAPI (Python 3.11)	✅ 100%	FastAPI Docs
Demo GUI	Next.js 14, TypeScript	✅ 100%	Embedded in Biometric Processor
Identity Core API	Spring Boot 3.2 (Java 21)	⚠️ 90%	Swagger UI
Web Admin Dashboard	React 18, Material-UI	✅ 100%	web-app submodule
Mobile/Desktop	Kotlin Multiplatform	⚠️ 60% (UI)	KMP Guide
NFC Reader	Kotlin, Jetpack Compose	✅ 85%	practice-and-test
Database	PostgreSQL 16 + pgvector	✅ 100%	Architecture
Cache/Queue	Redis 7	✅ Ready	Docker Compose configured

---

📊 Project Completion Status

Overall: Core platform production-deployed (June 2026). The API, biometric processor, web dashboard, hosted login + OAuth/OIDC, and the 10 auth methods are live in production; a per-feature truth-table (works / partial / roadmap) is maintained in the repo audit docs. Some advanced layers are intentionally roadmap/flag-off (see "Known limitations" below).

Biometric Processor API:  ████████████████████ 100% ✅ Deployed (face/voice/liveness)
Web Admin Dashboard:      ████████████████████ 100% ✅ React 18, Material-UI, deployed
Identity Core API:        ████████████████████ 100% ✅ Deployed — 10 auth methods, OAuth/OIDC, MFA
Database Schema:          ████████████████████ 100% ✅ PostgreSQL 17 + pgvector, 79 Flyway migrations
Hosted login + SDK:       ████████████████████ 100% ✅ verify.fivucsas.com + CDN SDK
NFC Reader (mobile):      █████████████████░░░  85% ✅ Serial/UID + ICAO 9303 BAC; chip passive-auth WIP
Mobile (Android):         ██████████████████░░  90% ✅ Android app (all 10 methods); iOS host app = roadmap

Known limitations (roadmap / not yet live): iOS host app, BYOD (own-DB), biometric demographics endpoint, OIDC pairwise subjects, the advanced multi-layer anti-spoof fusion pipeline, and the @fivucsas/* npm packages are planned / flag-off and should not be presented as live. NFC chip passive-authentication needs a CSCA trust store. See the per-feature audit docs for the exact status.

Details: Project Status

---

🎓 Academic Information

• Institution: Marmara University
• Department: Computer Engineering
• Course: Engineering Project (CSE4297)
• Project Type: Multi-tenant Biometric SaaS Platform
• Proposal: CSE4297_Project_Proposal.pdf
• Specification: PSD.docx

---

🚀 Quick Commands

Start Backend API

cd identity-core-api
mvn spring-boot:run -Dspring-boot.run.profiles=dev
# Access: http://localhost:8080
# API Docs: http://localhost:8080/swagger-ui.html

Start Biometric Service

cd biometric-processor
./venv/Scripts/activate
uvicorn app.main:app --reload --port 8001
# Access: http://localhost:8001
# API Docs: http://localhost:8001/docs

Start Desktop App

cd client-apps
./gradlew :desktopApp:run

Run All Tests

# Backend
cd identity-core-api && mvn test

# Mobile
cd client-apps && ./gradlew :shared:test

---

📖 Key Documents

For New Developers:

1. Getting Started
2. CLAUDE.md (Developer Guide) ⭐
3. Architecture Overview

For API Integration:

1. Backend API Docs
2. Biometric Service Docs
3. API Integration Quickstart

For Testing:

1. Testing Guide
2. Mobile Testing

---

📞 Support & Contributing

This is a university engineering project. For development:

• Read CLAUDE.md for development guidelines
• Check Implementation Guide
• Review Technology Decisions

---

📋 Documentation Design

This documentation follows professional software engineering principles:

• DRY (Don't Repeat Yourself) - Organized existing documentation, no duplication
• KISS (Keep It Simple) - Simple folder structure, easy navigation
• YAGNI (You Aren't Gonna Need It) - Documents what exists, not hypothetical features
• SOLID Principles - Separation of concerns, single responsibility
• Automation - API docs auto-generated from code (always accurate, zero maintenance)

See design documentation:

• Professional Design

---

Documentation Last Updated: 2026-06-11 Documentation Version: 2.4 (Added Multi-Modal Authentication Module) Project Version: 1.0.0-SNAPSHOT