From 595b48113c3d8826edf0d2dd1ba2d5c30a2915db Mon Sep 17 00:00:00 2001 From: Ahmet Abdullah Gultekin Date: Sun, 14 Jun 2026 18:15:37 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20GitHub-native=20cleanup=20=E2=80=94=20r?= =?UTF-8?q?emove=20archives,=20old=20presentations,=20shipped/migrated=20p?= =?UTF-8?q?lans?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Remove 29 stale docs (git history preserves all): - archive/ (superseded 2026-04 set), project/ (Nov-2025 inception planning), presentations/ (Jan-2026 defense, past). - Shipped designs now living in code: plans/MULTI_METHOD_2FA_DESIGN, plans/NFC_PUSH_APPROVAL_PROTOCOL. - Grade-tracking: plans/PATH_TO_20_20. - Future plans MIGRATED to GitHub issues: BYOD (#217), BAAS (#218), VOICE_STT (#219), PRODUCTION_HARDENING (#220), ANALYTICS (#221); SMS_ACTIVATION (shipped — Twilio Verify live). Kept: adr/ (decision records), 01-getting-started/ + 02-architecture/ (durable reference), plans/CLIENT_SIDE_ML_PLAN + AUTH_METHOD_SECURITY_LEVELS, diagrams/, SECURITY/README. --- archive/2026-04-16/ADD_FIVUCSAS.md | 3187 ----------------- archive/2026-04-16/ADD_LANDING_WEBSITE.md | 1434 -------- archive/2026-04-16/ANALYTICS_PLAN.md | 86 - archive/2026-04-16/BIOMETRIC_FLOW_RESEARCH.md | 777 ---- .../DOCS_MODULE_PROFESSIONAL_DESIGN.md | 1123 ------ .../2026-04-16/IDENTITY_CORE_API_ANALYSIS.md | 454 --- archive/2026-04-16/PGVECTOR_SETUP.md | 480 --- archive/2026-04-16/PLANTUML_DIAGRAMS.md | 2083 ----------- archive/2026-04-16/PLANTUML_DIAGRAMS_PART2.md | 1728 --------- .../2026-04-16/PRESENTATION_COMPLETE_GUIDE.md | 1661 --------- archive/2026-04-16/PRESENTATION_SPEECHES.md | 442 --- archive/2026-04-16/QUICK_START_PGVECTOR.md | 262 -- .../SYSTEM_DESIGN_ANALYSIS_AND_DECISION.md | 604 ---- archive/2026-04-16/TASK_LOG_TEMPLATE.md | 217 -- archive/README.md | 22 - plans/ANALYTICS_PLAN.md | 57 - plans/BAAS_RENTAL_MODEL.md | 652 ---- plans/BYOD_ARCHITECTURE.md | 513 --- plans/MULTI_METHOD_2FA_DESIGN.md | 689 ---- plans/NFC_PUSH_APPROVAL_PROTOCOL.md | 332 -- plans/PATH_TO_20_20.md | 91 - plans/PRODUCTION_HARDENING_PLAN.md | 956 ----- plans/SMS_ACTIVATION_PLAN.md | 547 --- plans/VOICE_STT_PLAN.md | 475 --- .../DEFENSE_PRESENTATION_JAN_2026.md | 515 --- presentations/SLIDES_CONTENT.md | 399 --- project/implementation-prompts.md | 361 -- project/optimization-summary.md | 828 ----- project/planning-summary.md | 701 ---- 29 files changed, 21676 deletions(-) delete mode 100644 archive/2026-04-16/ADD_FIVUCSAS.md delete mode 100644 archive/2026-04-16/ADD_LANDING_WEBSITE.md delete mode 100644 archive/2026-04-16/ANALYTICS_PLAN.md delete mode 100644 archive/2026-04-16/BIOMETRIC_FLOW_RESEARCH.md delete mode 100644 archive/2026-04-16/DOCS_MODULE_PROFESSIONAL_DESIGN.md delete mode 100644 archive/2026-04-16/IDENTITY_CORE_API_ANALYSIS.md delete mode 100644 archive/2026-04-16/PGVECTOR_SETUP.md delete mode 100644 archive/2026-04-16/PLANTUML_DIAGRAMS.md delete mode 100644 archive/2026-04-16/PLANTUML_DIAGRAMS_PART2.md delete mode 100644 archive/2026-04-16/PRESENTATION_COMPLETE_GUIDE.md delete mode 100644 archive/2026-04-16/PRESENTATION_SPEECHES.md delete mode 100644 archive/2026-04-16/QUICK_START_PGVECTOR.md delete mode 100644 archive/2026-04-16/SYSTEM_DESIGN_ANALYSIS_AND_DECISION.md delete mode 100644 archive/2026-04-16/TASK_LOG_TEMPLATE.md delete mode 100644 archive/README.md delete mode 100644 plans/ANALYTICS_PLAN.md delete mode 100644 plans/BAAS_RENTAL_MODEL.md delete mode 100644 plans/BYOD_ARCHITECTURE.md delete mode 100644 plans/MULTI_METHOD_2FA_DESIGN.md delete mode 100644 plans/NFC_PUSH_APPROVAL_PROTOCOL.md delete mode 100644 plans/PATH_TO_20_20.md delete mode 100644 plans/PRODUCTION_HARDENING_PLAN.md delete mode 100644 plans/SMS_ACTIVATION_PLAN.md delete mode 100644 plans/VOICE_STT_PLAN.md delete mode 100644 presentations/DEFENSE_PRESENTATION_JAN_2026.md delete mode 100644 presentations/SLIDES_CONTENT.md delete mode 100644 project/implementation-prompts.md delete mode 100644 project/optimization-summary.md delete mode 100644 project/planning-summary.md diff --git a/archive/2026-04-16/ADD_FIVUCSAS.md b/archive/2026-04-16/ADD_FIVUCSAS.md deleted file mode 100644 index b4a1771..0000000 --- a/archive/2026-04-16/ADD_FIVUCSAS.md +++ /dev/null @@ -1,3187 +0,0 @@ -# FACE AND IDENTITY VERIFICATION USING CLOUD BASED SAAS MODELS - -## Architectural Design Document (ADD) - ---- - -**CSE4197 Engineering Project 2** - -**Marmara University, Faculty of Engineering** -**Computer Engineering Department** - -**Spring Semester 2026** - ---- - -**Supervised by:** Assoc. Prof. Dr. Mustafa Ağaoğlu - -**Team Members:** -- Ahmet Abdullah Gültekin - 150121025 (Project Lead & Backend Developer) -- Ayşe Gülsüm Eren - 150120005 (Mobile Application Developer) -- Ayşenur Arıcı - 150123825 (AI/ML & Biometric Systems) - ---- - -**Document Version:** 1.0 -**Last Updated:** January 2026 - ---- - -## Table of Contents - -1. [Introduction](#1-introduction) - - 1.1 [Problem Description](#11-problem-description) - - 1.2 [Scope](#12-scope) - - 1.3 [Definitions and Acronyms](#13-definitions-and-acronyms) -2. [Literature Survey](#2-literature-survey) -3. [Project Requirements](#3-project-requirements) - - 3.1 [Functional Requirements](#31-functional-requirements) - - 3.2 [Non-Functional Requirements](#32-non-functional-requirements) -4. [System Design](#4-system-design) - - 4.1 [Use Case Diagrams](#41-use-case-diagrams) - - 4.2 [Class and ER Diagrams](#42-class-and-er-diagrams) - - 4.3 [User Interface Design](#43-user-interface-design) - - 4.4 [Test Plan](#44-test-plan) -5. [Software Architecture](#5-software-architecture) - - 5.1 [Architectural Style](#51-architectural-style) - - 5.2 [Component Architecture](#52-component-architecture) - - 5.3 [Data Architecture](#53-data-architecture) - - 5.4 [Deployment Architecture](#54-deployment-architecture) -6. [Tasks Accomplished](#6-tasks-accomplished) - - 6.1 [Current State of the System](#61-current-state-of-the-system) - - 6.2 [Task Log](#62-task-log) - - 6.3 [Gantt Chart](#63-gantt-chart) -7. [References](#7-references) - ---- - -## 1. Introduction - -### 1.1 Problem Description - -Traditional authentication methods present significant security vulnerabilities and poor user experiences in modern digital and physical access scenarios. According to Verizon's 2024 Data Breach Investigations Report, **81% of hacking-related breaches involve stolen or weak passwords**, while the Identity Theft Resource Center reports a **78% increase in data compromise events** between 2022-2023 affecting over 350 million individuals. Simultaneously, physical access cards can be cloned with readily available $50 RFID readers, and passive biometric systems remain vulnerable to spoofing attacks using static photos (success rate: 67% against basic systems), videos, or sophisticated 3D masks. - -This project addresses these challenges by developing **FIVUCSAS** (Face and Identity Verification Using Cloud-based SaaS) - a multi-tenant, cloud-native biometric authentication platform. The system integrates advanced face recognition with an innovative active liveness detection algorithm called "Biometric Puzzle" to provide robust protection against fraud while maintaining excellent user experience through developer-friendly APIs. - -The platform targets B2B and B2B2C markets, unifying both physical access control (door entry, kiosk authentication) and digital authentication (system login, transaction verification) under a single identity management solution. - -### 1.2 Scope - -#### 1.2.1 In Scope - -| Category | Items | -|----------|-------| -| **Backend Services** | Identity Core API (Spring Boot 3.2/Java 21), Biometric Processor API (FastAPI/Python 3.11) | -| **Client Applications** | Web Admin Dashboard (React 18), Mobile App (Android), Desktop App (Windows/Linux/macOS) using Kotlin Multiplatform | -| **Database Architecture** | Multi-tenant PostgreSQL 16 with pgvector extension for face embeddings | -| **Face Biometrics** | Face recognition (1:N), face verification (1:1) using DeepFace library with 9 model options | -| **Liveness Detection** | "Biometric Puzzle" active liveness + passive anti-spoofing using MediaPipe (468 facial landmarks) | -| **Infrastructure** | Docker Compose containerization, NGINX API Gateway, Redis caching | -| **Security** | JWT authentication, RBAC authorization, BCrypt password hashing, rate limiting | - -#### 1.2.2 Out of Scope - -| Feature | Exclusion Rationale | -|---------|-------------------| -| **Other biometric modalities** (fingerprint, voice, iris) | Architecture supports extensibility, but implementation deferred due to: (1) time constraints of academic semester, (2) face recognition sufficient for MVP validation, (3) hardware requirements (fingerprint readers) increase deployment complexity | -| **Production cloud deployment** (Kubernetes, Helm charts) | Docker Compose sufficient for academic demonstration and initial deployments; Kubernetes orchestration adds complexity without demonstrating core innovation; can be added post-graduation | -| **Edge device hardware manufacturing** | Physical kiosk/door hardware simulated in software to focus on core algorithms; hardware manufacturing outside software engineering scope; integration with commercial hardware (e.g., Raspberry Pi + camera) feasible but not required for degree | -| **Advanced billing and subscription management UI** | Basic tenant quotas implemented in database schema; comprehensive Stripe/payment integration deferred as non-differentiating feature; focus on biometric innovation over generic billing logic | -| **NFC card reading functionality** | Proof-of-concept NFC readers implemented separately (see `practice-and-test/`); integration into main app deferred to Semester 2 due to Android NFC API complexity and testing requirements | - -#### 1.2.3 Constraints - -| Constraint Type | Description | -|-----------------|-------------| -| **Technology** | Exclusively open-source technologies with permissive licenses (no proprietary databases, ML models, or frameworks) | -| **Infrastructure** | Primary development on local environments (Docker Compose); VPS hosting permitted for demonstration/testing purposes only (not production deployment) | -| **Hardware** | Liveness detection performance limited by device camera quality (minimum 720p recommended) and processing power (CPU inference acceptable, GPU optional for scale) | -| **Data** | No custom model training due to lack of labeled biometric datasets and GPU infrastructure; relies on pre-trained DeepFace models (Facenet, ArcFace, VGG-Face) | -| **Timeline** | Academic semester constraints (September 2025 - January 2026); core features prioritized over auxiliary functionality | - -### 1.3 Definitions and Acronyms - -| Term | Definition | -|------|------------| -| **ADD** | Architectural Design Document | -| **API** | Application Programming Interface | -| **BCrypt** | Password hashing algorithm with configurable work factor | -| **DeepFace** | Python library providing face recognition models (VGG-Face, Facenet, ArcFace, etc.) | -| **EAR** | Eye Aspect Ratio - metric for blink detection | -| **Embedding** | High-dimensional vector representation of a face | -| **FAR** | False Acceptance Rate | -| **FRR** | False Rejection Rate | -| **GDPR** | General Data Protection Regulation (EU) | -| **Hexagonal Architecture** | Ports and Adapters pattern for clean separation of concerns | -| **JWT** | JSON Web Token for stateless authentication | -| **KMP** | Kotlin Multiplatform - cross-platform development framework | -| **KVKK** | Turkish Personal Data Protection Law (No. 6698) | -| **MAR** | Mouth Aspect Ratio - metric for smile detection | -| **MediaPipe** | Google's ML library for real-time face landmark detection | -| **MVP** | Minimum Viable Product | -| **pgvector** | PostgreSQL extension for vector similarity search | -| **RBAC** | Role-Based Access Control | -| **SaaS** | Software as a Service | -| **Spoofing** | Attempt to bypass biometric authentication using fake biometrics | - ---- - -## 2. Literature Survey - -### 2.1 Identity and Access Management Landscape - -The Identity and Access Management (IAM) market is dominated by established players including Okta, Auth0, and Microsoft Azure Active Directory. These platforms primarily focus on traditional multi-factor authentication (MFA) methods: - -- Password-based authentication with complexity requirements -- One-Time Passwords (OTP) via SMS or authenticator apps -- Push notifications for approval -- Device-based biometrics (Apple Face ID, Android fingerprint) - -While these solutions are mature, they present limitations: -1. Device-bound biometrics create siloed identity experiences -2. Physical access control requires separate third-party integrations -3. Passive biometric verification remains vulnerable to sophisticated attacks - -### 2.2 Face Recognition Technologies - -Deep learning has revolutionized face recognition, achieving and surpassing human-level performance: - -| Model | Embedding Dimension | Architecture | LFW Accuracy | -|-------|---------------------|--------------|--------------| -| VGG-Face | 2,622 | VGGNet | 98.95% | -| Facenet512 | 512 | Inception ResNet | 99.65% | -| ArcFace | 512 | ResNet | 99.82% | -| DeepFace | 4,096 | AlexNet | 97.35% | -| OpenFace | 128 | Inception | 92.92% | - -The DeepFace library (Serengil & Ozpinar, 2021) provides unified access to these models, enabling: -- Face detection (MTCNN, RetinaFace, SSD) -- Face alignment and preprocessing -- Embedding generation -- Similarity computation (cosine, euclidean) - -### 2.3 Liveness Detection Approaches - -Face anti-spoofing research has evolved through several paradigms: - -**Passive Methods:** -- Texture analysis using Local Binary Patterns (LBP) -- Frequency domain analysis for moire patterns -- Color space analysis for skin tone verification -- Depth estimation from single images - -**Active Methods:** -- Challenge-response requiring user interaction -- Randomized action sequences -- Micro-expression tracking - -**Limitations of Passive Methods:** -- Vulnerable to high-quality prints and video replays -- Susceptible to 3D mask attacks -- Performance degrades with camera quality variations - -### 2.4 Comparative Analysis with Existing Solutions - -To rigorously position FIVUCSAS within the competitive landscape, we compare against leading Identity and Access Management (IAM) platforms and biometric authentication services: - -#### 2.4.1 IAM Platform Comparison - -| Feature / Capability | Okta | Auth0 (by Okta) | Microsoft Entra ID | AWS Rekognition | Azure Face API | **FIVUCSAS** | -|---------------------|------|-----------------|-------------------|-----------------|----------------|--------------| -| **Architecture** | -| Cloud-native SaaS | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Multi-tenant isolation | ✓ | ✓ | ✓ | N/A | N/A | ✓ | -| On-premises deployment | ✓ (OIN) | ✗ | ✓ (Hybrid) | ✗ | ✗ | ✓ (Docker) | -| Microservices design | Proprietary | Proprietary | Proprietary | N/A | N/A | ✓ | -| Open-source | ✗ | ✗ | ✗ | ✗ | ✗ | **✓** | -| **Authentication Methods** | -| Password + MFA | ✓ | ✓ | ✓ | N/A | N/A | ✓ | -| Biometric (device-bound) | ✓ (WebAuthn) | ✓ (WebAuthn) | ✓ (Windows Hello) | N/A | N/A | ✓ | -| Cloud-based face recognition | ✗ | ✗ | ✗ | ✓ | ✓ | **✓** | -| Active liveness detection | ✗ | ✗ | ✗ | Passive only | Passive only | **✓ (Biometric Puzzle)** | -| Multi-model face recognition | N/A | N/A | N/A | Single (proprietary) | Single (proprietary) | **✓ (9 models)** | -| **Physical Access Control** | -| Door/kiosk authentication | Integration only | Integration only | Integration only | ✗ | ✗ | **✓ (Native)** | -| NFC card reading | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ (Planned) | -| **Developer Experience** | -| REST API | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| SDKs | ✓ (8+ languages) | ✓ (12+ languages) | ✓ (Multiple) | ✓ (AWS SDK) | ✓ (Azure SDK) | ✓ (Python, Java, Kotlin) | -| OpenAPI/Swagger docs | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Webhooks | ✓ | ✓ | ✓ | ✗ | ✗ | ✓ | -| **Data & Privacy** | -| GDPR compliance | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | -| Data residency control | ✓ | ✓ | ✓ | Regional | Regional | **✓ (Self-hosted)** | -| Biometric data storage | N/A | N/A | N/A | Images stored | Images stored | **Embeddings only** | -| **Pricing Model** | -| Free tier | ✓ (Limited) | ✓ (7,500 MAUs) | ✓ (50K MAUs) | Pay-per-use | Pay-per-use | **✓ (Fully free/OSS)** | -| Enterprise cost (est.) | $5-15/user/month | $23-240/month | $6/user/month | $1/1K faces | $1/1K faces | **$0 (Self-hosted)** | - -#### 2.4.2 Why Existing Solutions Fall Short - -**Okta/Auth0 Limitations:** -1. **No Native Biometric SaaS:** Rely on device-bound biometrics (WebAuthn) which cannot unify physical and digital access -2. **Integration Complexity:** Physical access requires third-party integrations (e.g., Okta + Openpath) increasing cost and complexity -3. **Proprietary Lock-in:** Closed-source architecture prevents customization and on-premises deployment for sensitive environments -4. **Cost Barriers:** Per-user/per-month pricing becomes prohibitive at scale (10,000 users = $50,000-$150,000/year) - -**AWS Rekognition / Azure Face API Limitations:** -1. **No Identity Management:** Pure face recognition APIs without authentication/authorization layer -2. **Passive Liveness Only:** Vulnerable to sophisticated spoofing attacks (high-quality prints, video replay) -3. **No Multi-Tenancy:** Developers must build tenant isolation, RBAC, and quota management themselves -4. **Vendor Lock-in:** Proprietary models with no model selection flexibility -5. **Data Privacy Concerns:** Raw face images stored in cloud, violating some regulatory requirements (BIPA, GDPR Article 9) - -**Microsoft Entra ID (Azure AD) Limitations:** -1. **Enterprise Focus:** Designed for corporate SSO, not B2B SaaS or physical access -2. **No Face Recognition:** Supports Windows Hello (device biometrics) but no cloud-based face verification -3. **Complex Licensing:** Requires Azure subscriptions and complex SKU management - -#### 2.4.3 FIVUCSAS Unique Value Propositions - -**Technical Differentiators:** -1. **Unified Identity Platform:** Single system for digital authentication (web/mobile) AND physical access (doors, kiosks) -2. **Advanced Liveness Protection:** Biometric Puzzle algorithm requires sequential actions (blink + smile + head turn) defeating passive attacks -3. **Multi-Model Flexibility:** Tenant-configurable model selection (Facenet, ArcFace, VGG-Face) optimizing accuracy vs. speed trade-offs -4. **Privacy-First Design:** Stores only embeddings (512-2622D vectors), never raw images, complying with strictest regulations -5. **Open-Source Transparency:** Fully auditable codebase enabling security reviews and custom extensions - -**Business Differentiators:** -1. **Zero Licensing Costs:** No per-user fees, predictable infrastructure-only costs -2. **Deployment Flexibility:** Docker Compose for on-premises OR cloud VPS deployment -3. **Regulatory Compliance:** Self-hosted option satisfies data residency requirements (GDPR, KVKK, HIPAA) -4. **Developer Velocity:** FastAPI + Spring Boot with extensive documentation accelerates integration - -**Note:** The comparative analysis above demonstrates that FIVUCSAS addresses critical gaps in the current market by combining enterprise IAM capabilities with advanced biometric authentication in a single, open-source, privacy-respecting platform. This positions the project as a viable alternative for organizations requiring both digital and physical access control without vendor lock-in or prohibitive per-user costs. - ---- - -## 3. Project Requirements - -### 3.1 Functional Requirements - -This section presents the functional requirements in hierarchical format as per CSE4197 guidelines. Each requirement is structured with: Description, Inputs, Processing, Outputs, and Error/Data Handling subsections. - ---- - -#### 3.1.1 FR-1: User Authentication and Management - -##### 3.1.1.1 FR-1.1: User Registration - -###### 3.1.1.1.1 Description -Enables end users to create a new account within a specific tenant boundary. The system validates user input, ensures email uniqueness within the tenant scope, and securely stores credentials using industry-standard cryptographic hashing. - -###### 3.1.1.1.2 Inputs -- **Email:** String in RFC 5322 format (e.g., user@example.com) -- **Password:** String with minimum 12 characters, including uppercase, lowercase, digit, and special character -- **First Name:** String (1-50 characters) -- **Last Name:** String (1-50 characters) -- **Tenant ID:** UUID identifying the tenant context - -###### 3.1.1.1.3 Processing -1. Validate email format against RFC 5322 specification -2. Check email uniqueness within tenant scope (query users table with tenant_id filter) -3. Validate password complexity against defined policy -4. Hash password using BCrypt algorithm with work factor 12 -5. Create user record in database with status "ACTIVE" -6. Assign default role "USER" for the tenant -7. Generate confirmation token if email verification required - -###### 3.1.1.1.4 Outputs -- **User ID:** UUID of newly created user -- **Confirmation Message:** Success response with user details (excluding sensitive data) -- **HTTP Status:** 201 Created - -###### 3.1.1.1.5 Error/Data Handling -- **409 Conflict:** If email already exists within tenant (returns existing user's ID hash for security) -- **400 Bad Request:** If email format invalid, password does not meet complexity requirements, or required fields missing -- **403 Forbidden:** If tenant registration is disabled or tenant quota exceeded -- **Data Validation:** All inputs sanitized to prevent SQL injection and XSS attacks - ---- - -##### 3.1.1.2 FR-1.2: User Login - -###### 3.1.1.2.1 Description -Authenticates a user with email and password credentials, generating JWT tokens for subsequent API access. The system implements secure session management with short-lived access tokens and long-lived refresh tokens. - -###### 3.1.1.2.2 Inputs -- **Email:** String (registered user email) -- **Password:** String (plaintext password) -- **Tenant ID:** UUID identifying tenant context - -###### 3.1.1.2.3 Processing -1. Query user record by email and tenant_id -2. Verify user account status (must be ACTIVE, not LOCKED or SUSPENDED) -3. Compare submitted password with stored BCrypt hash -4. Increment failed login counter if password incorrect (lock account after 5 failures) -5. Generate JWT access token with 15-minute expiration (algorithm: HS512) -6. Generate JWT refresh token with 7-day expiration -7. Store refresh token in Redis with user session metadata -8. Reset failed login counter on successful authentication -9. Create audit log entry with IP address and user agent - -###### 3.1.1.2.4 Outputs -- **Access Token:** JWT string for API authentication -- **Refresh Token:** JWT string for token renewal -- **User Profile:** JSON object containing user_id, email, first_name, last_name, roles -- **Token Metadata:** Expiration timestamps for both tokens -- **HTTP Status:** 200 OK - -###### 3.1.1.2.5 Error/Data Handling -- **401 Unauthorized:** If email not found, password incorrect, or tenant mismatch -- **423 Locked:** If account locked due to repeated failed attempts (requires admin unlock) -- **403 Forbidden:** If account status is SUSPENDED or DELETED -- **Rate Limiting:** Enforce 10 login attempts per IP per minute (return 429 Too Many Requests) -- **Security:** Log all failed attempts for suspicious activity detection - ---- - -##### 3.1.1.3 FR-1.3: Token Refresh - -###### 3.1.1.3.1 Description -Allows clients to obtain a new access token using a valid refresh token without requiring re-authentication. This enables long-lived sessions while maintaining security through short access token lifetimes. - -###### 3.1.1.3.2 Inputs -- **Refresh Token:** JWT string previously issued during login - -###### 3.1.1.3.3 Processing -1. Validate JWT signature and expiration date -2. Extract user_id and session_id from token claims -3. Query Redis to verify token not revoked (check against session_id) -4. Verify user account still active in database -5. Generate new JWT access token with 15-minute expiration -6. Generate new JWT refresh token with 7-day expiration -7. Revoke old refresh token in Redis (add to revocation list) -8. Store new refresh token in Redis - -###### 3.1.1.3.4 Outputs -- **New Access Token:** JWT string -- **New Refresh Token:** JWT string -- **HTTP Status:** 200 OK - -###### 3.1.1.3.5 Error/Data Handling -- **401 Unauthorized:** If refresh token expired, signature invalid, or token revoked -- **403 Forbidden:** If user account no longer active -- **Token Rotation:** Old refresh tokens immediately invalidated to prevent replay attacks -- **Audit:** Log all token refresh operations with timestamp and IP - ---- - -##### 3.1.1.4 FR-1.4: Password Reset - -###### 3.1.1.4.1 Description -Initiates a password reset workflow for users who have forgotten their credentials. The system generates a time-limited reset token and sends it via email notification. - -###### 3.1.1.4.2 Inputs -- **Email:** String (registered user email) - -###### 3.1.1.4.3 Processing -1. Query user by email (do not reveal whether email exists for security) -2. If user found, generate cryptographically random reset token (32 bytes) -3. Store token hash in database with 24-hour expiration -4. Send email with reset link containing token (e.g., /reset-password?token=...) -5. If user not found, return same success message (prevent email enumeration) -6. Rate limit reset requests to 3 per email per hour - -###### 3.1.1.4.4 Outputs -- **Confirmation Message:** Generic success message (e.g., "If the email is registered, a reset link has been sent") -- **HTTP Status:** 200 OK (regardless of email existence) - -###### 3.1.1.4.5 Error/Data Handling -- **404 Not Found:** Never returned to prevent email enumeration attacks -- **429 Too Many Requests:** If reset request limit exceeded for this email -- **Email Delivery Failure:** Log error but still return success to client -- **Token Security:** Reset tokens are single-use and expire after 24 hours - ---- - -##### 3.1.1.5 FR-1.5: Profile Update - -###### 3.1.1.5.1 Description -Allows authenticated users to update their profile information such as name, phone number, and preferences. Admin users can update other users' profiles within their tenant. - -###### 3.1.1.5.2 Inputs -- **User ID:** UUID of user to update (from JWT or request body for admins) -- **Profile Fields:** JSON object containing updatable fields (first_name, last_name, phone_number, preferences) - -###### 3.1.1.5.3 Processing -1. Extract authenticated user from JWT access token -2. Verify permission: user can update own profile OR has tenant_admin role -3. Validate that target user belongs to same tenant -4. Validate field formats (e.g., phone number regex) -5. Update only allowed fields (prevent updating email, password, tenant_id directly) -6. Save changes to database -7. Invalidate cached user profile in Redis -8. Create audit log entry - -###### 3.1.1.5.4 Outputs -- **Updated User Profile:** JSON object with all current profile fields -- **HTTP Status:** 200 OK - -###### 3.1.1.5.5 Error/Data Handling -- **403 Forbidden:** If user attempts to update another user's profile without admin role -- **404 Not Found:** If target user_id does not exist or belongs to different tenant -- **400 Bad Request:** If field validation fails (e.g., invalid phone number format) -- **Immutable Fields:** Email, password, tenant_id cannot be changed via this endpoint (return 400 with error details) - ---- - -#### 3.1.2 FR-2: Biometric Enrollment - -##### 3.1.2.1 FR-2.1: Face Enrollment - -###### 3.1.2.1.1 Description -Captures and processes a user's facial biometric data to create a digital enrollment record. The system performs liveness detection, quality assessment, and generates a mathematical embedding vector for future verification operations. - -###### 3.1.2.1.2 Inputs -- **User ID:** UUID of user enrolling biometric -- **Face Image(s):** One or more images in JPEG/PNG format (base64-encoded or multipart upload) -- **Liveness Proof:** Video frames or challenge completion token from biometric puzzle -- **Model Selection:** Optional string specifying face recognition model (Facenet, ArcFace, VGG-Face, etc.) - -###### 3.1.2.1.3 Processing -1. Verify user authentication and biometric.enroll permission -2. Check tenant enrollment quota not exceeded (max_biometric_enrollments) -3. Validate liveness proof using Biometric Puzzle algorithm -4. Decode and validate image format -5. Detect face using MTCNN detector -6. Assess image quality (brightness, sharpness, pose angle, occlusion) -7. Reject if quality score < 0.5 (configurable threshold) -8. Generate face embedding using selected model (default: Facenet with 128 dimensions) -9. Normalize embedding vector for cosine similarity -10. Store embedding in biometric_data table using pgvector data type -11. Create IVFFlat index for vector similarity search -12. Delete raw images immediately (GDPR compliance - store embeddings only) - -###### 3.1.2.1.4 Outputs -- **Enrollment ID:** UUID of created biometric enrollment record -- **Quality Score:** Float value 0.0-1.0 indicating image quality -- **Quality Level:** Enum (EXCELLENT, GOOD, FAIR, POOR) -- **Embedding Dimension:** Integer (128, 512, or 2622 depending on model) -- **HTTP Status:** 201 Created - -###### 3.1.2.1.5 Error/Data Handling -- **400 Bad Request:** If no face detected in image, or image format invalid -- **422 Unprocessable Entity:** If quality score insufficient (< 0.5) -- **403 Forbidden:** If tenant enrollment quota exceeded or user lacks permission -- **409 Conflict:** If user already has active enrollment (prompt for re-enrollment) -- **Liveness Failure:** Return 403 with failure reason if spoof detected -- **Data Retention:** Raw images never persisted, only embeddings stored - ---- - -##### 3.1.2.2 FR-2.2: Quality Assessment - -###### 3.1.2.2.1 Description -Analyzes facial image quality across multiple dimensions to ensure enrollment and verification accuracy. The system provides real-time feedback to guide users in capturing optimal biometric samples. - -###### 3.1.2.2.2 Inputs -- **Face Image:** JPEG or PNG image (base64-encoded or binary) - -###### 3.1.2.2.3 Processing -1. Decode image and convert to RGB color space -2. Detect face region using MTCNN -3. Analyze brightness: compute mean pixel intensity (target: 100-200 range) -4. Analyze sharpness: apply Laplacian operator and compute variance (threshold: > 100) -5. Analyze pose: estimate yaw/pitch/roll angles (target: within ±15 degrees) -6. Detect occlusions: identify sunglasses, masks, hands using MediaPipe -7. Compute overall quality score as weighted average: - - Brightness: 20% - - Sharpness: 30% - - Pose: 30% - - Occlusion: 20% -8. Map score to quality level: - - EXCELLENT: score ≥ 0.8 - - GOOD: score ≥ 0.6 - - FAIR: score ≥ 0.4 - - POOR: score < 0.4 - -###### 3.1.2.2.4 Outputs -- **Quality Score:** Float value 0.0-1.0 -- **Quality Level:** Enum (EXCELLENT/GOOD/FAIR/POOR) -- **Detailed Metrics:** JSON object containing brightness, sharpness, pose angles, occlusion flags -- **Recommendations:** Array of strings suggesting improvements (e.g., "Move closer to light source", "Remove sunglasses") -- **HTTP Status:** 200 OK - -###### 3.1.2.2.5 Error/Data Handling -- **400 Bad Request:** If image format unrecognized or corrupted -- **422 Unprocessable Entity:** If no face detected in image -- **Graceful Degradation:** Return partial metrics if some analysis steps fail - ---- - -##### 3.1.2.3 FR-2.3: Liveness Verification - -###### 3.1.2.3.1 Description -Implements the Biometric Puzzle algorithm to detect presentation attacks (spoofing). The system issues random challenges requiring user actions (blink, smile, head turn) and verifies completion using facial landmark tracking. - -###### 3.1.2.3.2 Inputs -- **Challenge ID:** UUID of active liveness challenge session -- **Video Frames:** Array of images representing sequential frames (minimum 30 frames at 10 FPS) - -###### 3.1.2.3.3 Processing -1. Retrieve challenge configuration from Redis (random 3-5 actions) -2. Process frames sequentially using MediaPipe Face Mesh (468 landmarks) -3. For each required action, compute metrics: - - **Blink:** Eye Aspect Ratio (EAR) < 0.2 for 2+ consecutive frames - - **Smile:** Mouth Aspect Ratio (MAR) > 0.5 for 3+ frames - - **Head Turn Left/Right:** Yaw angle < -20° or > +20° - - **Nod:** Pitch angle change > 15° over 1 second -4. Verify actions completed in correct sequence -5. Detect anomalies: - - Uniform texture (printed photo): compute Laplacian variance - - Screen reflections: analyze specular highlights - - Video replay: check for digital artifacts (JPEG compression patterns) -6. Compute confidence score based on action completion quality -7. Require confidence > 0.95 for PASS result - -###### 3.1.2.3.4 Outputs -- **Liveness Result:** Enum (PASS, FAIL, INCONCLUSIVE) -- **Confidence Score:** Float 0.0-1.0 -- **Completed Actions:** Array of successfully detected actions -- **Failure Reason:** String describing why challenge failed (if applicable) -- **HTTP Status:** 200 OK - -###### 3.1.2.3.5 Error/Data Handling -- **400 Bad Request:** If insufficient frames provided (< 30) or challenge_id invalid -- **403 Forbidden:** If spoof detected (confidence < 0.95, texture anomalies) -- **410 Gone:** If challenge expired (timeout: 60 seconds) -- **Retry Limit:** Allow maximum 3 attempts per enrollment session -- **Security:** Log all failed liveness attempts with frame metadata for forensic analysis - ---- - -##### 3.1.2.4 FR-2.4: Re-enrollment - -###### 3.1.2.4.1 Description -Allows users to update their biometric enrollment with a new face capture. This may be necessary due to significant appearance changes or to improve enrollment quality. Admin override available for forced re-enrollment. - -###### 3.1.2.4.2 Inputs -- **User ID:** UUID of user to re-enroll -- **New Face Image:** JPEG/PNG image for new enrollment -- **Admin Override:** Boolean flag (requires tenant_admin role) - -###### 3.1.2.4.3 Processing -1. Verify requester is user themselves OR has tenant_admin role -2. Query existing enrollment record for user_id -3. If admin_override=false, require user authentication -4. Delete existing enrollment record from biometric_data table -5. Process new enrollment following FR-2.1 workflow -6. Create audit log entry noting re-enrollment with reason -7. Invalidate any cached verification results in Redis - -###### 3.1.2.4.4 Outputs -- **New Enrollment ID:** UUID of newly created enrollment -- **HTTP Status:** 201 Created - -###### 3.1.2.4.5 Error/Data Handling -- **403 Forbidden:** If user attempts re-enrollment without proper authorization -- **404 Not Found:** If no existing enrollment found for user_id -- **Transactional:** Deletion and new enrollment executed atomically (rollback on failure) -- **Backup:** Store old embedding in enrollment_history table for audit purposes (30-day retention) - ---- - -#### 3.1.3 FR-3: Biometric Verification - -##### 3.1.3.1 FR-3.1: 1:1 Verification - -###### 3.1.3.1.1 Description -Performs one-to-one biometric verification by comparing a presented face image against a specific user's enrolled embedding. This is the primary authentication mechanism for physical and digital access control. - -###### 3.1.3.1.2 Inputs -- **User ID:** UUID of user claiming identity -- **Face Image:** JPEG/PNG image of face to verify - -###### 3.1.3.1.3 Processing -1. Retrieve enrolled embedding for user_id from biometric_data table -2. Generate embedding from presented face image using same model as enrollment -3. Compute cosine similarity between embeddings: similarity = (A · B) / (||A|| × ||B||) -4. Retrieve tenant-configured similarity threshold (default: 0.7 for Facenet) -5. Determine match result: MATCH if similarity ≥ threshold, NO_MATCH otherwise -6. Create verification log entry with result, similarity score, timestamp -7. Increment verification counter for analytics - -###### 3.1.3.1.4 Outputs -- **Match Result:** Boolean (true/false) -- **Similarity Score:** Float 0.0-1.0 indicating confidence -- **Verification ID:** UUID of verification attempt for audit trail -- **HTTP Status:** 200 OK - -###### 3.1.3.1.5 Error/Data Handling -- **404 Not Found:** If user_id has no enrollment record -- **401 Unauthorized:** If similarity score below threshold (log failed attempt) -- **400 Bad Request:** If face not detected in presented image -- **Rate Limiting:** Enforce maximum 10 verification attempts per user per minute (prevent brute-force attacks) -- **Caching:** Cache recent negative results for 5 seconds to prevent rapid retry attacks - ---- - -##### 3.1.3.2 FR-3.2: 1:N Search - -###### 3.1.3.2.1 Description -Performs one-to-many search to identify a person across all enrolled users within a tenant. This supports use cases like identifying unknown visitors or finding duplicates during enrollment. - -###### 3.1.3.2.2 Inputs -- **Face Image:** JPEG/PNG image of face to search -- **Tenant ID:** UUID of tenant scope for search -- **Top K:** Integer specifying number of top matches to return (default: 10, max: 100) -- **Threshold:** Optional minimum similarity threshold (default: 0.6) - -###### 3.1.3.2.3 Processing -1. Generate embedding from search face image -2. Execute pgvector similarity search query: - ```sql - SELECT user_id, 1 - (embedding <=> :query_embedding) AS similarity - FROM biometric_data - WHERE tenant_id = :tenant_id - ORDER BY embedding <=> :query_embedding - LIMIT :top_k - ``` -3. Use IVFFlat index for fast approximate nearest neighbor search -4. Filter results where similarity ≥ threshold -5. Enrich results with user profile data (name, email) from users table -6. Create search audit log entry - -###### 3.1.3.2.4 Outputs -- **Matches:** JSON array of objects containing: - - user_id: UUID - - similarity: Float 0.0-1.0 - - user_profile: Object with first_name, last_name, email - - rank: Integer position in results -- **Total Results:** Integer count of matches above threshold -- **HTTP Status:** 200 OK - -###### 3.1.3.2.5 Error/Data Handling -- **404 Not Found:** If no matches found above threshold (return empty array with 200 OK) -- **400 Bad Request:** If face not detected or top_k exceeds maximum -- **Performance:** Query time increases with database size; monitor and enforce limits: - - < 50ms for 1K enrollments - - < 100ms for 10K enrollments - - < 200ms for 100K enrollments -- **Privacy:** Limit search to users within same tenant (strict row-level security) - ---- - -##### 3.1.3.3 FR-3.3: Verification with Liveness - -###### 3.1.3.3.1 Description -Combines liveness detection with 1:1 verification to provide maximum security against presentation attacks. This two-stage process ensures the presented biometric is both genuine and matching the claimed identity. - -###### 3.1.3.3.2 Inputs -- **User ID:** UUID of user claiming identity -- **Face Image:** JPEG/PNG final face image after liveness -- **Liveness Proof:** Challenge completion token or video frames - -###### 3.1.3.3.3 Processing -1. **Stage 1 - Liveness Verification:** - - Execute FR-2.3 Liveness Verification workflow - - Require confidence > 0.95 to proceed - - If liveness fails, abort immediately without checking identity -2. **Stage 2 - Identity Verification:** - - Execute FR-3.1 1:1 Verification workflow - - Use final frame from liveness challenge for embedding -3. Combine results into single response -4. Create audit log with both liveness and verification details - -###### 3.1.3.3.4 Outputs -- **Overall Result:** Enum (VERIFIED, FAILED_LIVENESS, FAILED_VERIFICATION) -- **Liveness Status:** Object containing result, confidence -- **Verification Status:** Object containing match result, similarity -- **Verification ID:** UUID for audit trail -- **HTTP Status:** 200 OK - -###### 3.1.3.3.5 Error/Data Handling -- **403 Forbidden:** If liveness verification fails (return liveness details) -- **401 Unauthorized:** If liveness passes but identity verification fails -- **Short-Circuit:** Abort after liveness failure to minimize processing time -- **Audit:** Log all failed attempts with specific failure stage for security monitoring - ---- - -#### 3.1.4 FR-4: Multi-Tenant Administration - -##### 3.1.4.1 FR-4.1: Tenant Creation - -###### 3.1.4.1.1 Description -Allows system administrators to provision new tenant organizations within the SaaS platform. Each tenant receives isolated data storage, configurable quotas, and unique API credentials. - -###### 3.1.4.1.2 Inputs -- **Name:** String (1-100 characters, tenant organization name) -- **Domain:** String (unique domain identifier, e.g., "acme-corp") -- **Subscription Plan:** Enum (FREE, BASIC, PROFESSIONAL, ENTERPRISE) -- **Settings:** JSON object containing: - - max_users: Integer quota - - max_biometric_enrollments: Integer quota - - similarity_threshold: Float 0.0-1.0 - - liveness_required: Boolean - -###### 3.1.4.1.3 Processing -1. Validate system administrator role (requires system_admin permission) -2. Check domain uniqueness across all tenants -3. Create tenant record with status "ACTIVE" -4. Generate tenant-specific API key (HMAC-SHA256 with secret) -5. Initialize default quotas based on subscription plan -6. Create default roles (TENANT_ADMIN, USER) for tenant -7. Create default admin user account for tenant -8. Initialize tenant-specific Redis namespace for caching -9. Create audit log entry - -###### 3.1.4.1.4 Outputs -- **Tenant ID:** UUID of created tenant -- **API Key:** String for tenant API authentication -- **Admin Credentials:** Temporary admin username and password -- **HTTP Status:** 201 Created - -###### 3.1.4.1.5 Error/Data Handling -- **409 Conflict:** If domain already exists (tenant domains must be globally unique) -- **403 Forbidden:** If requester lacks system_admin role -- **400 Bad Request:** If invalid subscription plan or quota settings -- **Transactional:** Rollback all changes if any step fails (tenant, roles, admin user) - ---- - -##### 3.1.4.2 FR-4.2: Tenant Configuration - -###### 3.1.4.2.1 Description -Enables tenant administrators to customize system behavior for their organization, including biometric thresholds, liveness requirements, and rate limiting policies. - -###### 3.1.4.2.2 Inputs -- **Tenant ID:** UUID of tenant to configure -- **Settings:** JSON object with one or more of: - - similarity_threshold: Float 0.5-0.95 (verification threshold) - - liveness_required: Boolean (enforce liveness for all verifications) - - liveness_confidence_threshold: Float 0.8-0.99 - - rate_limit_requests_per_minute: Integer 10-10000 - - session_timeout_minutes: Integer 5-1440 - - biometric_model: Enum (Facenet, ArcFace, VGG-Face) - -###### 3.1.4.2.3 Processing -1. Verify requester has tenant_admin role for target tenant -2. Validate each setting value against allowed ranges -3. Update tenant configuration in tenants table -4. Invalidate cached tenant settings in Redis -5. Notify all active sessions to reload configuration (publish event) -6. Create audit log entry with old and new values - -###### 3.1.4.2.4 Outputs -- **Updated Configuration:** JSON object with all current tenant settings -- **HTTP Status:** 200 OK - -###### 3.1.4.2.5 Error/Data Handling -- **403 Forbidden:** If requester is not tenant admin for this tenant -- **400 Bad Request:** If setting value out of allowed range or invalid setting key -- **Validation:** Reject similarity_threshold > 0.95 (too strict, high false rejection) -- **Validation:** Reject liveness_confidence_threshold < 0.8 (security risk) - ---- - -##### 3.1.4.3 FR-4.3: User Quota Management - -###### 3.1.4.3.1 Description -Tracks and enforces user account limits per tenant based on subscription plan. Prevents quota overruns and provides visibility into current usage. - -###### 3.1.4.3.2 Inputs -- **Tenant ID:** UUID of tenant to query - -###### 3.1.4.3.3 Processing -1. Query current user count for tenant: - ```sql - SELECT COUNT(*) FROM users WHERE tenant_id = :tenant_id AND status = 'ACTIVE' - ``` -2. Retrieve max_users quota from tenant configuration -3. Calculate remaining quota: remaining = max_users - current_count -4. Calculate usage percentage: usage_pct = (current_count / max_users) * 100 - -###### 3.1.4.3.4 Outputs -- **Current Users:** Integer count of active users -- **Max Users:** Integer quota limit -- **Remaining:** Integer available user slots -- **Usage Percentage:** Float 0.0-100.0 -- **HTTP Status:** 200 OK - -###### 3.1.4.3.5 Error/Data Handling -- **403 Forbidden:** If new user registration attempted when remaining = 0 (return quota details) -- **Warning:** Return HTTP 200 with warning header when usage > 90% (approaching limit) -- **Soft Delete:** Deleted users count toward quota for 30 days (prevent quota gaming) - ---- - -##### 3.1.4.4 FR-4.4: Enrollment Quota Management - -###### 3.1.4.4.1 Description -Tracks and enforces biometric enrollment limits per tenant. This controls storage costs and ensures fair resource allocation across tenants. - -###### 3.1.4.4.2 Inputs -- **Tenant ID:** UUID of tenant to query - -###### 3.1.4.4.3 Processing -1. Query current enrollment count for tenant: - ```sql - SELECT COUNT(*) FROM biometric_data WHERE tenant_id = :tenant_id AND status = 'ACTIVE' - ``` -2. Retrieve max_biometric_enrollments quota from tenant configuration -3. Calculate storage usage (embeddings consume ~2KB each for 512D vectors) -4. Calculate remaining quota - -###### 3.1.4.4.4 Outputs -- **Current Enrollments:** Integer count -- **Max Enrollments:** Integer quota -- **Remaining:** Integer available slots -- **Storage Usage MB:** Float estimated storage consumption -- **HTTP Status:** 200 OK - -###### 3.1.4.4.5 Error/Data Handling -- **403 Forbidden:** If new enrollment attempted when quota exceeded -- **Quota Upgrade:** Provide upgrade path in error response for quota expansion -- **Cleanup:** Old enrollments (> 1 year inactive) can be archived to reclaim quota - ---- - -#### 3.1.5 FR-5: Role-Based Access Control - -##### 3.1.5.1 FR-5.1: Role Assignment - -###### 3.1.5.1.1 Description -Assigns roles to users within a tenant scope to control access to system features and data. Supports hierarchical role management with permission validation. - -###### 3.1.5.1.2 Inputs -- **User ID:** UUID of user receiving role -- **Role ID:** UUID of role to assign (must belong to same tenant) - -###### 3.1.5.1.3 Processing -1. Verify assigner has user.assign_role permission (typically tenant_admin) -2. Validate user and role belong to same tenant -3. Check role assignment doesn't create circular dependencies -4. Create user_roles mapping record -5. Invalidate user's cached permissions in Redis -6. Force token refresh if user has active session -7. Create audit log entry - -###### 3.1.5.1.4 Outputs -- **Assignment Confirmation:** Success message with role details -- **HTTP Status:** 201 Created - -###### 3.1.5.1.5 Error/Data Handling -- **403 Forbidden:** If assigner lacks user.assign_role permission -- **400 Bad Request:** If user and role belong to different tenants -- **409 Conflict:** If user already has this role (idempotent - return 200 OK) - ---- - -##### 3.1.5.2 FR-5.2: Permission Check - -###### 3.1.5.2.1 Description -Evaluates whether a user has permission to perform a specific action on a resource. This is called on every API endpoint to enforce authorization policies. - -###### 3.1.5.2.2 Inputs -- **User ID:** UUID of user requesting action -- **Resource:** String identifying resource type (e.g., "user", "biometric_enrollment") -- **Action:** String identifying action (e.g., "create", "read", "update", "delete") - -###### 3.1.5.2.3 Processing -1. Retrieve user's roles from database (or Redis cache) -2. For each role, retrieve associated permissions from role_permissions table -3. Aggregate permissions across all roles (union operation) -4. Check if (resource, action) pair exists in aggregated permissions -5. Apply special rules: - - System admins have all permissions - - Users can always read/update their own profile - - Tenant admins have all permissions within tenant scope -6. Cache result in Redis for 5 minutes - -###### 3.1.5.2.4 Outputs -- **Authorized:** Boolean (true/false) -- **HTTP Status:** Used internally (not exposed via API) - -###### 3.1.5.2.5 Error/Data Handling -- **Fail-Secure:** Return false if database connection fails or user not found -- **Performance:** Use Redis cache aggressively (95%+ cache hit rate expected) -- **Audit:** Log permission denials for security monitoring - ---- - -##### 3.1.5.3 FR-5.3: Custom Role Creation - -###### 3.1.5.3.1 Description -Allows tenant administrators to define custom roles tailored to their organizational structure, selecting from available system permissions. - -###### 3.1.5.3.2 Inputs -- **Tenant ID:** UUID of tenant creating role -- **Role Name:** String (e.g., "Enrollment Operator") -- **Permissions:** Array of permission objects (resource + action pairs) - -###### 3.1.5.3.3 Processing -1. Verify requester has tenant_admin role -2. Validate role name uniqueness within tenant -3. Validate all requested permissions are valid system permissions -4. Create role record with tenant scope -5. Create role_permissions mappings for each permission -6. Return created role with full permission details - -###### 3.1.5.3.4 Outputs -- **Role ID:** UUID of created role -- **Role Details:** Object with name, description, permissions array -- **HTTP Status:** 201 Created - -###### 3.1.5.3.5 Error/Data Handling -- **403 Forbidden:** If requester is not tenant admin -- **400 Bad Request:** If attempting to assign system-level permissions (e.g., create_tenant) -- **409 Conflict:** If role name already exists within tenant - ---- - -#### 3.1.6 FR-6: Audit and Compliance - -##### 3.1.6.1 FR-6.1: Audit Logging - -###### 3.1.6.1.1 Description -Creates immutable audit trail records for all security-relevant actions within the system. Supports compliance with GDPR, HIPAA, and SOC 2 requirements. - -###### 3.1.6.1.2 Inputs -- **Action:** String describing action performed (e.g., "USER_LOGIN", "BIOMETRIC_ENROLLMENT") -- **Resource:** String identifying affected resource (e.g., "user:123e4567") -- **User:** UUID of user performing action -- **Details:** JSON object with action-specific metadata - -###### 3.1.6.1.3 Processing -1. Capture contextual metadata: - - Timestamp (UTC with microsecond precision) - - IP address from request - - User agent string - - Session ID if applicable -2. Create audit_logs record (append-only table) -3. Async write to prevent blocking API response -4. Async replication to separate audit database (for tamper resistance) -5. Retain logs for minimum 90 days (configurable up to 7 years) - -###### 3.1.6.1.4 Outputs -- **Audit Log ID:** UUID of created record -- **HTTP Status:** N/A (internal operation) - -###### 3.1.6.1.5 Error/Data Handling -- **Write Failures:** Queue failed logs for retry (critical priority) -- **Immutability:** Audit logs cannot be updated or deleted (enforced by database constraints) -- **Async Processing:** Use message queue to avoid impacting API latency - ---- - -##### 3.1.6.2 FR-6.2: Audit Log Query - -###### 3.1.6.2.1 Description -Provides tenant administrators with ability to search and retrieve audit logs for compliance reporting and security investigations. - -###### 3.1.6.2.2 Inputs -- **Tenant ID:** UUID of tenant (enforced tenant isolation) -- **Filters:** JSON object with optional filters: - - action: String or array (e.g., ["USER_LOGIN", "BIOMETRIC_ENROLLMENT"]) - - user_id: UUID - - date_from: ISO 8601 timestamp - - date_to: ISO 8601 timestamp - - resource: String pattern -- **Pagination:** Object with offset and limit (max 1000 records per request) - -###### 3.1.6.2.3 Processing -1. Verify requester has audit.read permission (tenant_admin role) -2. Build query with tenant_id filter (strict row-level security) -3. Apply additional filters from request -4. Execute paginated query on audit_logs table -5. Return results with total count for pagination - -###### 3.1.6.2.4 Outputs -- **Audit Records:** JSON array of log objects with timestamp, action, user, details -- **Total Count:** Integer total matching records (for pagination) -- **HTTP Status:** 200 OK - -###### 3.1.6.2.5 Error/Data Handling -- **403 Forbidden:** If requester lacks audit.read permission or attempts cross-tenant query -- **Performance:** Enforce max date range of 90 days per query (prevent expensive scans) -- **Retention:** Records older than retention period return 410 Gone - ---- - -##### 3.1.6.3 FR-6.3: Verification History - -###### 3.1.6.3.1 Description -Retrieves historical biometric verification attempts for a specific user to support security investigations and user self-service. - -###### 3.1.6.3.2 Inputs -- **User ID:** UUID of user to query -- **Pagination:** Optional offset and limit - -###### 3.1.6.3.3 Processing -1. Verify requester is user themselves OR has tenant_admin role -2. Query verification_logs table filtered by user_id -3. Include: timestamp, result (MATCH/NO_MATCH), similarity score, IP address -4. Order by timestamp descending (most recent first) -5. Apply pagination - -###### 3.1.6.3.4 Outputs -- **Verification Logs:** JSON array with verification attempt details -- **Total Count:** Integer count of all verification attempts -- **HTTP Status:** 200 OK - -###### 3.1.6.3.5 Error/Data Handling -- **403 Forbidden:** If requester is not user or tenant admin -- **Privacy:** Exclude raw biometric data from response (only similarity scores) -- **Retention:** Verification logs retained for 90 days - -### 3.2 Non-Functional Requirements - -#### NFR-1: Performance - -| ID | Requirement | Metric | Target | -|----|-------------|--------|--------| -| NFR-1.1 | API Response Time | 95th percentile latency | < 200ms for authentication endpoints | -| NFR-1.2 | Face Detection | Processing time | < 500ms per image (MTCNN detector on CPU) | -| NFR-1.3 | Embedding Generation | Processing time (CPU) | < 1s per face (tested on Intel i7-9700K @ 3.6GHz, 8 cores) | -| NFR-1.4 | Vector Search | Query time (1M vectors) | < 100ms with IVFFlat index (lists=100, probes=10) | -| NFR-1.5 | Concurrent Users | Simultaneous requests | 100 concurrent users per instance (8GB RAM, 4 vCPU) | -| NFR-1.6 | Throughput | Requests per second | 500 RPS for authentication (with Redis caching) | - -#### NFR-2: Reliability - -| ID | Requirement | Metric | Target | -|----|-------------|--------|--------| -| NFR-2.1 | System Availability | Uptime (monthly) | 99.5% (允 3.6 hours downtime/month for maintenance windows) | -| NFR-2.2 | Recovery Time Objective (RTO) | Service restoration | < 15 minutes for critical services (auth, verification) | -| NFR-2.3 | Mean Time To Recovery (MTTR) | Average downtime | < 1 hour for non-critical incidents | -| NFR-2.4 | Data Durability | Recovery Point Objective (RPO) | < 1 hour (automated PostgreSQL backups every 30 minutes) | -| NFR-2.5 | Graceful Degradation | Service isolation | Single service failure does not cascade (circuit breakers implemented) | -| NFR-2.6 | Error Rate | Failed requests | < 0.1% under normal load (excluding client errors 4xx) | - -#### NFR-3: Security - -| ID | Requirement | Implementation | -|----|-------------|----------------| -| NFR-3.1 | Transport Security | TLS 1.3 for all communications | -| NFR-3.2 | Password Storage | BCrypt with work factor 12 | -| NFR-3.3 | Token Security | JWT with HS512, 15-minute access token expiry | -| NFR-3.4 | Biometric Data | Embeddings only (no raw images stored), encrypted at rest | -| NFR-3.5 | Rate Limiting | Token bucket algorithm, 100 requests/minute per user | -| NFR-3.6 | SQL Injection | Parameterized queries via JPA/SQLAlchemy | -| NFR-3.7 | XSS Protection | Content Security Policy headers | -| NFR-3.8 | CORS | Configurable allowed origins | - -#### NFR-4: Usability - -| ID | Requirement | Target | -|----|-------------|--------| -| NFR-4.1 | Enrollment Time | < 60 seconds for complete face enrollment | -| NFR-4.2 | Verification Time | < 5 seconds for 1:1 verification | -| NFR-4.3 | Liveness Challenge | < 30 seconds for 3-step puzzle | -| NFR-4.4 | API Documentation | OpenAPI 3.0 with interactive Swagger UI | -| NFR-4.5 | Error Messages | Human-readable with error codes | - -#### NFR-5: Maintainability - -| ID | Requirement | Implementation | -|----|-------------|----------------| -| NFR-5.1 | Code Architecture | Hexagonal Architecture (Ports & Adapters) | -| NFR-5.2 | Test Coverage | > 70% unit test coverage | -| NFR-5.3 | Code Standards | Checkstyle (Java), Ruff/Flake8 (Python), ESLint (TypeScript) | -| NFR-5.4 | Documentation | Inline documentation, architecture decision records | -| NFR-5.5 | Dependency Management | Gradle (Java), Poetry (Python), npm (TypeScript) | - -#### NFR-6: Portability - -| ID | Requirement | Implementation | -|----|-------------|----------------| -| NFR-6.1 | Containerization | Docker images for all services | -| NFR-6.2 | Database | PostgreSQL 16 with standard extensions | -| NFR-6.3 | Cross-Platform Clients | Kotlin Multiplatform (95% shared code) | -| NFR-6.4 | Configuration | Environment variables, externalized config | - -#### NFR-7: Scalability - -| ID | Requirement | Metric | Target | -|----|-------------|--------|--------| -| NFR-7.1 | Tenant Capacity | Max tenants per instance | 1,000 tenants (with resource quotas enforced) | -| NFR-7.2 | User Capacity | Max users per tenant | 100,000 users (configurable per subscription tier) | -| NFR-7.3 | Biometric Enrollments | Max face embeddings | 1,000,000 vectors per PostgreSQL instance (with pgvector IVFFlat indexing) | -| NFR-7.4 | Horizontal Scaling | Stateless services | Identity Core and Biometric Processor support multiple replicas (session state in Redis) | -| NFR-7.5 | Database Sharding | Future capability | Database schema supports tenant-based sharding (not implemented in MVP) | -| NFR-7.6 | Vector Search Performance | Linear scaling | Query time increases linearly O(log n) with IVFFlat, not exponentially | - ---- - -## 4. System Design - -### 4.1 Use Case Diagrams - -#### 4.1.1 System Use Cases by Actor - -```mermaid -graph TB - subgraph Actors - EU((End User)) - TA((Tenant Admin)) - SA((System Admin)) - EXT((External System)) - end - - subgraph "User Management" - UC1[Register Account] - UC2[Login/Logout] - UC3[Reset Password] - UC4[Update Profile] - end - - subgraph "Biometric Operations" - UC5[Enroll Face] - UC6[Verify Identity] - UC7[Complete Liveness Challenge] - UC8[View Verification History] - end - - subgraph "Tenant Administration" - UC9[Manage Tenant Users] - UC10[View Analytics] - UC11[Configure Settings] - UC12[View Audit Logs] - end - - subgraph "System Administration" - UC13[Manage Tenants] - UC14[System Configuration] - UC15[Monitor Health] - UC16[Security Management] - end - - subgraph "API Integration" - UC17[Authenticate via API] - UC18[Verify via API] - UC19[Receive Webhooks] - end - - EU --> UC1 & UC2 & UC3 & UC4 - EU --> UC5 & UC6 & UC7 & UC8 - - TA --> UC2 & UC4 - TA --> UC9 & UC10 & UC11 & UC12 - - SA --> UC2 - SA --> UC13 & UC14 & UC15 & UC16 - - EXT --> UC17 & UC18 & UC19 -``` - -#### 4.1.2 Face Enrollment Use Case - -**Use Case:** Enroll Face -**Primary Actor:** End User -**Preconditions:** User is authenticated, has biometric.enroll permission, tenant enrollment quota not exceeded -**Postconditions:** Face embedding stored, enrollment record created - -**Main Flow:** -1. User initiates enrollment from client application -2. System requests liveness challenge -3. User completes Biometric Puzzle (3-5 random actions) -4. System verifies liveness with >95% confidence -5. System captures final face image -6. System performs quality assessment (brightness, sharpness, pose) -7. System generates face embedding using configured model -8. System stores embedding in biometric_data table with pgvector -9. System returns enrollment confirmation with quality score - -**Alternative Flows:** -- 3a. Liveness challenge fails: System requests retry (max 3 attempts) -- 6a. Quality insufficient: System provides guidance and requests new capture -- 8a. Duplicate enrollment exists: System prompts for re-enrollment confirmation - -#### 4.1.3 Face Verification Use Case - -**Use Case:** Verify Identity -**Primary Actor:** End User / External System -**Preconditions:** User has active enrollment, verification request includes valid face image -**Postconditions:** Verification logged, result returned - -**Main Flow:** -1. Client submits verification request with face image -2. System checks rate limits (token bucket) -3. System performs face detection -4. System generates embedding from probe image -5. System retrieves enrolled embedding for user -6. System computes cosine similarity -7. System compares against configured threshold (default 0.6) -8. System logs verification attempt -9. System returns match result with confidence score - -**Alternative Flows:** -- 2a. Rate limit exceeded: Return 429 Too Many Requests -- 3a. No face detected: Return 400 Bad Request with guidance -- 7a. Score below threshold: Return verification failed - -#### 4.1.4 Sequence Diagrams - -This subsection presents UML sequence diagrams illustrating the temporal interactions among system components for critical use cases, fulfilling CSE4197 ADD requirements for behavioral modeling. - -##### 4.1.4.1 User Registration Sequence - -The following diagram shows the complete user registration flow, including tenant validation, password hashing, and JWT token generation. - -```mermaid -sequenceDiagram - actor User - participant WebApp as Web/Mobile Client - participant NGINX as API Gateway - participant IdentityAPI as Identity Core API - participant DB as PostgreSQL - participant Redis as Redis Cache - - User->>WebApp: Enter registration details - WebApp->>NGINX: POST /api/v1/auth/register
{email, password, firstName, lastName, tenantId} - NGINX->>IdentityAPI: Forward request - - IdentityAPI->>IdentityAPI: Validate input format
(RFC 5322 email) - - IdentityAPI->>DB: SELECT * FROM tenants
WHERE id = :tenantId - DB-->>IdentityAPI: Tenant record - - alt Tenant not found or inactive - IdentityAPI-->>WebApp: 404 Not Found - WebApp-->>User: "Invalid tenant" - else Tenant active - IdentityAPI->>DB: SELECT COUNT(*) FROM users
WHERE tenant_id = :tenantId
AND email = :email - DB-->>IdentityAPI: Count (0 or 1) - - alt Email already exists - IdentityAPI-->>WebApp: 409 Conflict - WebApp-->>User: "Email already registered" - else Email unique - IdentityAPI->>IdentityAPI: Hash password
(BCrypt, work factor 12) - - IdentityAPI->>DB: INSERT INTO users
(id, tenant_id, email, password_hash,
first_name, last_name, created_at) - DB-->>IdentityAPI: User created (UUID) - - IdentityAPI->>IdentityAPI: Generate JWT access token
(HS512, 15min expiry) - IdentityAPI->>IdentityAPI: Generate refresh token
(UUID, 7 days) - - IdentityAPI->>DB: INSERT INTO refresh_tokens
(token, user_id, expires_at) - DB-->>IdentityAPI: Token stored - - IdentityAPI->>Redis: SET session:{userId}
TTL 900 seconds - Redis-->>IdentityAPI: OK - - IdentityAPI-->>WebApp: 201 Created
{accessToken, refreshToken, user} - WebApp->>WebApp: Store tokens in secure storage - WebApp-->>User: "Registration successful" - end - end -``` - -**Key Interactions:** -1. **Input Validation** (lines 9-10): Email format validated against RFC 5322 before database operations -2. **Tenant Isolation** (lines 12-13): Tenant existence verified to enforce multi-tenancy constraints -3. **Uniqueness Check** (lines 19-20): Email uniqueness checked within tenant scope (not globally) -4. **Security** (lines 25-26): Password hashed with BCrypt (work factor 12) before storage -5. **Stateless Auth** (lines 31-34): JWT access token for API authentication, refresh token for renewal -6. **Session Management** (lines 37-38): Session cached in Redis for fast lookup - -##### 4.1.4.2 Biometric Enrollment with Liveness Sequence - -This diagram illustrates the complete face enrollment process, including active liveness detection (Biometric Puzzle) and embedding generation. - -```mermaid -sequenceDiagram - actor User - participant MobileApp as Mobile/Desktop Client - participant BiometricAPI as Biometric Processor - participant IdentityAPI as Identity Core API - participant DeepFace as DeepFace Library - participant MediaPipe as MediaPipe - participant DB as PostgreSQL (pgvector) - - User->>MobileApp: Navigate to Enrollment - MobileApp->>BiometricAPI: POST /api/v1/liveness/challenge - BiometricAPI->>BiometricAPI: Generate random challenge sequence
(e.g., [BLINK, SMILE, TURN_LEFT]) - BiometricAPI-->>MobileApp: {challengeId, sequence, timeout: 30s} - - MobileApp-->>User: Display "Please blink your eyes" - User->>MobileApp: Blink action - MobileApp->>MobileApp: Capture video frames (30 FPS) - - loop For each frame (max 900 frames) - MobileApp->>MediaPipe: Detect facial landmarks - MediaPipe-->>MobileApp: 468 landmark coordinates - MobileApp->>MobileApp: Calculate EAR (Eye Aspect Ratio) - end - - MobileApp->>MobileApp: Detect EAR drop
(threshold < 0.25) - MobileApp-->>User: ✓ "Blink detected"
Display "Now smile" - - User->>MobileApp: Smile action - loop For each frame - MobileApp->>MediaPipe: Detect landmarks - MediaPipe-->>MobileApp: Landmark coordinates - MobileApp->>MobileApp: Calculate MAR (Mouth Aspect Ratio) - end - - MobileApp->>MobileApp: Detect MAR increase
(threshold > 0.5) - MobileApp-->>User: ✓ "Smile detected"
Display "Turn head left" - - User->>MobileApp: Turn head left - MobileApp->>MobileApp: Calculate head pose
(yaw angle) - MobileApp->>MobileApp: Detect yaw < -15° - MobileApp-->>User: ✓ "Challenge complete" - - MobileApp->>BiometricAPI: POST /api/v1/liveness/verify
{challengeId, frames[], landmarks[]} - BiometricAPI->>BiometricAPI: Verify challenge completion
(sequence + timing) - BiometricAPI->>BiometricAPI: Passive anti-spoofing
(LBP texture, moire detection) - - alt Liveness failed - BiometricAPI-->>MobileApp: 403 Forbidden
{reason: "SPOOF_DETECTED"} - MobileApp-->>User: "Liveness check failed" - else Liveness passed - BiometricAPI-->>MobileApp: 200 OK
{livenessToken, confidence: 0.95} - - MobileApp-->>User: "Capture enrollment photo" - User->>MobileApp: Capture high-quality image - - MobileApp->>BiometricAPI: POST /api/v1/enroll
{userId, image, livenessToken} - BiometricAPI->>BiometricAPI: Validate liveness token
(5-minute expiry) - - BiometricAPI->>DeepFace: detect_face(image) - DeepFace-->>BiometricAPI: {face_region, confidence: 0.98} - - alt No face detected - BiometricAPI-->>MobileApp: 400 Bad Request - MobileApp-->>User: "No face detected" - else Face detected - BiometricAPI->>DeepFace: analyze_quality(face_region) - DeepFace-->>BiometricAPI: {quality_score: 0.82, brightness, sharpness} - - alt Quality insufficient (<0.5) - BiometricAPI-->>MobileApp: 422 Unprocessable Entity - MobileApp-->>User: "Image quality too low" - else Quality sufficient - BiometricAPI->>DeepFace: represent(face_region, model='Facenet512') - DeepFace-->>BiometricAPI: embedding[512] (normalized vector) - - BiometricAPI->>IdentityAPI: GET /api/v1/users/{userId} - IdentityAPI-->>BiometricAPI: {userId, tenantId, permissions} - - BiometricAPI->>DB: INSERT INTO biometric_data
(user_id, tenant_id, embedding,
model_name, quality_score) - DB-->>BiometricAPI: Enrollment ID - - BiometricAPI->>DB: CREATE INDEX IF NOT EXISTS
USING ivfflat (embedding vector_cosine_ops)
WITH (lists = 100) - DB-->>BiometricAPI: Index updated - - BiometricAPI-->>MobileApp: 201 Created
{enrollmentId, qualityScore: 0.82} - MobileApp-->>User: "Enrollment successful!" - end - end - end -``` - -**Key Interactions:** -1. **Challenge Generation** (lines 9-11): Random 3-step sequence prevents replay attacks -2. **Real-time Landmark Tracking** (lines 17-22): MediaPipe processes 30 FPS for blink detection -3. **Biometric Puzzle Validation** (lines 43-45): Server-side verification of action sequence and timing -4. **Two-Factor Liveness** (lines 47-48): Active (challenge) + passive (texture analysis) combined -5. **Token-Based Enrollment** (lines 57-58): Liveness token valid for 5 minutes to prevent reuse -6. **Quality Gating** (lines 68-72): Enrollment rejected if image quality below threshold -7. **Vector Indexing** (lines 83-86): IVFFlat index automatically updated for fast similarity search - -##### 4.1.4.3 Face Search (1:N Identification) Sequence - -This diagram shows the workflow for identifying an unknown face against all enrolled users within a tenant. - -```mermaid -sequenceDiagram - actor User - participant System as External System - participant BiometricAPI as Biometric Processor - participant DeepFace as DeepFace Library - participant DB as PostgreSQL (pgvector) - participant Redis as Redis Cache - - User->>System: Present face to camera - System->>System: Capture image - - System->>BiometricAPI: POST /api/v1/search
{image, tenantId, topK: 10, threshold: 0.7} - BiometricAPI->>BiometricAPI: Validate tenant authorization - - BiometricAPI->>DeepFace: detect_face(image) - DeepFace-->>BiometricAPI: {face_region, confidence: 0.96} - - alt No face detected - BiometricAPI-->>System: 400 Bad Request
{error: "NO_FACE_DETECTED"} - System-->>User: "Face not visible" - else Face detected - BiometricAPI->>DeepFace: represent(face_region, model='Facenet512') - DeepFace-->>BiometricAPI: query_embedding[512] - - Note over BiometricAPI,Redis: Check cache for recent searches - BiometricAPI->>Redis: GET search:hash(query_embedding) - Redis-->>BiometricAPI: NULL (cache miss) - - BiometricAPI->>DB: SELECT user_id, embedding,
1 - (embedding <=> :query) AS similarity
FROM biometric_data
WHERE tenant_id = :tenantId
AND 1 - (embedding <=> :query) > :threshold
ORDER BY embedding <=> :query
LIMIT :topK - - Note over DB: pgvector uses IVFFlat index
for approximate nearest neighbor search
(lists=100, probes=10) - - DB-->>BiometricAPI: Top-10 matches with similarity scores - - alt No matches above threshold - BiometricAPI-->>System: 404 Not Found
{message: "No matching identity"} - System-->>User: "Identity not recognized" - else Matches found - BiometricAPI->>BiometricAPI: Rank by similarity score
(highest first) - - BiometricAPI->>Redis: SETEX search:hash(query_embedding)
results, TTL 60 seconds - Redis-->>BiometricAPI: OK - - BiometricAPI-->>System: 200 OK
{matches: [{userId, similarity: 0.94},
{userId, similarity: 0.88}, ...]} - - System->>System: Select top match (similarity: 0.94) - System-->>User: "Welcome, [User Name]"
Grant access - end - end -``` - -**Key Interactions:** -1. **Tenant Isolation** (line 10): Search scope limited to tenant's enrollments only -2. **Face Detection** (lines 12-13): Pre-processing ensures valid face before expensive vector search -3. **Embedding Generation** (lines 19-20): Query face converted to 512-D Facenet embedding -4. **Cache Layer** (lines 23-24): Redis caches recent searches for 60 seconds (repeated kiosk access) -5. **Vector Similarity Search** (lines 26-31): pgvector's `<=>` operator performs cosine distance search -6. **IVFFlat Optimization** (lines 33-35): Approximate nearest neighbor (ANN) search with index lists=100, probes=10 -7. **Threshold Filtering** (line 38): Only matches above 0.7 similarity (configurable per tenant) returned -8. **Result Caching** (lines 46-47): Successful searches cached to reduce database load - ---- - -### 4.2 Class and ER Diagrams - -#### 4.2.1 Domain Model - Core Entities - -```mermaid -classDiagram - class Tenant { - +UUID id - +String name - +String domain - +String displayName - +Boolean isActive - +String subscriptionPlan - +Integer maxUsers - +Integer maxBiometricEnrollments - +JSONB settings - +LocalDateTime createdAt - +activate() - +suspend() - +updateSettings() - } - - class User { - +UUID id - +UUID tenantId - +String email - +String passwordHash - +String firstName - +String lastName - +Boolean emailVerified - +Boolean isActive - +Boolean isLocked - +Integer failedLoginAttempts - +LocalDateTime lastLoginAt - +authenticate() - +changePassword() - +assignRole() - } - - class Role { - +UUID id - +UUID tenantId - +String name - +String description - +Boolean isSystemRole - +Set~Permission~ permissions - +addPermission() - +removePermission() - } - - class Permission { - +UUID id - +String name - +String resource - +String action - } - - class BiometricData { - +UUID id - +UUID userId - +UUID tenantId - +BiometricType type - +Vector embedding - +String embeddingModel - +Integer embeddingDimension - +Float qualityScore - +Boolean livenessVerified - +LocalDateTime enrolledAt - +compare(Vector) Float - } - - class VerificationLog { - +UUID id - +UUID userId - +UUID tenantId - +Boolean verified - +Float confidenceScore - +Float similarityDistance - +String modelUsed - +Integer processingTimeMs - +LocalDateTime verifiedAt - } - - class AuditLog { - +UUID id - +UUID tenantId - +UUID userId - +String action - +String resourceType - +UUID resourceId - +JSONB oldValues - +JSONB newValues - +String ipAddress - +LocalDateTime createdAt - } - - Tenant "1" --> "*" User : contains - User "1" --> "*" Role : has - Role "1" --> "*" Permission : grants - User "1" --> "0..1" BiometricData : has - User "1" --> "*" VerificationLog : performs - Tenant "1" --> "*" AuditLog : contains -``` - -#### 4.2.2 Entity Relationship Diagram - -```mermaid -erDiagram - TENANTS { - uuid id PK - varchar name UK - varchar domain UK - varchar display_name - boolean is_active - varchar subscription_plan - integer max_users - integer max_biometric_enrollments - varchar contact_email - jsonb settings - jsonb metadata - timestamp created_at - timestamp updated_at - timestamp deleted_at - } - - USERS { - uuid id PK - uuid tenant_id FK - varchar email - varchar password_hash - varchar first_name - varchar last_name - boolean email_verified - boolean is_active - boolean is_locked - integer failed_login_attempts - timestamp last_login_at - varchar language - varchar timezone - jsonb preferences - timestamp created_at - timestamp updated_at - timestamp deleted_at - } - - ROLES { - uuid id PK - uuid tenant_id FK - varchar name - varchar description - boolean is_system_role - boolean is_active - jsonb metadata - timestamp created_at - timestamp updated_at - timestamp deleted_at - } - - PERMISSIONS { - uuid id PK - varchar name UK - varchar description - varchar resource - varchar action - jsonb metadata - timestamp created_at - timestamp updated_at - } - - ROLE_PERMISSIONS { - uuid role_id PK,FK - uuid permission_id PK,FK - timestamp granted_at - uuid granted_by FK - } - - USER_ROLES { - uuid user_id PK,FK - uuid role_id PK,FK - timestamp assigned_at - uuid assigned_by FK - timestamp expires_at - } - - BIOMETRIC_DATA { - uuid id PK - uuid user_id FK - uuid tenant_id FK - biometric_type biometric_type - vector embedding - varchar embedding_model - integer embedding_dimension - float quality_score - biometric_quality quality_level - boolean liveness_verified - float liveness_score - varchar liveness_method - boolean is_active - boolean is_primary - timestamp enrolled_at - varchar enrolled_from_ip - timestamp expires_at - jsonb metadata - timestamp created_at - timestamp updated_at - timestamp deleted_at - } - - LIVENESS_ATTEMPTS { - uuid id PK - uuid user_id FK - uuid tenant_id FK - uuid puzzle_id - jsonb puzzle_steps - boolean success - integer steps_completed - integer total_steps - float completion_time_seconds - text error_message - varchar ip_address - text user_agent - jsonb device_info - timestamp attempted_at - } - - BIOMETRIC_VERIFICATION_LOGS { - uuid id PK - uuid user_id FK - uuid tenant_id FK - uuid biometric_data_id FK - boolean verified - float confidence_score - float similarity_distance - float threshold_used - varchar model_used - varchar verification_type - boolean success - varchar failure_reason - varchar ip_address - integer processing_time_ms - timestamp verified_at - } - - AUDIT_LOGS { - uuid id PK - uuid tenant_id FK - uuid user_id FK - varchar action - varchar resource_type - uuid resource_id - varchar http_method - varchar endpoint - integer status_code - jsonb old_values - jsonb new_values - boolean success - text error_message - varchar ip_address - text user_agent - integer response_time_ms - jsonb metadata - timestamp created_at - } - - REFRESH_TOKENS { - uuid id PK - uuid user_id FK - uuid tenant_id FK - varchar token_hash UK - varchar device_id - varchar device_name - varchar device_type - boolean is_active - boolean is_revoked - timestamp revoked_at - timestamp expires_at - timestamp last_used_at - integer usage_count - timestamp created_at - } - - ACTIVE_SESSIONS { - uuid id PK - uuid user_id FK - uuid tenant_id FK - varchar session_token_hash UK - varchar device_id - varchar device_type - varchar ip_address - boolean is_active - timestamp last_activity_at - timestamp expires_at - timestamp created_at - } - - SECURITY_EVENTS { - uuid id PK - uuid tenant_id FK - uuid user_id FK - varchar event_type - varchar severity - text description - varchar ip_address - varchar action_taken - boolean resolved - timestamp resolved_at - jsonb metadata - timestamp created_at - } - - RATE_LIMITS { - uuid id PK - uuid tenant_id FK - uuid user_id FK - varchar endpoint - varchar bucket_key UK - integer tokens - integer max_tokens - timestamp last_refill - integer refill_rate - timestamp created_at - timestamp updated_at - } - - TENANTS ||--o{ USERS : contains - TENANTS ||--o{ ROLES : defines - USERS ||--o{ USER_ROLES : has - ROLES ||--o{ USER_ROLES : assigned_to - ROLES ||--o{ ROLE_PERMISSIONS : has - PERMISSIONS ||--o{ ROLE_PERMISSIONS : granted_by - USERS ||--o| BIOMETRIC_DATA : has - USERS ||--o{ LIVENESS_ATTEMPTS : attempts - USERS ||--o{ BIOMETRIC_VERIFICATION_LOGS : logs - USERS ||--o{ REFRESH_TOKENS : has - USERS ||--o{ ACTIVE_SESSIONS : has - TENANTS ||--o{ AUDIT_LOGS : contains - TENANTS ||--o{ SECURITY_EVENTS : monitors - TENANTS ||--o{ RATE_LIMITS : limits -``` - -### 4.3 User Interface Design - -#### 4.3.1 Web Admin Dashboard - -The web admin dashboard is built with React 18 and Material-UI v5, providing a responsive interface for tenant administrators. - -**Implemented Pages:** - -| Page | Route | Description | -|------|-------|-------------| -| Login | `/login` | Email/password authentication with remember me | -| Dashboard | `/dashboard` | Analytics overview, enrollment statistics, verification trends | -| Users | `/users` | User management with CRUD operations, role assignment | -| Tenants | `/tenants` | Tenant list and configuration (super admin only) | -| Enrollments | `/enrollments` | Biometric enrollment records with quality scores | -| Audit Logs | `/audit-logs` | Searchable, filterable audit trail | -| Settings | `/settings` | Tenant configuration, thresholds, rate limits | - -**UI Architecture:** -- Feature-based folder structure (`features/auth/`, `features/users/`) -- Inversify dependency injection container -- Mock and real repository implementations for development/production -- Redux Toolkit for state management - -#### 4.3.2 Mobile Application (Android) - -The Android application uses Kotlin Multiplatform with Compose Multiplatform UI. - -**Implemented Screens:** - -| Screen | Description | -|--------|-------------| -| Login | Email/password authentication | -| Register | New user registration | -| Home | User profile, enrollment status | -| Enroll | Face capture with quality feedback, liveness challenge | -| Verify | Face verification with real-time feedback | - -**Technical Implementation:** -- CameraX for camera access and face capture -- Koin for dependency injection -- Ktor for HTTP communication -- Coroutines for async operations - -#### 4.3.3 Desktop Application - -Desktop application targets Windows, Linux, and macOS using Kotlin Multiplatform. - -**Modes:** -1. **Kiosk Mode**: Self-service terminal for enrollment and verification -2. **Admin Dashboard**: Desktop version of web admin functionality - -**Technical Implementation:** -- JavaCV for camera access (cross-platform) -- Compose Desktop for UI -- Same shared code as mobile (95% reuse) - -### 4.4 Test Plan - -#### 4.4.1 Test Strategy - -| Test Level | Scope | Tools | Coverage Target | -|------------|-------|-------|-----------------| -| Unit Tests | Individual classes and functions | JUnit 5, pytest, Vitest | > 70% | -| Integration Tests | Service interactions, database | Testcontainers, pytest | API contracts | -| E2E Tests | Full user flows | Playwright, Espresso | Critical paths | -| Performance Tests | Load and stress | k6, Locust | NFR targets | -| Security Tests | Vulnerability scanning | OWASP ZAP, Snyk | OWASP Top 10 | - -#### 4.4.2 Test Cases - Identity Core API - -| Test ID | Category | Description | Expected Result | -|---------|----------|-------------|-----------------| -| TC-AUTH-001 | Authentication | Valid login with correct credentials | 200 OK, JWT tokens returned | -| TC-AUTH-002 | Authentication | Login with invalid password | 401 Unauthorized | -| TC-AUTH-003 | Authentication | Login to locked account | 423 Locked | -| TC-AUTH-004 | Authentication | Token refresh with valid refresh token | 200 OK, new tokens | -| TC-AUTH-005 | Authentication | Token refresh with revoked token | 401 Unauthorized | -| TC-USER-001 | User Management | Create user with valid data | 201 Created | -| TC-USER-002 | User Management | Create user with duplicate email | 409 Conflict | -| TC-USER-003 | User Management | Update user profile | 200 OK | -| TC-RBAC-001 | Authorization | Access with sufficient permissions | 200 OK | -| TC-RBAC-002 | Authorization | Access with insufficient permissions | 403 Forbidden | -| TC-TENANT-001 | Multi-tenancy | User cannot access other tenant data | 404 Not Found | - -#### 4.4.3 Test Cases - Biometric Processor - -| Test ID | Category | Description | Expected Result | -|---------|----------|-------------|-----------------| -| TC-BIO-001 | Face Detection | Valid face image | Face detected with coordinates | -| TC-BIO-002 | Face Detection | Image without face | No face detected error | -| TC-BIO-003 | Quality | High quality image | Score > 0.8 | -| TC-BIO-004 | Quality | Blurry image | Score < 0.5 | -| TC-BIO-005 | Enrollment | Valid enrollment | Embedding stored | -| TC-BIO-006 | Verification | Matching faces | Similarity > threshold | -| TC-BIO-007 | Verification | Non-matching faces | Similarity < threshold | -| TC-LIVE-001 | Liveness | Valid blink detection | EAR drop detected | -| TC-LIVE-002 | Liveness | Valid smile detection | MAR increase detected | -| TC-LIVE-003 | Liveness | Static photo attack | Spoof detected | - -#### 4.4.4 Current Test Coverage - -| Service | Test Files | Test Cases | Coverage | -|---------|------------|------------|----------| -| Identity Core API | 29 | 156 | 72% | -| Biometric Processor | 18 | 89 | 68% | -| Web App | 10 | 45 | 65% | -| Client Apps (shared) | 50+ | 120 | 75% | - -#### 4.4.5 Test Timeline and Resource Allocation - -This subsection provides estimated calendar time required for testing tasks, fulfilling CSE4197 ADD requirements for temporal planning. - -**Testing Phase Schedule (Semester 1: September 2025 - January 2026)** - -| Task No | Test Task / Milestone | Responsible | Estimated Hours | Week | Deadline | Status | -|---------|----------------------|-------------|-----------------|------|----------|--------| -| **Phase 1: Unit Testing** | -| T-1.1 | Identity Core - Unit Tests (User, Auth, Token services) | AAG | 16 hours | Week 4-5 | Oct 13, 2025 | ✓ Complete | -| T-1.2 | Biometric Processor - Unit Tests (Enrollment, Verification) | AA | 18 hours | Week 4-6 | Oct 20, 2025 | ✓ Complete | -| T-1.3 | Liveness Detection - Unit Tests (EAR, MAR, Spoof detection) | AA | 12 hours | Week 6-7 | Oct 27, 2025 | ✓ Complete | -| T-1.4 | Client Apps - Unit Tests (ViewModels, Use Cases) | AGE | 14 hours | Week 5-7 | Oct 27, 2025 | ✓ Complete | -| **Phase 2: Integration Testing** | -| T-2.1 | Identity Core ↔ PostgreSQL (RBAC, Multi-tenancy) | AAG | 12 hours | Week 8-9 | Nov 10, 2025 | ✓ Complete | -| T-2.2 | Biometric Processor ↔ pgvector (Embedding storage/search) | AA | 10 hours | Week 8-9 | Nov 10, 2025 | ✓ Complete | -| T-2.3 | Identity Core ↔ Redis (Session management, caching) | AAG | 8 hours | Week 9 | Nov 17, 2025 | ✓ Complete | -| T-2.4 | Biometric Processor ↔ DeepFace (Model integration) | AA | 6 hours | Week 7 | Nov 3, 2025 | ✓ Complete | -| **Phase 3: End-to-End Testing** | -| T-3.1 | User Registration → Login → Biometric Enrollment | Team | 16 hours | Week 10-11 | Nov 24, 2025 | ✓ Complete | -| T-3.2 | Liveness Challenge → Verification → Access Grant | Team | 14 hours | Week 11-12 | Dec 1, 2025 | ✓ Complete | -| T-3.3 | Multi-tenant Isolation (Cross-tenant data access prevention) | AAG | 10 hours | Week 12 | Dec 8, 2025 | ✓ Complete | -| T-3.4 | Mobile App → Backend Integration Tests | AGE | 12 hours | Week 13-14 | Dec 22, 2025 | In Progress | -| **Phase 4: Performance Testing** | -| T-4.1 | API Load Testing (100 concurrent users, 500 RPS) | AAG | 8 hours | Week 14 | Dec 22, 2025 | Pending | -| T-4.2 | Vector Search Benchmark (1K, 10K, 100K embeddings) | AA | 6 hours | Week 14 | Dec 22, 2025 | Pending | -| T-4.3 | Liveness Detection Latency (Real-time performance) | AA | 4 hours | Week 14 | Dec 22, 2025 | Pending | -| **Phase 5: Security Testing** | -| T-5.1 | OWASP ZAP Vulnerability Scan (Identity Core API) | AAG | 4 hours | Week 15 | Dec 29, 2025 | Pending | -| T-5.2 | Authentication Bypass Attempts (JWT validation) | AAG | 4 hours | Week 15 | Dec 29, 2025 | Pending | -| T-5.3 | Spoofing Attack Tests (Photo, video, 3D mask) | AA | 6 hours | Week 15 | Dec 29, 2025 | Pending | -| **Phase 6: Regression & Final Validation** | -| T-6.1 | Full Regression Suite (All test levels) | Team | 8 hours | Week 16 | Jan 5, 2026 | Pending | -| T-6.2 | Bug Fixes & Re-testing | Team | 12 hours | Week 16-17 | Jan 7, 2026 | Pending | -| T-6.3 | Documentation & Test Report Generation | Team | 6 hours | Week 17 | Jan 7, 2026 | Pending | - -**Total Testing Effort:** 206 hours (approximately 26 person-days) - -**Resource Allocation:** -- AAG (Ahmet Abdullah Gültekin): 70 hours (Identity Core, Auth, Security) -- AA (Ayşenur Arıcı): 64 hours (Biometric Processor, Liveness, ML) -- AGE (Ayşe Gülsüm Eren): 40 hours (Client Apps, Mobile Integration) -- Team Collaborative: 32 hours (E2E, Regression) - -**Testing Infrastructure:** -- **CI/CD:** GitHub Actions for automated test execution on push -- **Test Environments:** - - Local: Docker Compose (development testing) - - Staging: VPS instance (integration/E2E testing) - - Performance: Dedicated test runner (8GB RAM, 4 vCPU) -- **Test Data:** - - Synthetic faces: 100 images from public datasets (LFW subset) - - Spoofing samples: 50 photo/video attacks - - User data: Faker library for realistic test accounts - -**Risk Mitigation:** -- **Time Overruns:** 20% buffer built into Phase 6 for unexpected issues -- **Blocking Dependencies:** Parallel test development where feasible -- **Resource Conflicts:** Weekly test review meetings to adjust allocation - ---- - -## 5. Software Architecture - -### 5.1 Architectural Style - -FIVUCSAS employs a **microservices architecture** with **Hexagonal Architecture (Ports & Adapters)** within each service, ensuring: - -- **Separation of Concerns**: Business logic isolated from infrastructure -- **Testability**: Domain logic testable without external dependencies -- **Flexibility**: Easy to swap implementations (e.g., database, ML models) -- **Scalability**: Services scale independently based on load - -#### 5.1.1 Hexagonal Architecture Layers - -``` -┌─────────────────────────────────────────────────────────────┐ -│ ADAPTER LAYER (Outside) │ -│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │ -│ │ REST │ │ WebSocket │ │ Message Queue │ │ -│ │ Controllers │ │ Handlers │ │ Consumers │ │ -│ └──────┬──────┘ └──────┬──────┘ └──────────┬──────────┘ │ -├─────────┼────────────────┼─────────────────────┼────────────┤ -│ │ │ │ │ -│ ▼ ▼ ▼ │ -│ ┌────────────────────────────────────────────────────────┐ │ -│ │ APPLICATION LAYER (Ports) │ │ -│ │ ┌────────────┐ ┌────────────┐ ┌──────────────────┐ │ │ -│ │ │ Use Cases │ │ DTOs │ │ Port Interfaces │ │ │ -│ │ └─────┬──────┘ └────────────┘ └────────┬─────────┘ │ │ -│ └────────┼──────────────────────────────────┼────────────┘ │ -│ │ │ │ -│ ▼ │ │ -│ ┌────────────────────────────────────────────────────────┐ │ -│ │ DOMAIN LAYER (Inside) │ │ -│ │ ┌──────────┐ ┌──────────────┐ ┌────────────────┐ │ │ -│ │ │ Entities │ │ Value Objects│ │ Domain Services│ │ │ -│ │ └──────────┘ └──────────────┘ └────────────────┘ │ │ -│ └────────────────────────────────────────────────────────┘ │ -│ ▲ │ │ -│ │ │ │ -│ ┌────────┴──────────────────────────────────┴────────────┐ │ -│ │ INFRASTRUCTURE LAYER (Adapters) │ │ -│ │ ┌─────────────┐ ┌─────────────┐ ┌────────────────┐ │ │ -│ │ │ JPA │ │ Redis │ │ External APIs │ │ │ -│ │ │ Repositories│ │ Adapter │ │ Clients │ │ │ -│ │ └─────────────┘ └─────────────┘ └────────────────┘ │ │ -└─────────────────────────────────────────────────────────────┘ -``` - -### 5.2 Component Architecture - -#### 5.2.1 High-Level System Architecture - -```mermaid -graph TB - subgraph "Client Layer" - WEB["Web Admin Dashboard
(React 18 + TypeScript)"] - MOBILE["Mobile App
(Android - KMP)"] - DESKTOP["Desktop App
(Windows/Linux/macOS - KMP)"] - KIOSK["Kiosk Mode
(Self-Service Terminal)"] - end - - subgraph "API Gateway Layer" - NGINX["NGINX
API Gateway & Load Balancer
Port 8000"] - end - - subgraph "Application Layer" - IDENTITY["Identity Core API
(Spring Boot 3.2 / Java 21)
Port 8080"] - BIOMETRIC["Biometric Processor
(FastAPI / Python 3.11)
Port 8001"] - end - - subgraph "Data Layer" - POSTGRES[("PostgreSQL 16
+ pgvector
Port 5432")] - REDIS[("Redis 7
Cache & Queue
Port 6379")] - end - - subgraph "ML Layer" - DEEPFACE["DeepFace
9 Models"] - MEDIAPIPE["MediaPipe
468 Landmarks"] - end - - WEB --> NGINX - MOBILE --> NGINX - DESKTOP --> NGINX - KIOSK --> NGINX - - NGINX --> IDENTITY - NGINX --> BIOMETRIC - - IDENTITY <--> POSTGRES - IDENTITY <--> REDIS - BIOMETRIC <--> POSTGRES - BIOMETRIC <--> REDIS - - BIOMETRIC --> DEEPFACE - BIOMETRIC --> MEDIAPIPE -``` - -#### 5.2.2 Identity Core API Components - -**Technology Stack:** -- Spring Boot 3.2.0 -- Java 21 -- Spring Data JPA -- Spring Security -- JJWT for JWT handling -- Bucket4j for rate limiting -- Flyway for migrations - -**Package Structure:** -``` -com.fivucsas.identity/ -├── adapter/ -│ ├── in/ -│ │ └── web/ # REST Controllers (8 controllers) -│ └── out/ -│ ├── persistence/ # JPA Repositories -│ └── messaging/ # Redis messaging -├── application/ -│ ├── port/ -│ │ ├── in/ # Use case interfaces (13 use cases) -│ │ └── out/ # Repository interfaces -│ ├── service/ # Use case implementations -│ └── dto/ # Data Transfer Objects -├── domain/ -│ ├── model/ # Entities (10 entities) -│ └── service/ # Domain services -└── infrastructure/ - ├── config/ # Spring configuration - ├── security/ # Security configuration - └── persistence/ # JPA entities and configs -``` - -**Key Controllers:** -| Controller | Endpoints | Description | -|------------|-----------|-------------| -| AuthController | `/api/v1/auth/*` | Login, logout, token refresh | -| UserController | `/api/v1/users/*` | User CRUD operations | -| TenantController | `/api/v1/tenants/*` | Tenant management | -| RoleController | `/api/v1/roles/*` | Role and permission management | -| BiometricController | `/api/v1/biometric/*` | Proxy to biometric processor | -| AuditController | `/api/v1/audit/*` | Audit log queries | -| HealthController | `/health/*` | Health checks | -| SettingsController | `/api/v1/settings/*` | Configuration management | - -#### 5.2.3 Biometric Processor Components - -**Technology Stack:** -- FastAPI 0.104+ -- Python 3.11+ -- DeepFace 0.0.79+ -- MediaPipe 0.10+ -- SQLAlchemy -- asyncpg for async PostgreSQL -- OpenCV - -**Package Structure:** -``` -app/ -├── api/ -│ └── routes/ # 19 route modules -│ ├── health.py -│ ├── enrollment.py -│ ├── verification.py -│ ├── search.py -│ ├── liveness.py -│ ├── quality.py -│ ├── admin.py -│ ├── analytics.py -│ ├── config.py -│ ├── detection.py -│ ├── embedding.py -│ ├── landmarks.py -│ ├── processing.py -│ ├── proctoring.py (WebSocket) -│ └── ... (5 more) -├── application/ -│ └── usecases/ # Business logic -├── domain/ -│ ├── entities/ # Domain models -│ └── interfaces/ # Repository interfaces -├── infrastructure/ -│ ├── ml/ # ML model wrappers -│ ├── persistence/ # Database adapters -│ └── external/ # External service clients -└── config.py # 552-line configuration -``` - -**API Endpoint Summary (46+ endpoints):** - -| Category | Endpoints | Description | -|----------|-----------|-------------| -| Health | 3 | Readiness, liveness, model status | -| Enrollment | 6 | Enroll, re-enroll, delete, status | -| Verification | 5 | 1:1 verify, verify with liveness | -| Search | 4 | 1:N search, batch search | -| Liveness | 8 | Challenge generation, verification, puzzle steps | -| Quality | 4 | Assess, batch assess, metrics | -| Detection | 5 | Detect faces, landmarks, attributes | -| Embedding | 4 | Generate, compare, batch generate | -| Analytics | 4 | Usage stats, accuracy metrics | -| Admin | 3 | Model management, cache control | - -**Supported Face Recognition Models:** -| Model | Dimensions | Speed | Accuracy | -|-------|------------|-------|----------| -| VGG-Face | 2,622 | Medium | Good | -| Facenet | 128 | Fast | Good | -| Facenet512 | 512 | Medium | Excellent | -| OpenFace | 128 | Fast | Moderate | -| DeepFace | 4,096 | Slow | Good | -| DeepID | 160 | Fast | Moderate | -| ArcFace | 512 | Medium | Excellent | -| Dlib | 128 | Fast | Good | -| SFace | 128 | Fast | Good | - -### 5.3 Data Architecture - -#### 5.3.1 Database Design - -**Database:** PostgreSQL 16 with pgvector extension - -**Key Design Decisions:** -1. **Multi-tenancy**: Shared database, shared schema with tenant_id column -2. **Row-Level Security**: Enforced at application layer -3. **Soft Deletes**: `deleted_at` timestamp for audit compliance -4. **Vector Storage**: pgvector with IVFFlat indexing for similarity search - -**Migration History (Flyway):** - -| Version | Description | Tables Created | -|---------|-------------|----------------| -| V1 | Tenants | `tenants` | -| V2 | Users | `users` | -| V3 | RBAC | `roles`, `permissions`, `role_permissions`, `user_roles` | -| V4 | Biometrics | `biometric_data`, `liveness_attempts`, `biometric_verification_logs` | -| V5 | Audit & Sessions | `audit_logs`, `refresh_tokens`, `active_sessions`, `password_history`, `security_events` | -| V6 | Refresh Tokens | Token enhancements | -| V7 | Performance | 18 composite indexes | -| V8 | Audit Enhancements | Additional audit fields | -| V9 | Rate Limiting | `rate_limits` table | - -**Vector Index Configuration:** -```sql --- IVFFlat index for approximate nearest neighbor search -CREATE INDEX idx_biometric_embedding_ivfflat - ON biometric_data - USING ivfflat (embedding vector_cosine_ops) - WITH (lists = 100) - WHERE deleted_at IS NULL AND is_active = TRUE; -``` - -#### 5.3.2 Caching Strategy - -**Redis Usage:** - -| Purpose | Key Pattern | TTL | -|---------|-------------|-----| -| Session Cache | `session:{user_id}:{token_hash}` | 15 min | -| Rate Limit Buckets | `rate_limit:{tenant_id}:{user_id}:{endpoint}` | 1 min | -| User Cache | `user:{tenant_id}:{user_id}` | 5 min | -| Permission Cache | `permissions:{user_id}` | 5 min | - -### 5.4 Deployment Architecture - -#### 5.4.1 Docker Compose Development Environment - -```mermaid -graph TB - subgraph "Docker Network: fivucsas-network" - subgraph "Frontend Containers" - WEB["web-app:5173"] - end - - subgraph "Backend Containers" - ICA["identity-core-api:8080"] - BP["biometric-processor:8001"] - end - - subgraph "Infrastructure Containers" - NGINX["nginx:8000"] - PG["postgres:5432"] - REDIS["redis:6379"] - end - end - - NGINX --> ICA - NGINX --> BP - ICA --> PG - ICA --> REDIS - BP --> PG - BP --> REDIS - WEB --> NGINX -``` - -**Container Specifications:** - -| Service | Base Image | Resources (Dev) | -|---------|------------|-----------------| -| identity-core-api | eclipse-temurin:21-jre | 512MB RAM | -| biometric-processor | python:3.11-slim | 1GB RAM | -| web-app | node:20-alpine | 256MB RAM | -| postgres | postgres:16-alpine | 256MB RAM | -| redis | redis:7-alpine | 128MB RAM | -| nginx | nginx:alpine | 64MB RAM | - -#### 5.4.2 Environment Configuration - -**Required Environment Variables:** -``` -# Database -POSTGRES_HOST=postgres -POSTGRES_PORT=5432 -POSTGRES_DB=fivucsas -POSTGRES_USER=fivucsas -POSTGRES_PASSWORD= - -# Redis -REDIS_HOST=redis -REDIS_PORT=6379 -REDIS_PASSWORD= - -# JWT -JWT_SECRET=<256-bit-key> -JWT_ACCESS_TOKEN_EXPIRY=900 -JWT_REFRESH_TOKEN_EXPIRY=604800 - -# Biometric -DEFAULT_FACE_MODEL=VGG-Face -SIMILARITY_THRESHOLD=0.6 -QUALITY_THRESHOLD=0.5 -``` - -### 5.5 State Machines and Behavioral Models - -This section presents state diagrams for key workflows within FIVUCSAS, illustrating state transitions and system behavior in response to events. State machines are particularly valuable for real-time systems (as recommended by CSE4197 ADD guidelines) to model complex workflows. - -#### 5.5.1 User Session Lifecycle State Machine - -This state machine models the complete user authentication session lifecycle from initial unauthenticated state through active usage to termination. - -```mermaid -stateDiagram-v2 - [*] --> Unauthenticated: System Start - - Unauthenticated --> Authenticating: POST /auth/login - - Authenticating --> Authenticated: Credentials Valid
(JWT issued) - Authenticating --> Unauthenticated: Credentials Invalid
(401 Unauthorized) - Authenticating --> Locked: Max Attempts Exceeded
(3 failed logins) - - Authenticated --> Active: API Request
(JWT valid) - Authenticated --> Expired: Token Expiry
(15 minutes) - - Active --> Active: Successful API Call
(session refreshed) - Active --> Expired: Token Expiry
(idle 15 min) - Active --> Terminated: POST /auth/logout
(explicit logout) - Active --> Revoked: Admin Revocation
(security event) - - Expired --> Refreshing: POST /auth/refresh
(refresh token provided) - Expired --> Unauthenticated: Refresh Token Expired
(7 days) - - Refreshing --> Authenticated: Refresh Token Valid
(new JWT issued) - Refreshing --> Unauthenticated: Refresh Token Invalid
(revoked/expired) - - Terminated --> [*]: Session Ended - Revoked --> [*]: Session Forcibly Ended - Locked --> Unauthenticated: Password Reset
(admin unlock) - - note right of Authenticated - JWT stored in Redis - TTL: 900 seconds - end note - - note right of Expired - Refresh token remains valid - Grace period: 7 days - end note - - note right of Locked - Requires admin intervention - Security event logged - end note -``` - -**State Descriptions:** - -| State | Description | Entry Condition | Exit Triggers | -|-------|-------------|-----------------|---------------| -| **Unauthenticated** | Initial state; no credentials provided | System start, logout, expired refresh token | Login attempt | -| **Authenticating** | Validating credentials against database | POST /auth/login received | Credentials validated OR max retries | -| **Authenticated** | Valid JWT issued, not yet used | Successful authentication or token refresh | First API request OR expiry | -| **Active** | User actively making API requests | API call with valid JWT | Token expiry, logout, revocation | -| **Expired** | Access token expired, refresh token still valid | 15-minute JWT expiry | Refresh attempt | -| **Refreshing** | Requesting new tokens with refresh token | POST /auth/refresh | Refresh token validated | -| **Terminated** | Normal session end | Explicit logout | Session cleanup complete | -| **Revoked** | Admin-forced session termination | Security event (e.g., password change) | Session cleanup complete | -| **Locked** | Account locked due to suspicious activity | 3+ failed login attempts | Admin password reset | - -#### 5.5.2 Biometric Enrollment Workflow State Machine - -This diagram models the face enrollment process, including quality checks, liveness verification, and embedding storage. - -```mermaid -stateDiagram-v2 - [*] --> Initiated: User Clicks "Enroll Face" - - Initiated --> ChallengeRequested: Request Liveness Challenge - - ChallengeRequested --> PerformingChallenge: Challenge Received
{sequence: [BLINK, SMILE, TURN]} - - PerformingChallenge --> BlinkDetection: Step 1: Detect Blink - BlinkDetection --> SmileDetection: EAR Drop Detected
(threshold < 0.25) - BlinkDetection --> ChallengeFailed: Timeout (30s)
OR No Blink Detected - - SmileDetection --> HeadTurnDetection: MAR Increase Detected
(threshold > 0.5) - SmileDetection --> ChallengeFailed: Timeout OR No Smile - - HeadTurnDetection --> ChallengeCompleted: Yaw Angle Detected
(< -15° for LEFT) - HeadTurnDetection --> ChallengeFailed: Timeout OR Insufficient Rotation - - ChallengeCompleted --> VerifyingLiveness: Submit Frames + Landmarks - - VerifyingLiveness --> LivenessVerified: Active + Passive Checks Pass
(confidence > 0.85) - VerifyingLiveness --> ChallengeFailed: Spoof Detected
(LBP/Moire patterns) - - ChallengeFailed --> Initiated: Retry Enrollment
(max 3 attempts) - ChallengeFailed --> EnrollmentAborted: Max Retries Exceeded - - LivenessVerified --> CapturingImage: Liveness Token Issued
(valid 5 min) - - CapturingImage --> DetectingFace: Image Submitted - - DetectingFace --> AnalyzingQuality: Face Detected
(confidence > 0.9) - DetectingFace --> CapturingImage: No Face Detected
(retry capture) - - AnalyzingQuality --> GeneratingEmbedding: Quality Sufficient
(score > 0.5) - AnalyzingQuality --> CapturingImage: Quality Insufficient
(blurry/dark image) - - GeneratingEmbedding --> StoringEmbedding: Embedding Generated
(512-D Facenet vector) - - StoringEmbedding --> IndexingVector: Embedding Stored
(biometric_data table) - - IndexingVector --> EnrollmentComplete: IVFFlat Index Updated - - EnrollmentComplete --> [*]: Success Message Displayed - - EnrollmentAborted --> [*]: Error Message Displayed - - note right of PerformingChallenge - Real-time MediaPipe - 468 facial landmarks - 30 FPS processing - end note - - note right of VerifyingLiveness - Two-factor verification: - 1. Active (challenge sequence) - 2. Passive (texture analysis) - end note - - note right of StoringEmbedding - Multi-tenant isolation - tenant_id foreign key - Embeddings encrypted at rest - end note -``` - -**State Descriptions:** - -| State | Description | Data Processed | Next States | -|-------|-------------|----------------|-------------| -| **Initiated** | User begins enrollment process | None | ChallengeRequested | -| **ChallengeRequested** | Requesting random liveness challenge | POST /liveness/challenge | PerformingChallenge | -| **PerformingChallenge** | User performing biometric puzzle | Video frames (30 FPS) | BlinkDetection, ChallengeFailed | -| **BlinkDetection** | Analyzing eye aspect ratio | EAR values, landmark points | SmileDetection, ChallengeFailed | -| **SmileDetection** | Analyzing mouth aspect ratio | MAR values, lip landmarks | HeadTurnDetection, ChallengeFailed | -| **HeadTurnDetection** | Analyzing head pose | Yaw/pitch/roll angles | ChallengeCompleted, ChallengeFailed | -| **VerifyingLiveness** | Server-side spoof detection | Frames, landmarks, texture | LivenessVerified, ChallengeFailed | -| **LivenessVerified** | Liveness confirmed, token issued | Liveness token (JWT, 5min TTL) | CapturingImage | -| **CapturingImage** | User capturing enrollment photo | High-resolution image | DetectingFace | -| **DetectingFace** | DeepFace face detection | Face bounding box, confidence | AnalyzingQuality, Retry | -| **AnalyzingQuality** | Brightness, sharpness, pose check | Quality score (0-1) | GeneratingEmbedding, Retry | -| **GeneratingEmbedding** | DeepFace model inference | 512-D normalized vector | StoringEmbedding | -| **StoringEmbedding** | PostgreSQL INSERT operation | user_id, tenant_id, embedding | IndexingVector | -| **IndexingVector** | pgvector IVFFlat index update | Vector index rebuild | EnrollmentComplete | -| **EnrollmentComplete** | Enrollment successful | enrollment_id | Terminal state | -| **ChallengeFailed** | Liveness check failed | Failure reason | Retry or Abort | -| **EnrollmentAborted** | Max retries exceeded | Error log | Terminal state | - -#### 5.5.3 Liveness Challenge State Machine - -This focused state machine details the biometric puzzle challenge sequence used for anti-spoofing. - -```mermaid -stateDiagram-v2 - [*] --> ChallengeGenerated: Generate Random Sequence - - ChallengeGenerated --> Step1_Blink: Sequence: [BLINK, ?, ?]
Start Timer (30s) - - Step1_Blink --> MonitoringBlink: Display "Blink Your Eyes" - - MonitoringBlink --> BlinkDetected: EAR < 0.25 detected - MonitoringBlink --> Step1_Timeout: Timer Expires (10s) - - BlinkDetected --> Step2_Smile: Step 1 Complete
Next Action - - Step2_Smile --> MonitoringSmile: Display "Smile" - - MonitoringSmile --> SmileDetected: MAR > 0.5 detected - MonitoringSmile --> Step2_Timeout: Timer Expires (10s) - - SmileDetected --> Step3_HeadTurn: Step 2 Complete
Final Action - - Step3_HeadTurn --> MonitoringHeadTurn: Display "Turn Head Left" - - MonitoringHeadTurn --> HeadTurnDetected: Yaw < -15° detected - MonitoringHeadTurn --> Step3_Timeout: Timer Expires (10s) - - HeadTurnDetected --> SequenceValidation: All Steps Complete - - SequenceValidation --> PassiveVerification: Timing Valid
(not too fast) - - PassiveVerification --> ChallengePassed: No Spoof Indicators
(LBP/Moire OK) - PassiveVerification --> ChallengeFailed: Spoof Detected - - Step1_Timeout --> ChallengeFailed: Step 1 Failed - Step2_Timeout --> ChallengeFailed: Step 2 Failed - Step3_Timeout --> ChallengeFailed: Step 3 Failed - - SequenceValidation --> ChallengeFailed: Sequence Too Fast
(< 3 seconds total) - - ChallengePassed --> [*]: Liveness Token Issued - - ChallengeFailed --> [*]: Retry Required - - note right of SequenceValidation - Validates: - - Correct action order - - Realistic timing (3-30s) - - No skipped steps - end note - - note right of PassiveVerification - Texture Analysis: - - Local Binary Patterns - - Moire pattern detection - - Color distribution - - Frequency domain analysis - end note -``` - -**State Descriptions:** - -| State | Description | Detection Method | Success Criteria | -|-------|-------------|------------------|------------------| -| **ChallengeGenerated** | Random 3-step sequence created | Server-side randomization | Sequence sent to client | -| **Step1_Blink** | Awaiting blink detection | Eye Aspect Ratio (EAR) monitoring | EAR drops below 0.25 | -| **MonitoringBlink** | Real-time landmark tracking | MediaPipe 468-point detection | Blink detected within 10s | -| **Step2_Smile** | Awaiting smile detection | Mouth Aspect Ratio (MAR) monitoring | MAR exceeds 0.5 | -| **MonitoringSmile** | Tracking mouth landmarks | Lip distance calculations | Smile detected within 10s | -| **Step3_HeadTurn** | Awaiting head rotation | Head pose estimation (yaw angle) | Yaw < -15° (left turn) | -| **MonitoringHeadTurn** | Tracking 3D head orientation | Perspective-n-Point (PnP) algorithm | Turn detected within 10s | -| **SequenceValidation** | Verifying action order and timing | Challenge log analysis | Correct order, 3-30s duration | -| **PassiveVerification** | Anti-spoofing texture analysis | LBP, Moire, color space checks | No spoof patterns detected | -| **ChallengePassed** | Liveness confirmed | All checks passed | Liveness token (JWT) issued | -| **ChallengeFailed** | Liveness verification failed | Timeout or spoof detected | Retry enrollment | - -### 5.6 Architecture Decision Records (ADRs) - -This section documents key architectural decisions made during FIVUCSAS development, providing rationale and trade-off analysis for critical technology selections. - -#### ADR-001: FastAPI for Biometric Processor vs. Spring Boot - -**Status:** Accepted -**Date:** September 2025 -**Deciders:** Team Lead, ML Engineer - -**Context:** -The biometric processor requires ML library integration (DeepFace, MediaPipe) and high-throughput image processing. Two primary frameworks were considered: -- **Spring Boot 3** (Java/Kotlin): Consistent with Identity Core API -- **FastAPI** (Python): Native ML ecosystem integration - -**Decision:** -Selected **FastAPI** (Python 3.11) for the Biometric Processor API. - -**Rationale:** - -| Criterion | Spring Boot | FastAPI | Winner | -|-----------|-------------|---------|--------| -| **ML Ecosystem** | Limited (DL4J, TensorFlow Java) | Native (DeepFace, MediaPipe, OpenCV) | **FastAPI** | -| **Development Speed** | Slower (type-safe compilation) | Faster (dynamic typing, REPL) | **FastAPI** | -| **Performance** | High (JVM optimization) | High (async/await, uvicorn) | Tie | -| **Type Safety** | Strong (compile-time) | Optional (Pydantic runtime) | Spring Boot | -| **Concurrency** | Thread pools, virtual threads | Async/await, event loop | Tie | -| **Team Expertise** | High (Java developers) | Medium (learning curve) | Spring Boot | -| **Library Maturity** | DeepFace (Python-only) | N/A | **FastAPI** | - -**Consequences:** - -*Positive:* -- ✅ Direct access to DeepFace library (no JNI bindings required) -- ✅ Faster prototyping of ML pipelines (Jupyter notebooks → API) -- ✅ Rich ecosystem for computer vision (OpenCV, PIL, scikit-image) -- ✅ Excellent async performance for I/O-bound face recognition tasks -- ✅ Automatic OpenAPI documentation generation - -*Negative:* -- ❌ Heterogeneous tech stack (Java + Python) increases deployment complexity -- ❌ No compile-time type checking (mitigated with Pydantic, mypy) -- ❌ Python GIL limits true parallelism for CPU-bound tasks (mitigated with multiprocessing) -- ❌ Team must maintain expertise in two ecosystems - -*Mitigation Strategies:* -- Use Docker to containerize both services (eliminates environment conflicts) -- Standardize on OpenAPI 3.0 for API contracts (language-agnostic) -- Implement comprehensive integration tests to catch type mismatches -- Consider GraalVM native image for Identity Core to reduce JVM overhead - -**Alternatives Considered:** -1. **PyTorch/TensorFlow Serving:** Rejected due to lack of business logic support -2. **gRPC for inter-service communication:** Deferred to v2.0 (REST-first for simplicity) -3. **Jython (Java + Python):** Rejected due to Python 2.7 limitation, poor library support - ---- - -#### ADR-002: pgvector for Embeddings vs. Specialized Vector Database - -**Status:** Accepted -**Date:** October 2025 -**Deciders:** Backend Lead, DBA - -**Context:** -Face embeddings require efficient similarity search at scale (target: 1M+ vectors). Options evaluated: -- **pgvector** (PostgreSQL extension) -- **Milvus** (purpose-built vector database) -- **Weaviate** (vector search engine) -- **Pinecone** (managed vector database) - -**Decision:** -Selected **pgvector** extension for PostgreSQL 16. - -**Rationale:** - -| Criterion | pgvector | Milvus | Weaviate | Pinecone | Winner | -|-----------|----------|--------|----------|----------|--------| -| **Setup Complexity** | Low (extension install) | Medium (separate service) | Medium (separate service) | Low (managed SaaS) | **pgvector** | -| **Operational Cost** | Included with Postgres | Self-hosted (infra cost) | Self-hosted | Pay-per-query | **pgvector** | -| **Query Performance (1M vectors)** | 50-100ms (IVFFlat) | 10-30ms (HNSW) | 20-50ms (HNSW) | 10-20ms (proprietary) | Milvus/Pinecone | -| **Transactional Consistency** | ACID guarantees | Eventual consistency | Eventual consistency | Eventual consistency | **pgvector** | -| **Multi-tenancy** | Native (row-level security) | Manual partitioning | Manual partitioning | Index-per-tenant | **pgvector** | -| **Maturity** | v0.5.1 (stable) | v2.3 (production-ready) | v1.22 (mature) | Production SaaS | Weaviate/Pinecone | -| **Open Source** | Yes (PostgreSQL license) | Yes (Apache 2.0) | Yes (BSD 3-Clause) | No (proprietary) | pgvector/Milvus/Weaviate | -| **Vendor Lock-in** | None | None | None | High | **pgvector** | - -**Consequences:** - -*Positive:* -- ✅ Single database (PostgreSQL) for relational + vector data (simplified architecture) -- ✅ ACID transactions enable atomic user+embedding creation -- ✅ Row-level security (RLS) enforces multi-tenant isolation at database level -- ✅ Existing PostgreSQL expertise (no new database to learn) -- ✅ Zero additional infrastructure cost -- ✅ Integrated backup/restore with existing database strategy - -*Negative:* -- ❌ Slower similarity search vs. specialized vector databases (50-100ms vs. 10-30ms) -- ❌ Index build time increases with dataset size (10s for 100K vectors) -- ❌ Limited to cosine, L2, inner product distances (no custom metrics) -- ❌ IVFFlat index requires manual tuning (lists, probes parameters) - -*Mitigation Strategies:* -- Implement Redis caching for frequent search queries (60-second TTL) -- Use IVFFlat index with optimized parameters (lists=100, probes=10) -- Monitor query performance; migrate to Milvus if latency exceeds NFR-1.4 (<100ms) -- Consider HNSW index in pgvector v0.6+ for faster queries - -**Performance Benchmark (100K embeddings, 512-D):** -- Sequential scan: 2,500ms -- IVFFlat (lists=100, probes=10): 75ms (97% recall) -- IVFFlat (lists=50, probes=5): 45ms (92% recall) -- Redis cache hit: 5ms - -**Migration Path:** -If query performance becomes bottleneck: -1. pgvector → Milvus: Export embeddings via `COPY` command, bulk import to Milvus -2. Dual-write pattern: Write to both pgvector and Milvus during migration -3. Feature flag to switch read queries to Milvus -4. Deprecate pgvector embedding storage - -**Alternatives Considered:** -1. **Elasticsearch with dense_vector:** Rejected due to poor recall at high dimensions (512-D) -2. **Redis with RediSearch:** Rejected due to memory cost ($500/month for 100K vectors) -3. **FAISS library (in-memory):** Rejected due to lack of persistence and multi-tenancy support - ---- - -#### ADR-003: Kotlin Multiplatform vs. React Native/Flutter - -**Status:** Accepted -**Date:** September 2025 -**Deciders:** Mobile Lead, Team - -**Context:** -Client applications required for Android, iOS, Windows, macOS, Linux. Cross-platform frameworks evaluated: -- **Kotlin Multiplatform (KMP)** with Compose Multiplatform -- **React Native** (JavaScript/TypeScript) -- **Flutter** (Dart) - -**Decision:** -Selected **Kotlin Multiplatform** with Compose Multiplatform for UI. - -**Rationale:** - -| Criterion | KMP + Compose | React Native | Flutter | Winner | -|-----------|--------------|--------------|---------|--------| -| **Code Sharing** | 95% (logic + UI) | 70% (logic only) | 90% (logic + UI) | **KMP** | -| **Desktop Support** | Native (Compose Desktop) | Poor (Electron wrapper) | Beta (unstable) | **KMP** | -| **Performance** | Native compilation | JavaScript bridge | Compiled (Dart VM) | KMP/Flutter | -| **Type Safety** | Strong (Kotlin) | Weak (TypeScript at compile) | Strong (Dart) | KMP/Flutter | -| **Native Integration** | Direct (expect/actual) | Bridges (JSI) | Plugins (FFI) | **KMP** | -| **Team Expertise** | High (Kotlin/Java) | Medium (JavaScript) | Low (Dart) | **KMP** | -| **Ecosystem Maturity** | Growing (2023+) | Mature (2015+) | Mature (2017+) | React Native/Flutter | -| **Jetpack Compose** | Native | N/A | N/A | **KMP** | - -**Consequences:** - -*Positive:* -- ✅ **95% code reuse** across Android, iOS, Desktop (business logic + UI) -- ✅ Native performance (no JavaScript bridge overhead) -- ✅ Type-safe interop with backend (shared Kotlin data classes) -- ✅ Compose UI familiar to Android developers (declarative paradigm) -- ✅ True desktop apps (not Electron wrappers) - better performance, smaller bundles - -*Negative:* -- ❌ **Smaller ecosystem** vs. React Native/Flutter (fewer libraries) -- ❌ iOS support still maturing (Compose Multiplatform iOS in alpha during development) -- ❌ Steeper learning curve for non-Kotlin developers -- ❌ Build times longer than React Native (full compilation) - -*Mitigation Strategies:* -- Focus on Android + Desktop for MVP (defer iOS to v2.0) -- Use expect/actual declarations for platform-specific code -- Leverage existing Kotlin libraries (Ktor, kotlinx.serialization, Koin) -- Monitor Compose Multiplatform iOS stability; fallback to SwiftUI if needed - -**Code Sharing Breakdown:** -- **Shared (95%):** Domain models, use cases, repositories, ViewModels, UI components -- **Platform-specific (5%):** Camera access (CameraX vs. AVFoundation), biometric auth, notifications - -**Alternatives Considered:** -1. **Native (Swift + Kotlin):** Rejected due to 0% code sharing, 3x development time -2. **.NET MAUI:** Rejected due to team unfamiliarity with C# -3. **Ionic/Capacitor:** Rejected due to poor native integration for biometric APIs - ---- - -#### ADR-004: JWT with HS512 vs. RS256 for Token Signing - -**Status:** Accepted -**Date:** October 2025 -**Deciders:** Security Lead, Backend Lead - -**Context:** -Access tokens require digital signatures to prevent tampering. Two primary JWT algorithms considered: -- **HS512:** Symmetric signing (shared secret) -- **RS256:** Asymmetric signing (public/private key pair) - -**Decision:** -Selected **HS512** (HMAC with SHA-512) for JWT signing. - -**Rationale:** - -| Criterion | HS512 | RS256 | Winner | -|-----------|-------|-------|--------| -| **Security** | High (512-bit secret) | Higher (2048-bit RSA) | RS256 | -| **Performance** | Fast (symmetric crypto) | Slower (asymmetric crypto) | **HS512** | -| **Key Distribution** | Shared secret (both services) | Public key distribution | RS256 | -| **Token Verification** | Requires secret (backend only) | Public key (any service) | RS256 | -| **Complexity** | Low | Medium (key rotation) | **HS512** | -| **Token Size** | Smaller (HMAC-SHA512: 64 bytes) | Larger (RSA-SHA256: 256 bytes) | **HS512** | - -**Consequences:** - -*Positive:* -- ✅ **5-10x faster** token signing and verification (benchmarked: HS512: 5µs, RS256: 50µs) -- ✅ Simpler key management (single secret stored in environment variable) -- ✅ Smaller token payload (reduces HTTP header size) -- ✅ Sufficient security for internal microservices (no public verification needed) - -*Negative:* -- ❌ Shared secret must be protected (leaked secret compromises all tokens) -- ❌ All services require secret access (no public verification) -- ❌ Secret rotation requires coordinated deployment - -*Mitigation Strategies:* -- Store JWT secret in environment variable (not in code) -- Rotate secret quarterly using blue-green deployment -- Implement short token expiry (15 minutes) to limit compromise window -- Use refresh tokens (separate secret) for long-lived sessions - -**Security Considerations:** -- Secret strength: 512-bit random (base64-encoded, 86 characters) -- Stored in: Docker secrets (production), .env file (development) -- Access: Identity Core API only (Biometric Processor uses opaque tokens) - -**When to Migrate to RS256:** -- Public API launch (third-party integrations need token verification) -- Multi-region deployment (different keys per region) -- Compliance requirement (e.g., FIPS 140-2 mandates asymmetric signing) - -**Alternatives Considered:** -1. **HS256 (HMAC-SHA256):** Rejected in favor of stronger HS512 (minimal performance difference) -2. **EdDSA (Ed25519):** Rejected due to limited library support in Java/Kotlin ecosystem -3. **Opaque tokens (random UUIDs):** Used for refresh tokens, but requires database lookup (slower) - ---- - -## 6. Tasks Accomplished - -### 6.1 Current State of the System - -#### 6.1.1 Implementation Progress by Component - -| Component | Status | Progress | Notes | -|-----------|--------|----------|-------| -| Identity Core API | In Progress | 68% | RBAC implementation pending | -| Biometric Processor | Complete | 100% | 46+ endpoints, all features | -| Web Admin Dashboard | Complete | 100% | Production-ready | -| Android App | In Progress | 75% | Backend integration pending | -| Desktop App | In Progress | 60% | Kiosk mode functional | -| iOS App | Shell | 20% | Basic structure only | -| Database Schema | Complete | 100% | 9 migrations, optimized indexes | -| Documentation | Complete | 100% | 259 files, 35+ diagrams | - -#### 6.1.2 Feature Completion Matrix - -| Feature | Identity Core | Biometric | Web App | Mobile | -|---------|--------------|-----------|---------|--------| -| User Registration | ✅ | - | ✅ | ✅ | -| Authentication (JWT) | ✅ | - | ✅ | ✅ | -| Token Refresh | ✅ | - | ✅ | ✅ | -| Password Reset | ✅ | - | ✅ | ⏳ | -| Face Enrollment | ⏳ | ✅ | ✅ | ⏳ | -| Face Verification | ⏳ | ✅ | ✅ | ⏳ | -| Liveness Detection | - | ✅ | - | ⏳ | -| 1:N Search | - | ✅ | ✅ | ⏳ | -| Quality Assessment | - | ✅ | ✅ | ⏳ | -| Multi-tenancy | ✅ | ✅ | ✅ | ✅ | -| RBAC | ⏳ | - | ⏳ | - | -| Audit Logging | ✅ | ✅ | ✅ | - | -| Rate Limiting | ✅ | ✅ | - | - | - -**Legend:** ✅ Complete | ⏳ In Progress | - Not Applicable - -#### 6.1.3 Biometric Processor - Detailed Status - -The Biometric Processor is the most complete component, implementing: - -**Face Detection:** -- Multiple detector backends (MTCNN, RetinaFace, SSD, OpenCV) -- Face alignment and normalization -- Multi-face detection support -- Bounding box extraction - -**Face Recognition:** -- 9 model options with configurable thresholds -- Embedding generation and comparison -- Batch processing support -- Vector storage with pgvector - -**Liveness Detection:** -- Biometric Puzzle implementation: - - Blink detection (EAR metric) - - Smile detection (MAR metric) - - Head pose tracking (Yaw, Pitch, Roll) - - Random challenge sequences -- Passive anti-spoofing: - - Texture analysis (LBP) - - Color distribution analysis - - Moire pattern detection - - Frequency domain analysis - -**Quality Assessment:** -- Brightness analysis -- Sharpness/blur detection -- Face pose estimation -- Occlusion detection -- Resolution verification - -**Proctoring System:** -- WebSocket-based real-time monitoring -- Continuous liveness verification -- Multiple face detection alerts -- Gaze tracking - -### 6.2 Task Log - -#### 6.2.1 Fall Semester (CSE4297) - Completed Tasks - -| Week | Task | Deliverable | Status | -|------|------|-------------|--------| -| 1-2 | Project Setup | Repository structure, submodules, Docker Compose | ✅ | -| 3-4 | Database Design | PostgreSQL schema, pgvector setup, Flyway migrations V1-V4 | ✅ | -| 5-6 | Identity Core Foundation | User/Tenant entities, basic CRUD, JWT auth | ✅ | -| 7-8 | Biometric Processor Core | Face detection, embedding generation | ✅ | -| 9-10 | Liveness Algorithm | Biometric Puzzle implementation, MediaPipe integration | ✅ | -| 11-12 | Web Dashboard | React setup, authentication UI, user management | ✅ | -| 13-14 | Integration & Testing | API integration, unit tests, documentation | ✅ | -| 15-16 | PSD Finalization | Project Specification Document, presentation | ✅ | - -#### 6.2.2 Spring Semester (CSE4197) - Planned Tasks - -| Week | Task | Expected Deliverable | Status | -|------|------|---------------------|--------| -| 1-2 | Identity Core RBAC | Complete role/permission implementation | ⏳ | -| 3-4 | Service Integration | Connect Identity Core to Biometric Processor | 🔜 | -| 5-6 | Mobile App Backend Integration | API clients, error handling | 🔜 | -| 7-8 | Desktop App Completion | Kiosk mode polishing, admin features | 🔜 | -| 9-10 | End-to-End Testing | Integration tests, E2E flows | 🔜 | -| 11-12 | Performance Optimization | Load testing, bottleneck resolution | 🔜 | -| 13-14 | Security Audit | Vulnerability assessment, fixes | 🔜 | -| 15-16 | Final Documentation | ADD completion, demo preparation | 🔜 | - -**Legend:** ✅ Complete | ⏳ In Progress | 🔜 Planned - -### 6.3 Gantt Chart - -This section presents the project timeline in tabular format as required by CSE4197 ADD guidelines, showing task decomposition, expected outputs, dependencies, and monthly progress tracking. - -#### 6.3.1 Fall Semester (CSE4297) Timeline - -**Duration:** September 2025 - January 2026 (5 months) - -| Task No | Task Description | Expected Output | Responsible | Sep | Oct | Nov | Dec | Jan | Status | Dependencies | -|---------|------------------|-----------------|-------------|-----|-----|-----|-----|-----|--------|--------------| -| **F-1** | Project Initiation & Setup | Git repository, Docker Compose environment, CI/CD pipeline | AAG | ████ | | | | | ✅ Complete | None | -| **F-2** | Database Schema Design | ER diagram, 9 Flyway migrations, pgvector setup | AAG | ████ | ████ | | | | ✅ Complete | F-1 | -| **F-3** | Identity Core - Base Implementation | User registration, JWT authentication, RBAC schema | AAG | | ████ | ████ | | | ✅ Complete | F-2 | -| **F-4** | Biometric Processor - Core API | Face detection, embedding generation, quality analysis | AA | | | ████ | ████ | | ✅ Complete | F-2 | -| **F-5** | Liveness Detection Algorithm | Biometric Puzzle (active + passive), MediaPipe integration | AA | | | ████ | ████ | | ✅ Complete | F-4 | -| **F-6** | Web Admin Dashboard | React 18 UI, 14+ pages, shadcn/ui components | Team | | | | ████ | ████ | ✅ Complete | F-3, F-4 | -| **F-7** | Service Integration | Identity Core ↔ Biometric Processor API contracts | AAG, AA | | | | | ████ | 🔄 70% | F-3, F-4 | -| **F-8** | Mobile App - UI Development | Android app with Compose Multiplatform, 6 screens | AGE | | | ████ | ████ | ████ | ✅ Complete | F-3 | -| **F-9** | Desktop App - Kiosk Mode | Desktop app with kiosk + admin modes | AGE | | | | ████ | ████ | ✅ Complete | F-3 | -| **F-10** | NFC Reader - Proof of Concept | Turkish eID reader, universal card detector | AA | | ████ | ████ | ████ | | ✅ Complete | None | -| **F-11** | PSD Documentation | Project Specification Document submission | Team | | | | | ████ | ✅ Complete | All | - -**Legend:** ████ = Work performed during month | ✅ = Complete | 🔄 = In Progress | ⏳ = Pending - -**Critical Path:** F-1 → F-2 → F-3 → F-4 → F-5 → F-7 → F-11 - -#### 6.3.2 Spring Semester (CSE4197) Timeline - -**Duration:** February 2026 - June 2026 (5 months) - -| Task No | Task Description | Expected Output | Responsible | Feb | Mar | Apr | May | Jun | Status | Dependencies | -|---------|------------------|-----------------|-------------|-----|-----|-----|-----|-----|--------|--------------| -| **S-1** | RBAC Implementation | Permission enforcement, role-based access control | AAG | ████ | ████ | | | | ⏳ Planned | F-3 | -| **S-2** | Service Integration - Complete | Full Identity ↔ Biometric integration, webhooks | AAG, AA | ████ | ████ | | | | ⏳ Planned | F-7 | -| **S-3** | Mobile App - Backend Connection | API client, authentication flow, biometric enrollment | AGE | | ████ | ████ | | | ⏳ Planned | S-2 | -| **S-4** | Desktop App - Production Ready | Admin dashboard, session management, NFC integration | AGE | | ████ | ████ | | | ⏳ Planned | S-2 | -| **S-5** | Vector Search Optimization | pgvector index tuning, query performance benchmarks | AA | | | ████ | | | ⏳ Planned | S-2 | -| **S-6** | End-to-End Testing | Playwright tests, API integration tests, mobile E2E | Team | | | ████ | ████ | | ⏳ Planned | S-3, S-4 | -| **S-7** | Performance Optimization | Load testing, caching strategy, API response time tuning | AAG | | | | ████ | | ⏳ Planned | S-6 | -| **S-8** | Security Audit | OWASP ZAP scan, penetration testing, vulnerability fixes | Team | | | | ████ | ████ | ⏳ Planned | S-6 | -| **S-9** | Documentation Finalization | ADD document, API documentation, deployment guide | Team | | | | ████ | ████ | 🔄 80% | All | -| **S-10** | Demo Preparation | Demo video, presentation slides, system demonstration | Team | | | | | ████ | ⏳ Planned | S-9 | -| **S-11** | ADD Submission & Defense | Final ADD submission, defense presentation | Team | | | | | ████ | ⏳ Planned | S-9, S-10 | - -**Legend:** ████ = Planned work month | ✅ = Complete | 🔄 = In Progress | ⏳ = Pending - -**Critical Path:** S-1 → S-2 → S-3/S-4 → S-6 → S-7 → S-8 → S-9 → S-11 - -#### 6.3.3 Task Dependencies Graph - -```mermaid -graph LR - F1[F-1: Setup] --> F2[F-2: Database] - F2 --> F3[F-3: Identity Core] - F2 --> F4[F-4: Biometric Core] - F3 --> F6[F-6: Web Dashboard] - F3 --> F7[F-7: Integration] - F3 --> F8[F-8: Mobile UI] - F3 --> F9[F-9: Desktop UI] - F4 --> F5[F-5: Liveness] - F4 --> F6 - F4 --> F7 - F5 --> F7 - F7 --> F11[F-11: PSD] - F8 --> F11 - F9 --> F11 - - F3 --> S1[S-1: RBAC] - F7 --> S2[S-2: Full Integration] - S1 --> S2 - S2 --> S3[S-3: Mobile Backend] - S2 --> S4[S-4: Desktop Production] - S2 --> S5[S-5: Vector Optimization] - S3 --> S6[S-6: E2E Testing] - S4 --> S6 - S6 --> S7[S-7: Performance] - S6 --> S8[S-8: Security] - S7 --> S9[S-9: Documentation] - S8 --> S9 - S9 --> S10[S-10: Demo Prep] - S10 --> S11[S-11: ADD Defense] -``` - -#### 6.3.4 Resource Allocation - -| Resource | Fall Semester Allocation (hours) | Spring Semester Allocation (hours) | Total | -|----------|----------------------------------|-------------------------------------|-------| -| **AAG (Ahmet Abdullah)** | 280 hours (Identity Core, Database, Integration) | 200 hours (RBAC, Performance, Security) | 480 hours | -| **AA (Ayşenur)** | 320 hours (Biometric Processor, Liveness, NFC) | 180 hours (Vector Optimization, Testing) | 500 hours | -| **AGE (Ayşe Gülsüm)** | 240 hours (Mobile + Desktop UI) | 220 hours (Backend Integration, Testing) | 460 hours | -| **Team Collaborative** | 120 hours (Web Dashboard, PSD) | 160 hours (E2E Testing, Documentation, Demo) | 280 hours | -| **Total Project Effort** | 960 hours | 760 hours | **1,720 hours** | - -#### 6.3.1 Milestone Summary - -| Milestone | Target Date | Status | -|-----------|-------------|--------| -| M1: Project Setup Complete | October 2025 | ✅ | -| M2: Database Schema Finalized | November 2025 | ✅ | -| M3: Core APIs Functional | December 2025 | ✅ | -| M4: Liveness Detection Working | December 2025 | ✅ | -| M5: Web Dashboard Complete | January 2026 | ✅ | -| M6: PSD Submission | January 2026 | ✅ | -| M7: RBAC Complete | February 2026 | 🔜 | -| M8: Full Service Integration | March 2026 | 🔜 | -| M9: Mobile Apps Functional | April 2026 | 🔜 | -| M10: System Testing Complete | May 2026 | 🔜 | -| M11: ADD & Demo Ready | June 2026 | 🔜 | - ---- - -## 7. References - -### 7.1 Academic References - -1. Taigman, Y., Yang, M., Ranzato, M., & Wolf, L. (2014). DeepFace: Closing the Gap to Human-Level Performance in Face Verification. *Conference on Computer Vision and Pattern Recognition (CVPR)*. - -2. Schroff, F., Kalenichenko, D., & Philbin, J. (2015). FaceNet: A Unified Embedding for Face Recognition and Clustering. *IEEE Conference on Computer Vision and Pattern Recognition (CVPR)*. - -3. Deng, J., Guo, J., Xue, N., & Zafeiriou, S. (2019). ArcFace: Additive Angular Margin Loss for Deep Face Recognition. *IEEE Conference on Computer Vision and Pattern Recognition (CVPR)*. - -4. Serengil, S.I., & Ozpinar, A. (2021). HyperExtended LightFace: A Facial Attribute Analysis Framework. *International Conference on Engineering Applications of Neural Networks*. - -5. Parkhi, O.M., Vedaldi, A., & Zisserman, A. (2015). Deep Face Recognition. *British Machine Vision Conference*. - -6. de Freitas Pereira, T., & Marcel, S. (2020). Heterogeneous Face Recognition using Domain Specific Units. *IEEE Transactions on Information Forensics and Security*. - -### 7.2 Technical Documentation - -7. Google. (2024). MediaPipe Face Landmark Detection. https://ai.google.dev/edge/mediapipe/solutions/vision/face_landmarker - -8. PostgreSQL Global Development Group. (2024). pgvector: Open-source vector similarity search for Postgres. https://github.com/pgvector/pgvector - -9. Spring Framework. (2024). Spring Boot Reference Documentation. https://docs.spring.io/spring-boot/docs/current/reference/html/ - -10. FastAPI. (2024). FastAPI Documentation. https://fastapi.tiangolo.com/ - -11. JetBrains. (2024). Kotlin Multiplatform Documentation. https://kotlinlang.org/docs/multiplatform.html - -### 7.3 Standards and Regulations - -12. European Parliament. (2016). General Data Protection Regulation (GDPR). Regulation (EU) 2016/679. - -13. Republic of Turkey. (2016). Personal Data Protection Law (KVKK). Law No. 6698. - -14. ISO/IEC 30107-1:2016. Information technology - Biometric presentation attack detection. - -15. ISO/IEC 19795-1:2021. Information technology - Biometric performance testing and reporting. - -### 7.4 Project Resources - -16. FIVUCSAS GitHub Organization. (2025). Project Repository. https://github.com/Rollingcat-Software/FIVUCSAS - -17. FIVUCSAS Documentation. (2025). Project Documentation Repository. `docs/` submodule. - -18. Marmara University. (2025). CSE4197 Engineering Project 2 - ADD Guide. `docs/CSE4197_ADD_Guide.pdf` - ---- - -## Appendix A: API Endpoint Reference - -### A.1 Identity Core API Endpoints - -``` -Authentication: -POST /api/v1/auth/login - User login -POST /api/v1/auth/logout - User logout -POST /api/v1/auth/refresh - Refresh tokens -POST /api/v1/auth/forgot-password - Request password reset -POST /api/v1/auth/reset-password - Reset password - -Users: -GET /api/v1/users - List users (paginated) -POST /api/v1/users - Create user -GET /api/v1/users/{id} - Get user by ID -PUT /api/v1/users/{id} - Update user -DELETE /api/v1/users/{id} - Delete user (soft) -GET /api/v1/users/me - Get current user profile - -Tenants: -GET /api/v1/tenants - List tenants -POST /api/v1/tenants - Create tenant -GET /api/v1/tenants/{id} - Get tenant by ID -PUT /api/v1/tenants/{id} - Update tenant -DELETE /api/v1/tenants/{id} - Delete tenant (soft) - -Roles: -GET /api/v1/roles - List roles -POST /api/v1/roles - Create role -GET /api/v1/roles/{id} - Get role by ID -PUT /api/v1/roles/{id} - Update role -DELETE /api/v1/roles/{id} - Delete role -POST /api/v1/roles/{id}/permissions - Assign permissions - -Audit: -GET /api/v1/audit/logs - Query audit logs -GET /api/v1/audit/logs/{id} - Get audit log entry -``` - -### A.2 Biometric Processor API Endpoints - -``` -Health: -GET /health - Basic health check -GET /health/ready - Readiness probe -GET /health/live - Liveness probe - -Enrollment: -POST /api/v1/enroll - Enroll face -DELETE /api/v1/enroll/{user_id} - Delete enrollment -GET /api/v1/enroll/{user_id}/status - Get enrollment status -PUT /api/v1/enroll/{user_id} - Re-enroll face - -Verification: -POST /api/v1/verify - 1:1 verification -POST /api/v1/verify/with-liveness - Verify with liveness check -POST /api/v1/search - 1:N search -POST /api/v1/compare - Compare two faces - -Liveness: -POST /api/v1/liveness/challenge - Generate challenge -POST /api/v1/liveness/verify - Verify challenge completion -POST /api/v1/liveness/passive - Passive liveness check - -Quality: -POST /api/v1/quality/assess - Assess face quality -POST /api/v1/quality/batch - Batch quality assessment - -Detection: -POST /api/v1/detect - Detect faces in image -POST /api/v1/detect/landmarks - Get facial landmarks -POST /api/v1/detect/attributes - Get face attributes - -Embedding: -POST /api/v1/embedding/generate - Generate embedding -POST /api/v1/embedding/compare - Compare embeddings - -Admin: -GET /api/v1/admin/models - List available models -POST /api/v1/admin/cache/clear - Clear cache -GET /api/v1/admin/stats - Get system statistics - -Proctoring (WebSocket): -WS /ws/proctoring/{session_id} - Real-time proctoring -``` - ---- - -## Appendix B: Configuration Reference - -### B.1 Default System Roles and Permissions - -**System Roles:** -| Role | Scope | Description | -|------|-------|-------------| -| SUPER_ADMIN | Global | Full system access | -| SYSTEM | Global | Internal system operations | -| TENANT_ADMIN | Tenant | Full tenant access | -| TENANT_MANAGER | Tenant | User and enrollment management | -| USER | Tenant | Basic user operations | -| VIEWER | Tenant | Read-only access | - -**Permissions (16 total):** -| Permission | Resource | Action | -|------------|----------|--------| -| user.read | user | read | -| user.create | user | create | -| user.update | user | update | -| user.delete | user | delete | -| biometric.enroll | biometric | enroll | -| biometric.verify | biometric | verify | -| biometric.delete | biometric | delete | -| role.read | role | read | -| role.create | role | create | -| role.update | role | update | -| role.delete | role | delete | -| tenant.read | tenant | read | -| tenant.update | tenant | update | -| tenant.delete | tenant | delete | -| analytics.view | analytics | view | -| audit.view | audit | view | - -### B.2 Subscription Plans - -| Plan | Max Users | Max Enrollments | Features | -|------|-----------|-----------------|----------| -| FREE | 100 | 500 | Basic features | -| BASIC | 500 | 2,500 | +Analytics | -| PREMIUM | 2,000 | 10,000 | +Priority support | -| ENTERPRISE | Unlimited | Unlimited | +Custom integrations | - ---- - -**Document End** - -*This ADD document was prepared in accordance with CSE4197 Engineering Project 2 guidelines.* - -*Last verified against implementation: January 2026* diff --git a/archive/2026-04-16/ADD_LANDING_WEBSITE.md b/archive/2026-04-16/ADD_LANDING_WEBSITE.md deleted file mode 100644 index 09f55bb..0000000 --- a/archive/2026-04-16/ADD_LANDING_WEBSITE.md +++ /dev/null @@ -1,1434 +0,0 @@ -# FIVUCSAS Landing Website -## Analysis & Design Document (ADD) - -**Document Version:** 1.0 -**Last Updated:** February 2026 -**Status:** Design Phase -**Domain:** `fivucsas.com` -**Hosting Provider:** Hostinger - ---- - -## Table of Contents - -1. [Executive Summary](#1-executive-summary) -2. [Project Overview](#2-project-overview) -3. [Target Audience Analysis](#3-target-audience-analysis) -4. [Brand Identity & Guidelines](#4-brand-identity--guidelines) -5. [Information Architecture](#5-information-architecture) -6. [Page-by-Page Specifications](#6-page-by-page-specifications) -7. [Visual Design System](#7-visual-design-system) -8. [Technical Architecture](#8-technical-architecture) -9. [Responsive Design Strategy](#9-responsive-design-strategy) -10. [Content Strategy](#10-content-strategy) -11. [SEO & Performance Strategy](#11-seo--performance-strategy) -12. [Security Requirements](#12-security-requirements) -13. [Hosting & Infrastructure](#13-hosting--infrastructure) -14. [Implementation Roadmap](#14-implementation-roadmap) -15. [Success Metrics & KPIs](#15-success-metrics--kpis) -16. [Appendices](#16-appendices) - ---- - -## 1. Executive Summary - -### 1.1 Purpose - -This document defines the complete analysis and design specifications for the FIVUCSAS landing website - a professional marketing and branding platform that introduces the FIVUCSAS biometric authentication system to potential users, stakeholders, and the broader market. - -### 1.2 Vision Statement - -> Create a compelling, trustworthy, and conversion-optimized digital presence that positions FIVUCSAS as the premier cloud-based biometric authentication solution, driving awareness, engagement, and adoption. - -### 1.3 Key Objectives - -| Objective | Description | Priority | -|-----------|-------------|----------| -| **Brand Awareness** | Establish FIVUCSAS brand identity and market presence | Critical | -| **Trust Building** | Demonstrate security, reliability, and compliance credentials | Critical | -| **Lead Generation** | Convert visitors into interested prospects and trial users | High | -| **Education** | Explain biometric authentication benefits and use cases | High | -| **Differentiation** | Position against competitors with unique value propositions | Medium | - -### 1.4 Project Scope - -**In Scope:** -- Landing page design and development -- Brand identity system -- Responsive web design (Desktop, Tablet, Mobile) -- Content strategy and copywriting guidelines -- SEO optimization -- Performance optimization -- Hostinger deployment configuration - -**Out of Scope:** -- User dashboard (separate application) -- API documentation portal (exists in main docs) -- Mobile application (separate project) -- Payment/billing integration (future phase) - ---- - -## 2. Project Overview - -### 2.1 Background - -FIVUCSAS (Face and Identity Verification Using Cloud-based SaaS) is a multi-tenant biometric authentication platform designed for enterprise and institutional use. The landing website serves as the primary marketing channel to introduce this technology to the market. - -### 2.2 Website Goals - -``` - ┌─────────────────────────────────────┐ - │ PRIMARY GOALS │ - └─────────────────────────────────────┘ - │ - ┌─────────────────────────┼─────────────────────────┐ - ▼ ▼ ▼ - ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ - │ INFORM │ │ ENGAGE │ │ CONVERT │ - │ │ │ │ │ │ - │ Educate on │ │ Build trust │ │ Generate │ - │ biometric │ │ and brand │ │ leads and │ - │ auth value │ │ affinity │ │ sign-ups │ - └─────────────┘ └─────────────┘ └─────────────┘ -``` - -### 2.3 Success Criteria - -| Metric | Target | Measurement | -|--------|--------|-------------| -| Page Load Time | < 3 seconds | Google PageSpeed | -| Mobile Responsiveness | 100% compatible | Cross-device testing | -| SEO Score | > 90/100 | Lighthouse audit | -| Accessibility | WCAG 2.1 AA | Automated + manual testing | -| Uptime | 99.9% | Hostinger monitoring | - ---- - -## 3. Target Audience Analysis - -### 3.1 Primary Personas - -#### Persona 1: Enterprise IT Decision Maker - -| Attribute | Details | -|-----------|---------| -| **Role** | CTO, IT Director, Security Manager | -| **Industry** | Financial Services, Healthcare, Government, Education | -| **Pain Points** | Password fatigue, security breaches, compliance requirements | -| **Goals** | Implement secure, scalable authentication | -| **Decision Factors** | Security certifications, ROI, integration ease | - -#### Persona 2: Developer/Technical Evaluator - -| Attribute | Details | -|-----------|---------| -| **Role** | Software Engineer, DevOps, Technical Architect | -| **Context** | Evaluating authentication solutions for integration | -| **Pain Points** | Complex APIs, poor documentation, vendor lock-in | -| **Goals** | Easy integration, clear documentation, good developer experience | -| **Decision Factors** | API quality, SDK availability, community support | - -#### Persona 3: Business Stakeholder - -| Attribute | Details | -|-----------|---------| -| **Role** | CEO, Product Manager, Business Analyst | -| **Context** | Looking for competitive advantage through technology | -| **Pain Points** | User friction, security incidents, compliance costs | -| **Goals** | Improve user experience, reduce risk, demonstrate innovation | -| **Decision Factors** | Business value, user experience, market perception | - -#### Persona 4: Academic/Research User - -| Attribute | Details | -|-----------|---------| -| **Role** | Researcher, University Administrator, Student | -| **Context** | Academic institutions seeking secure access management | -| **Pain Points** | Budget constraints, diverse user base, privacy concerns | -| **Goals** | Secure campus access, research data protection | -| **Decision Factors** | Academic pricing, privacy compliance, ease of deployment | - -### 3.2 User Journey Map - -``` -AWARENESS CONSIDERATION DECISION ADOPTION - │ │ │ │ - ▼ ▼ ▼ ▼ -┌────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ -│ Search │ │ Explore │ │ Compare │ │ Sign Up │ -│ Social │ ───► │ Features │ ───► │ Options │ ───► │ Trial │ -│ Referral│ │ Demo │ │ Pricing │ │ Onboard │ -└────────┘ └──────────┘ └──────────┘ └──────────┘ - │ │ │ │ - │ │ │ │ -Landing Page Feature Pages Comparison/ Dashboard -Hero Section How It Works Testimonials Access - Use Cases Contact Form -``` - ---- - -## 4. Brand Identity & Guidelines - -### 4.1 Brand Essence - -| Element | Definition | -|---------|------------| -| **Mission** | Democratize biometric authentication for secure, seamless identity verification | -| **Vision** | A world where digital identity is both secure and effortless | -| **Values** | Security, Innovation, Simplicity, Trust, Accessibility | -| **Voice** | Professional, Confident, Approachable, Technical yet Accessible | - -### 4.2 Brand Name Usage - -**Primary Name:** FIVUCSAS -**Full Name:** Face and Identity Verification Using Cloud-based SaaS -**Tagline Options:** -- "Your Face, Your Identity, Your Security" -- "Biometric Authentication, Simplified" -- "Trust Verified. Identity Confirmed." -- "Where Security Meets Simplicity" - -### 4.3 Color Palette - -#### Primary Colors - -| Color | Hex | RGB | Usage | -|-------|-----|-----|-------| -| **Deep Blue** | `#1E3A5F` | rgb(30, 58, 95) | Primary brand, headers, CTAs | -| **Electric Blue** | `#3B82F6` | rgb(59, 130, 246) | Interactive elements, links | -| **Pure White** | `#FFFFFF` | rgb(255, 255, 255) | Backgrounds, contrast | - -#### Secondary Colors - -| Color | Hex | RGB | Usage | -|-------|-----|-----|-------| -| **Success Green** | `#10B981` | rgb(16, 185, 129) | Success states, security indicators | -| **Warm Gray** | `#6B7280` | rgb(107, 114, 128) | Body text, secondary elements | -| **Light Gray** | `#F3F4F6` | rgb(243, 244, 246) | Backgrounds, cards | - -#### Accent Colors - -| Color | Hex | RGB | Usage | -|-------|-----|-----|-------| -| **Warning Amber** | `#F59E0B` | rgb(245, 158, 11) | Warnings, highlights | -| **Error Red** | `#EF4444` | rgb(239, 68, 68) | Errors, critical alerts | -| **Innovation Purple** | `#8B5CF6` | rgb(139, 92, 246) | Special features, AI elements | - -### 4.4 Typography - -#### Font Stack - -```css -/* Primary - Headings */ -font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; - -/* Secondary - Body */ -font-family: 'Source Sans Pro', 'Helvetica Neue', Arial, sans-serif; - -/* Monospace - Code/Technical */ -font-family: 'JetBrains Mono', 'Fira Code', 'Consolas', monospace; -``` - -#### Type Scale - -| Element | Size | Weight | Line Height | -|---------|------|--------|-------------| -| H1 - Hero | 48-72px | 800 | 1.1 | -| H2 - Section | 36-48px | 700 | 1.2 | -| H3 - Subsection | 24-32px | 600 | 1.3 | -| H4 - Card Title | 20-24px | 600 | 1.4 | -| Body Large | 18-20px | 400 | 1.6 | -| Body | 16px | 400 | 1.6 | -| Small/Caption | 14px | 400 | 1.5 | - -### 4.5 Logo Guidelines - -#### Logo Variations - -1. **Primary Logo** - Full horizontal lockup with icon + wordmark -2. **Icon Only** - Face/biometric symbol for favicons, app icons -3. **Wordmark Only** - Text-only version for constrained spaces -4. **Reversed** - White version for dark backgrounds - -#### Logo Clear Space - -``` -Minimum clear space = Height of the "F" in FIVUCSAS - - ┌────────────────────────────────┐ - │ [CLEAR SPACE] │ - │ ┌──────────────────────┐ │ - │ │ │ │ - │ │ FIVUCSAS │ │ - │ │ LOGO │ │ - │ │ │ │ - │ └──────────────────────┘ │ - │ [CLEAR SPACE] │ - └────────────────────────────────┘ -``` - -### 4.6 Iconography - -**Style:** Outlined with 2px stroke, rounded corners -**Library Recommendation:** Heroicons, Lucide, or Phosphor Icons -**Biometric-Specific Icons:** Custom designed for face recognition, fingerprint, iris concepts - -### 4.7 Photography & Imagery - -| Type | Guidelines | -|------|------------| -| **Hero Images** | Abstract technology patterns, face recognition visualization | -| **People** | Diverse, professional, authentic (not stock-looking) | -| **Diagrams** | Clean, flat design, brand color palette | -| **Screenshots** | High-quality, annotated product screenshots | -| **Illustrations** | Geometric, modern, gradient accents | - ---- - -## 5. Information Architecture - -### 5.1 Site Map - -``` -fivucsas.com -│ -├── / (Home/Landing) -│ ├── Hero Section -│ ├── Value Proposition -│ ├── Features Overview -│ ├── How It Works -│ ├── Use Cases Preview -│ ├── Testimonials -│ ├── CTA Section -│ └── Footer -│ -├── /features -│ ├── Face Recognition -│ ├── Multi-Factor Authentication -│ ├── Anti-Spoofing -│ ├── API & SDK -│ └── Enterprise Features -│ -├── /solutions -│ ├── By Industry -│ │ ├── Financial Services -│ │ ├── Healthcare -│ │ ├── Education -│ │ └── Government -│ └── By Use Case -│ ├── Access Control -│ ├── Identity Verification -│ └── Fraud Prevention -│ -├── /pricing -│ ├── Plans Comparison -│ ├── Enterprise Quote -│ └── Academic Program -│ -├── /developers -│ ├── Documentation Link -│ ├── API Overview -│ ├── SDKs -│ └── GitHub Links -│ -├── /about -│ ├── Our Story -│ ├── Team -│ ├── Security & Compliance -│ └── Contact -│ -├── /blog (Future) -│ └── Articles & News -│ -├── /contact -│ ├── Contact Form -│ ├── Sales Inquiry -│ └── Support -│ -└── /legal - ├── Privacy Policy - ├── Terms of Service - └── Cookie Policy -``` - -### 5.2 Navigation Structure - -#### Primary Navigation (Desktop) - -``` -┌─────────────────────────────────────────────────────────────────────┐ -│ [LOGO] Features Solutions Pricing Developers About [CTA] │ -└─────────────────────────────────────────────────────────────────────┘ -``` - -#### Mobile Navigation - -``` -┌─────────────────────────────────────────────────────────────────────┐ -│ [LOGO] [MENU ☰] │ -└─────────────────────────────────────────────────────────────────────┘ - -Expanded: -┌─────────────────────────────────────────────────────────────────────┐ -│ Features ▶ │ -│ Solutions ▶ │ -│ Pricing │ -│ Developers ▶ │ -│ About ▶ │ -│ ───────────────────────────────────────────────────────────────── │ -│ [Get Started - CTA Button] │ -└─────────────────────────────────────────────────────────────────────┘ -``` - -### 5.3 User Flows - -#### Flow 1: New Visitor to Trial Sign-up - -``` -Landing Page ──► Features ──► Pricing ──► Sign Up ──► Email Confirm ──► Dashboard - │ │ │ - └──────────────┴────────────┴──► Contact Sales (Enterprise) -``` - -#### Flow 2: Developer Evaluation - -``` -Landing Page ──► Developers ──► API Docs ──► GitHub ──► Trial API Key - │ - └──► SDK Download ──► Integration Guide -``` - ---- - -## 6. Page-by-Page Specifications - -### 6.1 Home Page (Landing) - -#### Purpose -Primary conversion page - introduce FIVUCSAS, build trust, and drive action. - -#### Sections - -##### Section 1: Hero - -``` -┌─────────────────────────────────────────────────────────────────────────┐ -│ │ -│ ┌─────────────────────────────────────────────────────────────────┐ │ -│ │ [Navigation Bar - Fixed] │ │ -│ └─────────────────────────────────────────────────────────────────┘ │ -│ │ -│ Biometric Authentication │ -│ Made Simple │ -│ │ -│ Secure your applications with advanced face recognition │ -│ and identity verification powered by cloud-based AI. │ -│ │ -│ [Get Started Free] [Watch Demo] │ -│ │ -│ ┌──────────────────────────────────┐ │ -│ │ │ │ -│ │ [Hero Visual/Animation] │ │ -│ │ Face Recognition Demo │ │ -│ │ │ │ -│ └──────────────────────────────────┘ │ -│ │ -│ Trusted by: [Logo] [Logo] [Logo] [Logo] [Logo] │ -│ │ -└─────────────────────────────────────────────────────────────────────────┘ -``` - -**Content Requirements:** -- Headline: 6-10 words, benefit-focused -- Subheadline: 15-25 words, expand on value -- Primary CTA: "Get Started Free" / "Start Free Trial" -- Secondary CTA: "Watch Demo" / "See How It Works" -- Trust Indicators: Partner/client logos or security badges - -##### Section 2: Value Proposition - -``` -┌─────────────────────────────────────────────────────────────────────────┐ -│ │ -│ Why Choose FIVUCSAS? │ -│ │ -│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ -│ │ [Icon] │ │ [Icon] │ │ [Icon] │ │ -│ │ │ │ │ │ │ │ -│ │ 99.9% │ │ < 500ms │ │ Zero │ │ -│ │ Accuracy │ │ Response │ │ Friction │ │ -│ │ │ │ │ │ │ │ -│ │ Industry- │ │ Real-time │ │ Seamless │ │ -│ │ leading │ │ verify in │ │ user exp │ │ -│ │ precision │ │ millisecs │ │ no pwd │ │ -│ └─────────────┘ └─────────────┘ └─────────────┘ │ -│ │ -└─────────────────────────────────────────────────────────────────────────┘ -``` - -##### Section 3: Features Overview - -``` -┌─────────────────────────────────────────────────────────────────────────┐ -│ │ -│ Powerful Features │ -│ │ -│ ┌───────────────────────────────────────────────────────────────┐ │ -│ │ │ │ -│ │ [Feature Image/Animation] Face Recognition │ │ -│ │ │ │ -│ │ Advanced AI-powered face │ │ -│ │ detection and matching │ │ -│ │ with anti-spoofing │ │ -│ │ protection. │ │ -│ │ │ │ -│ │ [Learn More →] │ │ -│ └───────────────────────────────────────────────────────────────┘ │ -│ │ -│ ┌───────────────────────────────────────────────────────────────┐ │ -│ │ │ │ -│ │ Multi-Factor Auth [Feature Image/Animation] │ │ -│ │ │ │ -│ │ Combine biometrics with │ │ -│ │ traditional factors for │ │ -│ │ enhanced security. │ │ -│ │ │ │ -│ │ [Learn More →] │ │ -│ └───────────────────────────────────────────────────────────────┘ │ -│ │ -│ (Additional features in alternating layout...) │ -│ │ -└─────────────────────────────────────────────────────────────────────────┘ -``` - -##### Section 4: How It Works - -``` -┌─────────────────────────────────────────────────────────────────────────┐ -│ │ -│ How It Works │ -│ Get started in 3 simple steps │ -│ │ -│ ┌─────┐ ┌─────┐ ┌─────┐ │ -│ │ 1 │─────────────►│ 2 │─────────────►│ 3 │ │ -│ └─────┘ └─────┘ └─────┘ │ -│ │ -│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ -│ │ Integrate │ │ Enroll │ │ Verify │ │ -│ │ │ │ │ │ │ │ -│ │ Add our SDK │ │ Users scan │ │ Instant │ │ -│ │ or API to │ │ their face │ │ secure │ │ -│ │ your app │ │ once │ │ auth │ │ -│ └─────────────┘ └─────────────┘ └─────────────┘ │ -│ │ -│ [Start Integration →] │ -│ │ -└─────────────────────────────────────────────────────────────────────────┘ -``` - -##### Section 5: Use Cases - -``` -┌─────────────────────────────────────────────────────────────────────────┐ -│ │ -│ Built for Every Industry │ -│ │ -│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ -│ │ [Icon] │ │ [Icon] │ │ [Icon] │ │ [Icon] │ │ -│ │ │ │ │ │ │ │ │ │ -│ │ Finance │ │ Health │ │ Edu │ │ Govt │ │ -│ │ │ │ │ │ │ │ │ │ -│ │ Secure │ │ HIPAA │ │ Campus │ │ Citizen │ │ -│ │ banking │ │ compliant│ │ access │ │ services │ │ -│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ -│ │ -│ [Explore Solutions →] │ -│ │ -└─────────────────────────────────────────────────────────────────────────┘ -``` - -##### Section 6: Social Proof / Testimonials - -``` -┌─────────────────────────────────────────────────────────────────────────┐ -│ │ -│ Trusted by Security-Conscious Organizations │ -│ │ -│ ┌─────────────────────────────────────────────────────────────────┐ │ -│ │ │ │ -│ │ "FIVUCSAS transformed our authentication flow. Our users │ │ -│ │ love the passwordless experience, and our security team │ │ -│ │ finally sleeps at night." │ │ -│ │ │ │ -│ │ [Photo] Jane Smith │ │ -│ │ CTO, TechCorp Inc. │ │ -│ │ │ │ -│ └─────────────────────────────────────────────────────────────────┘ │ -│ │ -│ ┌──────────────────────────────────────────────────────────────────┐ │ -│ │ │ │ -│ │ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │ │ -│ │ │Stats│ │Stats│ │Stats│ │Stats│ │Stats│ │ │ -│ │ │ │ │ │ │ │ │ │ │ │ │ │ -│ │ │ 10M+│ │99.9%│ │ 500+│ │ 50+ │ │ 24/7│ │ │ -│ │ │Users│ │ Up │ │Orgs │ │Ctry │ │Supp │ │ │ -│ │ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ │ │ -│ │ │ │ -│ └──────────────────────────────────────────────────────────────────┘ │ -│ │ -└─────────────────────────────────────────────────────────────────────────┘ -``` - -##### Section 7: CTA Section - -``` -┌─────────────────────────────────────────────────────────────────────────┐ -│ │ -│ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ │ -│ ░ ░ │ -│ ░ Ready to Secure Your Applications? ░ │ -│ ░ ░ │ -│ ░ Start your free trial today. No credit card required. ░ │ -│ ░ ░ │ -│ ░ [Start Free Trial] [Contact Sales] ░ │ -│ ░ ░ │ -│ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ │ -│ │ -└─────────────────────────────────────────────────────────────────────────┘ -``` - -##### Section 8: Footer - -``` -┌─────────────────────────────────────────────────────────────────────────┐ -│ │ -│ [FIVUCSAS LOGO] │ -│ │ -│ Product Solutions Resources Company │ -│ ──────── ───────── ───────── ─────── │ -│ Features Finance Documentation About Us │ -│ Pricing Healthcare API Reference Careers │ -│ Security Education Blog Contact │ -│ Enterprise Government Status Page Press │ -│ │ -│ ───────────────────────────────────────────────────────────────── │ -│ │ -│ [Twitter] [LinkedIn] [GitHub] │ -│ │ -│ © 2026 Rollingcat Software. All rights reserved. │ -│ Privacy Policy | Terms of Service | Cookie Policy │ -│ │ -└─────────────────────────────────────────────────────────────────────────┘ -``` - -### 6.2 Features Page - -**Purpose:** Deep dive into platform capabilities - -**Key Sections:** -1. Features Hero with category navigation -2. Face Recognition Technology (expandable) -3. Anti-Spoofing & Liveness Detection -4. Multi-Factor Authentication Options -5. API & SDK Capabilities -6. Enterprise Features (Admin, Analytics, Audit) -7. Integration Ecosystem -8. Feature Comparison Table -9. CTA to Try/Demo - -### 6.3 Solutions Page - -**Purpose:** Industry-specific value propositions - -**Key Sections:** -1. Industry Selector (Visual Cards) -2. Industry-Specific Challenges -3. FIVUCSAS Solutions for That Industry -4. Case Study / Success Story -5. Compliance & Certifications Relevant -6. Industry CTA - -### 6.4 Pricing Page - -**Purpose:** Clear pricing tiers and conversion - -**Key Sections:** -1. Pricing Hero -2. Plan Comparison Table -3. Feature Matrix -4. FAQ -5. Enterprise Contact Form -6. Academic/Nonprofit Program -7. Money-back Guarantee / Trial CTA - -### 6.5 Developers Page - -**Purpose:** Technical audience conversion - -**Key Sections:** -1. Developer Hero with Code Sample -2. Quick Start Guide Preview -3. SDK Downloads (iOS, Android, Web, Python, Java) -4. API Endpoints Overview -5. Documentation Links -6. GitHub Repository Links -7. Developer Community / Discord -8. API Key CTA - -### 6.6 About Page - -**Purpose:** Build trust and human connection - -**Key Sections:** -1. Company Story -2. Mission & Vision -3. Team Section -4. Security & Compliance Certifications -5. Partners & Integrations -6. Contact Information - -### 6.7 Contact Page - -**Purpose:** Lead capture and support - -**Key Sections:** -1. Contact Form (Name, Email, Company, Message, Type) -2. Sales Inquiry Option -3. Support Channels -4. Office Location / Map -5. Social Links - ---- - -## 7. Visual Design System - -### 7.1 Design Principles - -| Principle | Application | -|-----------|-------------| -| **Clarity** | Clean layouts, ample whitespace, clear hierarchy | -| **Trust** | Professional aesthetics, security-focused imagery | -| **Modernity** | Contemporary design trends, subtle animations | -| **Accessibility** | WCAG 2.1 AA compliance, readable contrast | -| **Consistency** | Unified component library, predictable patterns | - -### 7.2 Component Library - -#### Buttons - -``` -Primary Button: -┌─────────────────────────────┐ -│ Get Started Free │ Background: #1E3A5F -│ │ Text: #FFFFFF -└─────────────────────────────┘ Hover: Lighten 10% - -Secondary Button: -┌─────────────────────────────┐ -│ Learn More → │ Background: Transparent -│ │ Border: #1E3A5F -└─────────────────────────────┘ Text: #1E3A5F - -Ghost Button: -┌─────────────────────────────┐ -│ Watch Demo │ Background: Transparent -│ │ Text: #3B82F6 -└─────────────────────────────┘ Underline on hover -``` - -#### Cards - -``` -Feature Card: -┌─────────────────────────────────┐ -│ [Icon] │ -│ │ -│ Feature Title │ -│ │ -│ Brief description of the │ -│ feature and its benefits. │ -│ │ -│ [Learn More →] │ -└─────────────────────────────────┘ -Border-radius: 12px -Shadow: 0 4px 6px rgba(0,0,0,0.1) -Hover: Lift + shadow increase -``` - -#### Form Elements - -``` -Input Field: -┌─────────────────────────────────┐ -│ Label │ -│ ┌─────────────────────────────┐ │ -│ │ Placeholder text... │ │ -│ └─────────────────────────────┘ │ -│ Helper text or error message │ -└─────────────────────────────────┘ -Border: 1px solid #D1D5DB -Focus: Border #3B82F6 -Error: Border #EF4444 -``` - -### 7.3 Animation Guidelines - -| Element | Animation | Duration | Easing | -|---------|-----------|----------|--------| -| Page Load | Fade in + slide up | 400ms | ease-out | -| Hover States | Scale + shadow | 200ms | ease-in-out | -| Modal Open | Fade + scale | 300ms | ease-out | -| Scroll Reveal | Fade in + slide | 600ms | ease-out | -| Loading | Pulse / Skeleton | Continuous | linear | - -### 7.4 Spacing System - -``` -Base unit: 4px - -Spacing scale: -- xs: 4px (0.25rem) -- sm: 8px (0.5rem) -- md: 16px (1rem) -- lg: 24px (1.5rem) -- xl: 32px (2rem) -- 2xl: 48px (3rem) -- 3xl: 64px (4rem) -- 4xl: 96px (6rem) - -Section spacing: 80-120px vertical padding -``` - -### 7.5 Grid System - -``` -Desktop: 12-column grid, 1200px max-width -Tablet: 8-column grid, 768px breakpoint -Mobile: 4-column grid, 375px minimum - -Gutters: 24px (desktop), 16px (mobile) -Margins: 48px (desktop), 16px (mobile) -``` - ---- - -## 8. Technical Architecture - -### 8.1 Technology Stack Recommendations - -#### Option A: Static Site Generator (Recommended for Initial Launch) - -| Component | Technology | Rationale | -|-----------|------------|-----------| -| **Framework** | Next.js (Static Export) or Astro | Fast, SEO-friendly, modern DX | -| **Styling** | Tailwind CSS | Rapid development, consistent design | -| **Animations** | Framer Motion | Smooth, performant animations | -| **Forms** | Formspree or Netlify Forms | No backend needed | -| **CMS** | Contentful or Sanity (optional) | Content updates without code | -| **Deployment** | Hostinger Static Hosting | Cost-effective, reliable | - -#### Option B: Full React Application - -| Component | Technology | Rationale | -|-----------|------------|-----------| -| **Framework** | React + Vite | If dynamic features needed | -| **Routing** | React Router | SPA navigation | -| **State** | React Context | Minimal state needs | -| **API** | REST calls to main backend | If dashboard integration needed | - -### 8.2 File Structure - -``` -fivucsas-landing/ -├── public/ -│ ├── images/ -│ │ ├── logo/ -│ │ ├── heroes/ -│ │ ├── features/ -│ │ └── team/ -│ ├── fonts/ -│ └── favicon.ico -├── src/ -│ ├── components/ -│ │ ├── common/ -│ │ │ ├── Button/ -│ │ │ ├── Card/ -│ │ │ ├── Input/ -│ │ │ └── ... -│ │ ├── layout/ -│ │ │ ├── Header/ -│ │ │ ├── Footer/ -│ │ │ └── Navigation/ -│ │ └── sections/ -│ │ ├── Hero/ -│ │ ├── Features/ -│ │ ├── HowItWorks/ -│ │ └── ... -│ ├── pages/ -│ │ ├── index.tsx -│ │ ├── features.tsx -│ │ ├── solutions/ -│ │ ├── pricing.tsx -│ │ ├── developers.tsx -│ │ ├── about.tsx -│ │ └── contact.tsx -│ ├── styles/ -│ │ ├── globals.css -│ │ └── variables.css -│ ├── lib/ -│ │ └── utils.ts -│ └── types/ -│ └── index.ts -├── package.json -├── tailwind.config.js -├── next.config.js -└── README.md -``` - -### 8.3 Build & Deployment Pipeline - -``` -┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ -│ Code │ │ Build │ │ Test │ │ Deploy │ -│ Push │───►│ (npm │───►│ (Light │───►│ (Host- │ -│ (Git) │ │ build) │ │ house) │ │ inger) │ -└──────────┘ └──────────┘ └──────────┘ └──────────┘ - │ │ - │ GitHub Actions CI/CD │ - └──────────────────────────────────────────────┘ -``` - -### 8.4 Third-Party Integrations - -| Service | Purpose | Priority | -|---------|---------|----------| -| Google Analytics 4 | Traffic analytics | Essential | -| Google Tag Manager | Tag management | Essential | -| Hotjar/Clarity | Heatmaps, recordings | High | -| Intercom/Crisp | Live chat | Medium | -| Mailchimp/ConvertKit | Email capture | High | -| Calendly | Demo scheduling | Medium | -| reCAPTCHA v3 | Form spam protection | Essential | - ---- - -## 9. Responsive Design Strategy - -### 9.1 Breakpoints - -| Breakpoint | Width | Target Devices | -|------------|-------|----------------| -| Mobile S | 320px | Small phones | -| Mobile M | 375px | iPhone, standard phones | -| Mobile L | 425px | Large phones | -| Tablet | 768px | iPad, tablets | -| Laptop | 1024px | Small laptops | -| Desktop | 1200px | Standard desktops | -| Large Desktop | 1440px+ | Large monitors | - -### 9.2 Responsive Behavior - -#### Navigation - -``` -Desktop (>1024px): -┌─────────────────────────────────────────────────────────────────────┐ -│ [LOGO] Features Solutions Pricing Developers About [CTA] │ -└─────────────────────────────────────────────────────────────────────┘ - -Tablet (768-1024px): -┌─────────────────────────────────────────────────────────────────────┐ -│ [LOGO] Features Solutions Pricing [CTA] │ -└─────────────────────────────────────────────────────────────────────┘ -(Secondary items in "More" dropdown) - -Mobile (<768px): -┌─────────────────────────────────────────────────────────────────────┐ -│ [LOGO] [MENU ☰] │ -└─────────────────────────────────────────────────────────────────────┘ -(Full-screen slide-out menu) -``` - -#### Content Grids - -``` -Desktop: 3-4 columns -┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ -│ │ │ │ │ │ │ │ -└─────┘ └─────┘ └─────┘ └─────┘ - -Tablet: 2 columns -┌─────────┐ ┌─────────┐ -│ │ │ │ -└─────────┘ └─────────┘ -┌─────────┐ ┌─────────┐ -│ │ │ │ -└─────────┘ └─────────┘ - -Mobile: 1 column (stacked) -┌─────────────────────┐ -│ │ -└─────────────────────┘ -┌─────────────────────┐ -│ │ -└─────────────────────┘ -``` - -### 9.3 Touch Considerations - -| Element | Minimum Size | Spacing | -|---------|--------------|---------| -| Buttons | 44x44px | 8px between | -| Links | 44px touch target | 8px between | -| Form inputs | 44px height | 16px between | -| Navigation items | 48px height | 4px between | - ---- - -## 10. Content Strategy - -### 10.1 Messaging Framework - -#### Primary Message -> "FIVUCSAS provides enterprise-grade biometric authentication that's secure, fast, and effortless to integrate." - -#### Supporting Messages - -| Pillar | Message | -|--------|---------| -| **Security** | "Bank-grade security with anti-spoofing and liveness detection" | -| **Simplicity** | "Integrate in minutes with our SDKs and comprehensive APIs" | -| **Speed** | "Sub-500ms verification for seamless user experiences" | -| **Scalability** | "From startup to enterprise, scale with confidence" | - -### 10.2 Tone of Voice - -| Attribute | Do | Don't | -|-----------|----|----| -| **Professional** | "Our platform enables..." | "We're totally awesome at..." | -| **Confident** | "Industry-leading accuracy" | "We think we're pretty good" | -| **Clear** | "Verify users in 500ms" | "Leveraging synergies..." | -| **Human** | "Your users will love it" | "End-users experience satisfaction" | - -### 10.3 SEO Keywords - -#### Primary Keywords -- Biometric authentication -- Face recognition API -- Identity verification software -- Passwordless authentication -- Facial recognition SDK - -#### Long-tail Keywords -- Cloud-based biometric authentication platform -- Enterprise face recognition solution -- HIPAA compliant biometric verification -- Face recognition API for mobile apps -- Multi-factor authentication with biometrics - -### 10.4 Content Types - -| Type | Purpose | Frequency | -|------|---------|-----------| -| Landing Copy | Convert visitors | Static | -| Feature Descriptions | Explain capabilities | Static | -| Use Case Stories | Industry relevance | Quarterly updates | -| Blog Posts (Future) | SEO, thought leadership | Weekly | -| Case Studies | Social proof | Monthly | -| Documentation | Developer support | Continuous | - ---- - -## 11. SEO & Performance Strategy - -### 11.1 Technical SEO Requirements - -#### Meta Tags Template - -```html - -FIVUCSAS - Biometric Authentication Made Simple - - - - - - - - - - - - - - - - -``` - -#### Structured Data - -```json -{ - "@context": "https://schema.org", - "@type": "SoftwareApplication", - "name": "FIVUCSAS", - "applicationCategory": "SecurityApplication", - "operatingSystem": "Web, iOS, Android", - "offers": { - "@type": "Offer", - "price": "0", - "priceCurrency": "USD" - }, - "aggregateRating": { - "@type": "AggregateRating", - "ratingValue": "4.8", - "ratingCount": "150" - } -} -``` - -### 11.2 Performance Targets - -| Metric | Target | Tool | -|--------|--------|------| -| First Contentful Paint | < 1.5s | Lighthouse | -| Largest Contentful Paint | < 2.5s | Lighthouse | -| Time to Interactive | < 3.5s | Lighthouse | -| Cumulative Layout Shift | < 0.1 | Lighthouse | -| First Input Delay | < 100ms | Lighthouse | -| Overall Performance Score | > 90 | Lighthouse | - -### 11.3 Performance Optimization Techniques - -1. **Image Optimization** - - WebP format with fallbacks - - Lazy loading for below-fold images - - Responsive images with srcset - - CDN delivery - -2. **Code Optimization** - - Minification of CSS/JS - - Tree shaking - - Code splitting by route - - Critical CSS inlining - -3. **Caching Strategy** - - Static assets: 1 year cache - - HTML: No cache or short cache - - API responses: Appropriate TTL - -4. **Network Optimization** - - Preconnect to critical origins - - DNS prefetch - - HTTP/2 or HTTP/3 - - Gzip/Brotli compression - ---- - -## 12. Security Requirements - -### 12.1 Web Security - -| Requirement | Implementation | -|-------------|----------------| -| HTTPS | Enforce via Hostinger SSL | -| CSP | Content Security Policy headers | -| XSS Protection | Input sanitization, CSP | -| CSRF | Token-based form protection | -| Clickjacking | X-Frame-Options header | - -### 12.2 Security Headers - -``` -Strict-Transport-Security: max-age=31536000; includeSubDomains -X-Content-Type-Options: nosniff -X-Frame-Options: DENY -X-XSS-Protection: 1; mode=block -Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline' https://www.googletagmanager.com; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' https://fonts.gstatic.com; -Referrer-Policy: strict-origin-when-cross-origin -Permissions-Policy: camera=(), microphone=(), geolocation=() -``` - -### 12.3 Privacy Compliance - -| Regulation | Requirements | -|------------|--------------| -| GDPR | Cookie consent, privacy policy, data rights | -| CCPA | Privacy notice, opt-out mechanism | -| General | Clear data collection disclosure | - ---- - -## 13. Hosting & Infrastructure - -### 13.1 Hostinger Configuration - -#### Hosting Plan Recommendation - -| Feature | Requirement | Hostinger Plan | -|---------|-------------|----------------| -| Storage | ~500MB initially | Business Web Hosting | -| Bandwidth | 10,000+ visits/month | Unlimited | -| SSL | Required | Free SSL included | -| CDN | Recommended | Cloudflare integration | -| Email | Optional | Included | - -### 13.2 Domain Configuration - -``` -Domain: fivucsas.com - -DNS Records: -┌──────────┬──────────┬────────────────────────────┐ -│ Type │ Name │ Value │ -├──────────┼──────────┼────────────────────────────┤ -│ A │ @ │ [Hostinger IP] │ -│ CNAME │ www │ fivucsas.com │ -│ TXT │ @ │ [SPF Record] │ -│ TXT │ _dmarc │ [DMARC Policy] │ -└──────────┴──────────┴────────────────────────────┘ -``` - -### 13.3 Deployment Process - -``` -1. Build locally: npm run build -2. Export static: npm run export (if Next.js) -3. Upload to Hostinger: - - Via File Manager - - Via FTP/SFTP - - Via Git deployment (if supported) -4. Configure redirects in .htaccess -5. Verify SSL certificate -6. Test all pages -``` - -### 13.4 Hostinger .htaccess Configuration - -```apache -# Enable HTTPS redirect -RewriteEngine On -RewriteCond %{HTTPS} off -RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301] - -# Remove trailing slashes -RewriteCond %{REQUEST_FILENAME} !-d -RewriteRule ^(.*)/$ /$1 [L,R=301] - -# SPA routing (if applicable) -RewriteCond %{REQUEST_FILENAME} !-f -RewriteCond %{REQUEST_FILENAME} !-d -RewriteRule ^ index.html [L] - -# Caching - - ExpiresActive On - ExpiresByType image/jpg "access plus 1 year" - ExpiresByType image/jpeg "access plus 1 year" - ExpiresByType image/gif "access plus 1 year" - ExpiresByType image/png "access plus 1 year" - ExpiresByType image/webp "access plus 1 year" - ExpiresByType text/css "access plus 1 month" - ExpiresByType application/javascript "access plus 1 month" - - -# Compression - - AddOutputFilterByType DEFLATE text/html text/plain text/css application/javascript application/json - - -# Security headers - - Header set X-Content-Type-Options "nosniff" - Header set X-Frame-Options "DENY" - Header set X-XSS-Protection "1; mode=block" - Header set Referrer-Policy "strict-origin-when-cross-origin" - -``` - ---- - -## 14. Implementation Roadmap - -### 14.1 Phase Overview - -``` -Phase 1: Foundation (Week 1-2) -├── Design system setup -├── Component library -├── Basic page templates -└── Development environment - -Phase 2: Core Pages (Week 3-4) -├── Home/Landing page -├── Features page -├── Pricing page -└── Contact page - -Phase 3: Secondary Pages (Week 5-6) -├── Solutions pages -├── Developers page -├── About page -└── Legal pages - -Phase 4: Polish & Launch (Week 7-8) -├── Animations & interactions -├── SEO optimization -├── Performance tuning -├── Testing & QA -└── Deployment -``` - -### 14.2 Detailed Timeline - -| Phase | Tasks | Deliverables | -|-------|-------|--------------| -| **Week 1** | Project setup, design tokens, Tailwind config | Dev environment ready | -| **Week 2** | Component library (buttons, cards, forms, nav) | Storybook/component docs | -| **Week 3** | Home page development | Functional landing page | -| **Week 4** | Features + Pricing pages | 3 core pages complete | -| **Week 5** | Solutions + Developers pages | Industry pages | -| **Week 6** | About + Contact + Legal | All pages complete | -| **Week 7** | Animations, integrations, SEO | Enhanced UX | -| **Week 8** | Testing, optimization, deployment | Live website | - -### 14.3 Milestones - -| Milestone | Date | Criteria | -|-----------|------|----------| -| M1: Dev Ready | End Week 1 | Environment, design system | -| M2: Alpha | End Week 4 | Core pages functional | -| M3: Beta | End Week 6 | All pages complete | -| M4: Launch Ready | End Week 7 | QA complete | -| M5: Go Live | End Week 8 | Production deployment | - ---- - -## 15. Success Metrics & KPIs - -### 15.1 Launch Metrics - -| Metric | Target | Measurement | -|--------|--------|-------------| -| Lighthouse Performance | > 90 | Automated test | -| Lighthouse Accessibility | > 90 | Automated test | -| Lighthouse SEO | > 90 | Automated test | -| Mobile Usability | 100% | Google Search Console | -| Cross-browser Compatibility | 100% | Manual testing | - -### 15.2 Business Metrics (Post-Launch) - -| Metric | Target (Month 1) | Target (Month 3) | -|--------|------------------|------------------| -| Unique Visitors | 1,000 | 5,000 | -| Page Views | 3,000 | 15,000 | -| Avg Session Duration | > 2 min | > 2.5 min | -| Bounce Rate | < 60% | < 50% | -| Contact Form Submissions | 20 | 100 | -| Trial Sign-ups | 10 | 50 | - -### 15.3 Tracking Implementation - -```javascript -// Google Analytics 4 Events -gtag('event', 'cta_click', { - 'event_category': 'engagement', - 'event_label': 'hero_get_started' -}); - -gtag('event', 'form_submission', { - 'event_category': 'conversion', - 'event_label': 'contact_form' -}); - -gtag('event', 'demo_request', { - 'event_category': 'conversion', - 'event_label': 'demo_scheduled' -}); -``` - ---- - -## 16. Appendices - -### Appendix A: Competitor Analysis Summary - -| Competitor | Strengths | Weaknesses | FIVUCSAS Advantage | -|------------|-----------|------------|-------------------| -| Auth0 | Brand recognition, docs | Complex pricing | Simpler, biometric-focused | -| FacePhi | Biometric expertise | Enterprise-only | More accessible tiers | -| Onfido | KYC focus | Limited auth features | Full authentication suite | -| BioID | Privacy focus | Limited SDK | Better developer experience | - -### Appendix B: Accessibility Checklist - -- [ ] Color contrast ratio > 4.5:1 -- [ ] All images have alt text -- [ ] Form inputs have labels -- [ ] Keyboard navigation works -- [ ] Focus indicators visible -- [ ] Skip navigation link -- [ ] ARIA landmarks used -- [ ] Heading hierarchy correct -- [ ] Link text descriptive -- [ ] Video has captions - -### Appendix C: Browser Support Matrix - -| Browser | Version | Support Level | -|---------|---------|---------------| -| Chrome | Last 2 versions | Full | -| Firefox | Last 2 versions | Full | -| Safari | Last 2 versions | Full | -| Edge | Last 2 versions | Full | -| iOS Safari | Last 2 versions | Full | -| Chrome Android | Last 2 versions | Full | - -### Appendix D: Image Assets Required - -| Asset | Dimensions | Format | Usage | -|-------|------------|--------|-------| -| Logo Primary | 200x50px | SVG | Header | -| Logo Icon | 32x32px, 64x64px | SVG/PNG | Favicon, app icon | -| Hero Image | 1920x1080px | WebP/PNG | Landing hero | -| Feature Icons | 64x64px | SVG | Feature cards | -| Team Photos | 400x400px | WebP | About page | -| OG Image | 1200x630px | PNG | Social sharing | -| Twitter Image | 1200x600px | PNG | Twitter cards | - -### Appendix E: Copy Requirements - -| Page | Word Count | Key Messages | -|------|------------|--------------| -| Home | ~800 words | Value prop, features preview, CTA | -| Features | ~1200 words | Detailed feature descriptions | -| Solutions | ~400 words/industry | Industry-specific benefits | -| Pricing | ~500 words | Plan details, FAQ | -| Developers | ~600 words | Quick start, SDK info | -| About | ~600 words | Company story, team | -| Contact | ~200 words | Form labels, info | - ---- - -## Document History - -| Version | Date | Author | Changes | -|---------|------|--------|---------| -| 1.0 | February 2026 | Claude | Initial document creation | - ---- - -## Approval - -| Role | Name | Signature | Date | -|------|------|-----------|------| -| Project Lead | | | | -| Design Lead | | | | -| Technical Lead | | | | - ---- - -*This document serves as the authoritative reference for the FIVUCSAS landing website design and implementation. All team members should refer to this document for design decisions and technical specifications.* diff --git a/archive/2026-04-16/ANALYTICS_PLAN.md b/archive/2026-04-16/ANALYTICS_PLAN.md deleted file mode 100644 index b4d7e4f..0000000 --- a/archive/2026-04-16/ANALYTICS_PLAN.md +++ /dev/null @@ -1,86 +0,0 @@ -# Analytics & Tracking Plan — FIVUCSAS - -**Created**: 2026-04-10 - ---- - -## What to Set Up (Priority Order) - -### 1. Google Search Console (Free — Do This First, 10 min) - -- **Site**: fivucsas.com -- **Why**: Understand how Google indexes the site, fix crawl errors, submit sitemap -- **DNS TXT record already exists**: `google-site-verification=RTnOyspxMve8PKsFb3cUAmPpEz-PMTUEwb8vKwh3L44` -- **Setup**: - 1. Go to search.google.com/search-console - 2. Add property → `https://fivucsas.com` - 3. Choose "DNS record" verification — it will auto-verify (TXT record already in DNS) - 4. Submit sitemap: `https://fivucsas.com/sitemap.xml` -- **What to monitor**: Search queries, click-through rate, crawl errors - -### 2. Google Analytics 4 (Free — 15 min) - -- **Where**: fivucsas.com + demo.fivucsas.com -- **NOT on**: app.fivucsas.com (authenticated dashboard — GDPR/KVKK concern) -- **Setup**: - 1. Go to analytics.google.com - 2. Create Account → Create Property → Web - 3. Add `fivucsas.com` → get Measurement ID (format: `G-XXXXXXXXXX`) - 4. Add the GA4 snippet to landing-website/index.html ``: - ```html - - - ``` - 5. Rebuild and deploy landing-website -- **Events to track**: - - `click_demo` — "Live Demo" button in hero - - `click_dashboard` — "Try Admin Dashboard" button - - `click_github` — GitHub link clicks - - Page views, scroll depth (auto-collected by GA4) - -### 3. Cookie Consent Banner (Required before GA4 for KVKK compliance) - -Add a simple banner to fivucsas.com before enabling analytics: - -```html - - - -``` - -### 4. Uptime Kuma (Already Running) - -- **URL**: https://status.fivucsas.com -- All services already monitored -- Public status page already live - ---- - -## NOT Recommended Right Now - -| Tool | Reason to Skip | -|------|---------------| -| Google Ads | No revenue model yet; organic first | -| Hotjar / Clarity | Overkill for current stage | -| Facebook Pixel | Not relevant for B2B/academic project | -| Mixpanel | GA4 is sufficient | - ---- - -## GitHub Actions: Deployment Notes - -The DNS TXT record for Google Search Console is already in place: -``` -TXT fivucsas.com "google-site-verification=RTnOyspxMve8PKsFb3cUAmPpEz-PMTUEwb8vKwh3L44" -``` -Just add the property in Search Console and it will verify instantly. diff --git a/archive/2026-04-16/BIOMETRIC_FLOW_RESEARCH.md b/archive/2026-04-16/BIOMETRIC_FLOW_RESEARCH.md deleted file mode 100644 index 024154a..0000000 --- a/archive/2026-04-16/BIOMETRIC_FLOW_RESEARCH.md +++ /dev/null @@ -1,777 +0,0 @@ -# FIVUCSAS Biometric Flow Research Report - -> Comprehensive end-to-end trace of Face, Voice, and Fingerprint (WebAuthn) enrollment and verification flows. -> Generated: 2026-04-11 - ---- - -## 1. Architecture Overview - -``` - Browser (React 18 / TypeScript) - ================================ - MediaPipe BlazeFace (face detection) - Web Audio API + MediaRecorder (voice) - WebAuthn API (fingerprint/hardware key) - | - | HTTPS - v - +----------------------------------------------+ - | Traefik v3.6.12 (SSL/routing) | - +----------------------------------------------+ - | | - v v - +--------------------------+ +---------------------------+ - | Identity Core API | | Biometric Processor | - | Spring Boot 3.2.0 | | FastAPI / Python 3.12 | - | Java 21 / Port 8080 | | Port 8001 (internal only) | - | Hexagonal Architecture | | DeepFace + Resemblyzer | - +--------------------------+ +---------------------------+ - | | | - v v v - +-----------+ +---------+ +------------------+ - | PostgreSQL| | Redis | | PostgreSQL 17 | - | 17 | | 7.4 | | + pgvector | - | identity_ | | (WebAuthn| | biometric_db | - | core | | challenges) +------------------+ - +-----------+ +---------+ - - Databases: - identity_core: users, user_enrollments, webauthn_credentials, auth_sessions - biometric_db: face_embeddings (512-dim), voice_enrollments (256-dim) -``` - -**Two enrollment paths exist:** - -1. **Direct path** (Face enrollment from dashboard): Browser -> BiometricService.ts -> biometric-processor directly (via VITE_BIOMETRIC_API_URL, X-API-Key auth) -2. **Proxy path** (Voice enrollment, MFA verification): Browser -> identity-core-api BiometricController/AuthHandlers -> BiometricServiceAdapter -> biometric-processor (Docker internal network) - ---- - -## 2. Face -- Enrollment Flow - -### 2.1 Browser: Capture, Processing, Encoding - -**Key files:** -- `web-app/src/features/auth/components/FaceEnrollmentFlow.tsx` -- `web-app/src/features/auth/hooks/useFaceChallenge.ts` (lines 37-43) -- `web-app/src/features/auth/hooks/useFaceDetection.ts` - -**Step-by-step:** - -1. **Camera init**: `getUserMedia({ video: { facingMode: 'user', width: 640, height: 480 } })` (FaceEnrollmentFlow.tsx:52-53) - -2. **Face detection**: MediaPipe BlazeFace runs on every animation frame via `useFaceDetection` hook. Returns `detected`, `centered`, `boundingBox`, `confidence`, `tooClose`, `tooFar`. - -3. **5-stage liveness challenge** (useFaceChallenge.ts:37-43): - | Stage | Instruction | Hold time | - |-------|------------|-----------| - | `position` | Position face in oval | 300ms | - | `frontal` | Look straight at camera | 300ms | - | `turn_left` | Turn head left | 300ms | - | `turn_right` | Turn head right | 300ms | - | `blink` | Blink naturally | 400ms | - -4. **Stage detection logic** (useFaceChallenge.ts:84-125): - - `position`: face detected AND centered AND not too close/far - - `frontal`: face detected AND centered - - `turn_left`: bounding box center X > 0.5 + 0.06 (HEAD_TURN_THRESHOLD) - - `turn_right`: bounding box center X < 0.5 - 0.06 - - `blink`: confidence drops from >0.6 to <0.5 then recovers - -5. **Timeouts** (useFaceChallenge.ts:46): - - Soft timeout: 6s (STAGE_TIMEOUT_MS) with face detected -> auto-advance with 500ms hold - - Hard timeout: 12s without any detection -> auto-advance - -6. **Image capture** (useFaceChallenge.ts:157-182): At each stage completion: - - Primary: `cropFace(canvas)` extracts face bounding box region - - Fallback: center-crop ~60% of frame if no bounding box - - Format: `canvas.toDataURL('image/jpeg', 0.85)` -> base64 data URL - -7. **Result**: Array of 5 base64 JPEG images (one per stage) passed to `onComplete(captures)` - -### 2.2 API Call (Enrollment) - -**Key file:** `web-app/src/core/services/BiometricService.ts` (lines 72-98) - -The `EnrollmentPage.tsx` (line 460) calls: -```typescript -await biometric.enrollFace(userId, images, tenantId) -``` - -**BiometricService.enrollFace()** routes based on image count: -- **1 image**: `POST /enroll` (multipart form-data: `file` + `user_id`) -- **2+ images** (typical, 5 from liveness): `POST /enroll/multi` (multipart form-data: `files[]` + `user_id`) - -The call goes **directly to biometric-processor** (not through identity-core-api): -``` -Browser -> https://bio.fivucsas.com/api/v1/enroll/multi - (or VITE_BIOMETRIC_API_URL, X-API-Key header) -``` - -**Request shape (multi-image):** -``` -POST /enroll/multi -Content-Type: multipart/form-data -X-API-Key: - -- user_id: "" -- files: face_0.jpg (binary) -- files: face_1.jpg (binary) -- ... up to 5 -``` - -**Response shape:** -```json -{ - "success": true, - "user_id": "", - "images_processed": 5, - "fused_quality_score": 78.5, - "average_quality_score": 72.3, - "individual_quality_scores": [68.1, 73.2, 75.0, 71.5, 73.8], - "message": "Multi-image enrollment completed successfully", - "embedding_dimension": 512, - "fusion_strategy": "quality_weighted_average" -} -``` - -### 2.3 Biometric Processor: Embedding Extraction & Storage - -**Key files:** -- `biometric-processor/app/api/routes/enrollment.py` (lines 147-305: `/enroll/multi`) -- `biometric-processor/app/application/use_cases/enroll_face.py` (lines 54-154) -- `biometric-processor/app/infrastructure/persistence/repositories/pgvector_embedding_repository.py` - -**Processing pipeline per image** (EnrollFaceUseCase.execute): - -1. **Load image**: `cv2.imread(image_path)` (line 85) -2. **Detect face**: `IFaceDetector.detect(image)` -- DeepFace detector (line 91) -3. **Extract face region**: `detection.get_face_region(image)` -- crop bounding box (line 96) -4. **Quality assessment**: `IQualityAssessor.assess(face_region)` -- blur, resolution, lighting checks (line 99) - - Enrollment threshold: quality_score must be `is_acceptable` (configurable, ~70/100) - - Raises `PoorImageQualityError` if below threshold -5. **Extract embedding**: `IEmbeddingExtractor.extract(face_region)` -- DeepFace FaceNet model -> 512-dim float32 vector (line 120) - -**Multi-image fusion** (EnrollMultiImageUseCase): -- Processes each image independently (steps 1-5) -- Fuses embeddings using quality-weighted average (higher quality = higher weight) -- Stores the fused template - -**Storage** (PgVectorEmbeddingRepository.save, lines 173-314): - -1. Insert INDIVIDUAL enrollment row with 512-dim embedding -2. Cap at MAX_INDIVIDUAL_ENROLLMENTS = 5 per user (prune lowest quality) -3. Compute CENTROID as `AVG(embedding)::vector(512)` across all INDIVIDUAL rows -4. Upsert CENTROID row (create or update) - -### 2.4 Database Storage (biometric_db) - -**Table: `face_embeddings`** - -| Column | Type | Description | -|--------|------|-------------| -| `id` | UUID | Primary key (uuid_generate_v4) | -| `user_id` | VARCHAR(255) | User identifier | -| `tenant_id` | VARCHAR(255) | Optional multi-tenant | -| `embedding` | vector(512) | 512-dim FaceNet embedding | -| `quality_score` | FLOAT | 0.0-1.0 (normalized from 0-100) | -| `enrollment_type` | VARCHAR | 'INDIVIDUAL' or 'CENTROID' | -| `is_active` | BOOLEAN | Active flag (default true) | -| `deleted_at` | TIMESTAMP | Soft delete timestamp | -| `created_at` | TIMESTAMP | Creation time | -| `updated_at` | TIMESTAMP | Last update (auto-trigger) | -| `metadata` | JSONB | Additional metadata | - -**Indexes:** -- `idx_face_embeddings_embedding_hnsw`: HNSW index on `embedding` column using `vector_cosine_ops` (m=16, ef_construction=64) -- replaces old IVFFlat -- `idx_embeddings_user_id`: B-tree on `user_id` -- `idx_embeddings_tenant_id`: B-tree on `tenant_id` - -### 2.5 Enrollment Status Lifecycle - -After biometric-processor succeeds, the frontend updates identity_core: - -```typescript -// 1. Create enrollment record -await createEnrollment({ tenantId, methodType: 'FACE' }) -// 2. Mark as complete (FACE is async type) -await httpClient.put(`/users/${userId}/enrollments/FACE/complete`, {}) -``` - -**Table: `user_enrollments`** (identity_core DB, V16 migration) - -| Column | Type | Description | -|--------|------|-------------| -| `id` | UUID | Primary key | -| `user_id` | UUID | FK -> users(id) | -| `tenant_id` | UUID | FK -> tenants(id) | -| `auth_method_type` | VARCHAR(30) | 'FACE', 'VOICE', etc. | -| `status` | VARCHAR(20) | Lifecycle state | -| `enrollment_data` | JSONB | Method-specific data | -| `enrolled_at` | TIMESTAMP | When enrolled | -| `expires_at` | TIMESTAMP | Optional expiry | -| `revoked_at` | TIMESTAMP | When revoked | - -**Status lifecycle:** `NOT_ENROLLED` -> `PENDING` -> `ENROLLED` | `FAILED` | `REVOKED` | `EXPIRED` - ---- - -## 3. Face -- Verification Flow - -### 3.1 Browser: Capture & Submission - -**Two verification contexts:** - -**A. Dashboard verification** (FaceCaptureStep.tsx): -- Single capture: detect face, hold 1.5s (HOLD_DURATION), auto-capture via `cropFace(canvas)` -- Sends single base64 JPEG via `onSubmit(image)` - -**B. MFA step verification** (FaceCaptureStep in auth flow): -- Same single-capture flow -- Submits via `AuthSessionRepository.completeStep()` with `{ data: { image: base64 } }` - -### 3.2 MFA Verification Path (through identity-core-api) - -**Endpoint:** `POST /auth/mfa/step` -```json -{ - "sessionToken": "", - "data": { "image": "" } -} -``` - -**FaceAuthHandler.validate()** (FaceAuthHandler.java:34-82): -1. Extract `image` from data map (base64 string) -2. Check `session.getUser() != null` -3. Decode base64 -> byte[] -> `Base64MultipartFile` -4. Call `biometricServicePort.verifyFace(userId, imageFile)` - -**BiometricServiceAdapter.verifyFace()** (BiometricServiceAdapter.java:113-136): -``` -POST http://biometric-processor:8001/verify -Content-Type: multipart/form-data -X-API-Key: - -- file: face.jpg (binary) -- user_id: "" -``` - -### 3.3 Biometric Processor: Verification - -**Key file:** `biometric-processor/app/application/use_cases/verify_face.py` - -1. Load image, detect face, extract face region -2. **Quality gate**: score >= 50.0 (VERIFICATION_QUALITY_THRESHOLD, line 37) -- more lenient than enrollment (70) -3. Extract 512-dim embedding from probe image -4. Retrieve stored CENTROID embedding: `repository.find_by_user_id(user_id)` (prefers CENTROID, falls back to latest INDIVIDUAL) -5. **Calculate cosine distance**: `CosineSimilarityCalculator.calculate(new_embedding, stored_embedding)` - - L2-normalize both vectors - - `cosine_distance = 1.0 - dot(emb1_norm, emb2_norm)` -6. **Threshold check**: distance < 0.6 (default threshold) - - 0.0 = identical, 0.4 = high confidence, 0.6 = balanced threshold, 0.8 = different - -**Confidence = 1.0 - distance** (cosine_similarity.py:135-145) - -**Response:** -```json -{ - "verified": true, - "confidence": 0.82, - "distance": 0.18, - "threshold": 0.6, - "message": "Face verified successfully" -} -``` - -### 3.4 Back in FaceAuthHandler - -**Double-check logic** (FaceAuthHandler.java:60-77): -1. Check `result.get("error_code")` for `"SPOOF_DETECTED"` -> reject -2. Check `result.get("verified")` boolean -3. **Fallback**: if not verified but `confidence >= 0.7` (DEFAULT_CONFIDENCE_THRESHOLD), accept anyway -4. Return `StepResult.success()` or `StepResult.failure()` - ---- - -## 4. Voice -- Enrollment Flow - -### 4.1 Browser: Recording & Encoding - -**Key file:** `web-app/src/features/auth/components/VoiceEnrollmentFlow.tsx` - -1. **Recording**: `MediaRecorder` with `mimeType: 'audio/webm;codecs=opus'` (line 219) -2. **Duration**: Up to 10 seconds (MAX_RECORDING_SECONDS) -3. **Voice activity check**: Amplitude monitoring via AnalyserNode; rejects if `maxAmplitude < 0.05` (line 231) -4. **Passphrase**: Random from 6 built-in English phrases (lines 89-96), displayed to user -5. **Audio conversion** (lines 59-77): - - WebM -> WAV 16kHz mono via `AudioContext({ sampleRate: 16000 })` - - `decodeAudioData()` -> mono channel -> `createWavBuffer()` (PCM int16) - - Fallback: send raw WebM if conversion fails -6. **Encoding**: `FileReader.readAsDataURL(wavBlob)` -> strip `data:audio/wav;base64,` prefix -> raw base64 string - -### 4.2 API Call (Enrollment) - -**VoiceEnrollmentFlow calls identity-core-api proxy** (line 321): -``` -POST /api/v1/biometric/voice/enroll/{userId} -Authorization: Bearer -Content-Type: application/json - -{ "voiceData": "" } -``` - -**BiometricController.enrollVoice()** -> `biometricServicePort.enrollVoice(userId, voiceData)` - -**BiometricServiceAdapter.enrollVoice()** (BiometricServiceAdapter.java:176-189): -``` -POST http://biometric-processor:8001/voice/enroll -Content-Type: application/json -X-API-Key: - -{ "user_id": "", "voice_data": "" } -``` - -### 4.3 Biometric Processor: Voice Embedding - -**Key files:** -- `biometric-processor/app/api/routes/voice.py` (lines 58-108) -- `biometric-processor/app/infrastructure/ml/voice/speaker_embedder.py` - -1. **Decode audio** (speaker_embedder.py:81-104): - - Strip data URI prefix if present - - Base64 decode -> raw bytes - - Auto-detect format (WAV magic bytes `RIFF`, WebM `\x1aE\xdf\xa3`, etc.) - -2. **Convert to 16kHz mono** (speaker_embedder.py:110-154): - - pydub + ffmpeg for WebM/Opus - - Direct WAV parse for WAV files (faster, no ffmpeg) - - Resample if needed via `scipy.signal.resample` - - Minimum duration: 0.5 seconds - -3. **Extract embedding** (speaker_embedder.py:193-226): - - `resemblyzer.preprocess_wav()` -- VAD + normalization (skips resample since already 16kHz) - - `VoiceEncoder.embed_utterance(processed)` -> 256-dim vector - - L2-normalize to unit vector for cosine similarity - - Output: `np.float32` array of shape (256,) - -### 4.4 Database Storage (biometric_db) - -**Table: `voice_enrollments`** - -| Column | Type | Description | -|--------|------|-------------| -| `id` | (auto) | Primary key | -| `user_id` | VARCHAR | User identifier | -| `tenant_id` | VARCHAR | Optional tenant | -| `embedding` | vector(256) | 256-dim Resemblyzer speaker embedding | -| `quality_score` | FLOAT | Always 1.0 (no voice quality metric yet) | -| `enrollment_type` | VARCHAR | 'INDIVIDUAL' or 'CENTROID' | -| `deleted_at` | TIMESTAMP | Soft delete | -| `created_at` | TIMESTAMP | Creation time | -| `updated_at` | TIMESTAMP | Last update | - -**Centroid pattern** (same as face): Each enrollment stores an INDIVIDUAL row, then computes/updates CENTROID as `AVG(embedding)::vector(256)` across all INDIVIDUAL rows. - -**Indexes:** -- `idx_voice_enrollments_embedding_hnsw`: HNSW (m=16, ef_construction=64, vector_cosine_ops) -- `idx_voice_enrollments_user_type`: B-tree on `(user_id, enrollment_type) WHERE deleted_at IS NULL` - ---- - -## 5. Voice -- Verification Flow - -### 5.1 Browser - -Same recording flow as enrollment. Submitted via: -- **MFA step**: `POST /auth/mfa/step` with `{ data: { voiceData: "" } }` -- **Direct verify**: `POST /api/v1/biometric/voice/verify/{userId}` with `{ voiceData: "" }` - -### 5.2 VoiceAuthHandler (MFA path) - -**VoiceAuthHandler.java:27-57:** -1. Extract `voiceData` from data map -2. Call `biometricServicePort.verifyVoice(userId, voiceData)` -3. Check `result.get("verified")` -> StepResult.success/failure - -### 5.3 Biometric Processor Verification - -**voice.py:114-178:** -1. Extract 256-dim probe embedding from submitted audio (same pipeline as enrollment) -2. Load enrolled CENTROID: `repo.find_by_user_id(user_id)` (prefers CENTROID, falls back to latest INDIVIDUAL) -3. **Cosine similarity**: `np.dot(probe_embedding, enrolled_embedding)` -- both already L2-normalized -4. Clamp to [0, 1] -5. **Threshold**: `VERIFY_THRESHOLD = 0.65` (voice.py:120) -6. `verified = similarity >= 0.65` - -**Response:** -```json -{ - "success": true, - "verified": true, - "confidence": 0.7823, - "message": "Voice verified successfully", - "user_id": "", - "modality": "voice" -} -``` - ---- - -## 6. Fingerprint/WebAuthn -- Enrollment Flow - -### 6.1 Browser: WebAuthn Registration Ceremony - -**Key file:** `web-app/src/features/auth/components/WebAuthnEnrollment.tsx` - -This uses the **W3C WebAuthn API** for platform authenticators (Touch ID, Windows Hello, Android biometrics). - -**Step 1: Get registration options** (WebAuthnEnrollment.tsx:137-140): -``` -POST /api/v1/webauthn/register/options/{userId} -Authorization: Bearer -``` - -**Response from DeviceController.getRegistrationOptions()** (DeviceController.java:85-113): -```json -{ - "sessionId": "", - "challenge": "", - "rpId": "fivucsas.com", - "rpName": "Fivucsas Identity", - "userId": "", - "userName": "user@example.com", - "excludeCredentials": ["", ...], - "attestation": "direct", - "authenticatorSelection": { - "authenticatorAttachment": "platform", - "requireResidentKey": false, - "userVerification": "preferred" - } -} -``` - -**Challenge generation** (WebAuthnService.java:37-44): -- 32 random bytes via `SecureRandom` -- Base64url encoded (no padding) -- Stored in Redis: key `webauthn:challenge:`, TTL 5 minutes - -**Step 2: Browser WebAuthn create** (WebAuthnEnrollment.tsx:154-179): -```typescript -navigator.credentials.create({ - publicKey: { - challenge: , - rp: { name: "Fivucsas Identity", id: "fivucsas.com" }, - user: { id: , name: email, displayName: email }, - pubKeyCredParams: [ - { type: "public-key", alg: -7 }, // ES256 (ECDSA P-256) - { type: "public-key", alg: -257 }, // RS256 (RSASSA-PKCS1-v1_5) - ], - authenticatorSelection: { - authenticatorAttachment: "platform", // or "cross-platform" for hardware keys - requireResidentKey: false, - userVerification: "preferred", - }, - excludeCredentials: [...], - attestation: "direct", - timeout: 60000, - } -}) -``` - -The browser prompts for biometric (fingerprint/Face ID/Windows Hello). On success, returns `PublicKeyCredential`. - -**Step 3: Encode and send attestation** (WebAuthnEnrollment.tsx:189-222): -``` -POST /api/v1/webauthn/register/verify -Authorization: Bearer -Content-Type: application/json - -{ - "userId": "", - "sessionId": "", - "credentialId": "", // credential.id (from browser) - "publicKey": "", // getPublicKey() or attestationObject - "clientDataJSON": "", // attestationResponse.clientDataJSON - "attestationFormat": "packed", - "transports": "internal", // or "usb,ble,nfc" for hardware keys - "deviceName": "My MacBook Touch ID" -} -``` - -### 6.2 Backend: Registration Verification - -**DeviceController.verifyRegistration()** (DeviceController.java:116-175): - -1. Parse request fields -2. **Validate challenge** via `webAuthnService.validateRegistrationChallenge(sessionId, clientDataJson)`: - - Retrieve stored challenge from Redis - - Decode clientDataJSON (base64url -> JSON) - - Verify `type == "webauthn.create"` - - Verify `challenge` matches stored value - - Consume (delete) challenge from Redis -3. Check `credentialRepository.existsByCredentialId(credentialId)` for duplicates -4. **Store credential** in `webauthn_credentials` table: - ```java - WebAuthnCredential.builder() - .user(user) - .credentialId(credentialId) - .publicKey(publicKey) // base64url X.509 ECDSA public key - .publicKeyAlgorithm("ES256") - .attestationFormat("packed") - .transports("internal") - .deviceName("My MacBook Touch ID") - .build() - ``` -5. **Auto-complete enrollment**: `manageEnrollmentUseCase.completeEnrollment(userId, FINGERPRINT, "{}")` -- marks `user_enrollments` row as ENROLLED - -### 6.3 Database Storage (identity_core) - -**Table: `webauthn_credentials`** (V18 migration) - -| Column | Type | Description | -|--------|------|-------------| -| `id` | UUID | Primary key (gen_random_uuid) | -| `user_id` | UUID | FK -> users(id) CASCADE | -| `credential_id` | VARCHAR(512) | WebAuthn credential ID (UNIQUE) | -| `public_key` | TEXT | Base64url X.509 public key | -| `public_key_algorithm` | VARCHAR(20) | 'ES256' (default) or 'RS256' | -| `sign_count` | BIGINT | Authenticator signature counter | -| `device_name` | VARCHAR(100) | User-provided device label | -| `attestation_format` | VARCHAR(50) | 'packed', 'none', etc. | -| `transports` | VARCHAR(255) | 'internal', 'usb', 'ble,nfc', etc. | -| `created_at` | TIMESTAMP | Creation time | -| `last_used_at` | TIMESTAMP | Last authentication time | - -**Indexes:** -- `idx_webauthn_credentials_user_id`: B-tree on `user_id` -- `idx_webauthn_credentials_credential_id`: B-tree on `credential_id` - ---- - -## 7. Fingerprint/WebAuthn -- Verification Flow - -### 7.1 Browser: WebAuthn Assertion - -**Key file:** `web-app/src/features/auth/components/steps/FingerprintStep.tsx` - -**Step 1: Request challenge** (via MFA step or `onRequestChallenge` callback): -- MFA path: `POST /auth/mfa/step` with `{ data: { action: "challenge" } }` -- FingerprintAuthHandler.generateChallenge() returns: - ```json - { - "status": "CHALLENGE", - "data": { - "challenge": "", - "rpId": "fivucsas.com", - "authenticatorAttachment": "platform", - "timeout": "60000", - "allowCredentials": ["", ""] - } - } - ``` - -**Step 2: Browser WebAuthn get** (FingerprintStep.tsx:86-95): -```typescript -navigator.credentials.get({ - publicKey: { - challenge: , - rpId: "fivucsas.com", // from server, NOT window.location.hostname - userVerification: "required", // biometric required for fingerprint - authenticatorAttachment: "platform", - timeout: 60000, - allowCredentials: [ // enables non-discoverable credentials - { type: "public-key", id: } - ], - } -}) -``` - -**Step 3: Encode assertion** (FingerprintStep.tsx:101-106): -```typescript -btoa(JSON.stringify({ - credentialId: credential.id, // base64url from browser - authenticatorData: arrayBufferToBase64(assertionResponse.authenticatorData), - clientDataJSON: arrayBufferToBase64(assertionResponse.clientDataJSON), - signature: arrayBufferToBase64(assertionResponse.signature), -})) -``` -Result: base64-encoded JSON string submitted as `fingerprintData`. - -### 7.2 Backend: Assertion Verification - -**FingerprintAuthHandler.validate()** (FingerprintAuthHandler.java:44-126): - -1. If `action == "challenge"`: generate and return challenge (see above) -2. Parse `fingerprintData`: base64 decode -> JSON -> extract credentialId, authenticatorData, clientDataJSON, signature -3. Look up credential: `credentialRepository.findByCredentialId(credentialId)` -4. Verify user ownership: `credential.getUser().getId().equals(session.getUser().getId())` -5. **Cryptographic verification** via `webAuthnService.verifyAssertion()`: - -**WebAuthnService.verifyAssertion()** (WebAuthnService.java:99-148): -1. Retrieve stored challenge from Redis (`webauthn:challenge:`) -2. **Validate clientDataJSON** (lines 209-243): - - Decode base64url -> JSON - - `type == "webauthn.get"` - - `challenge` matches stored value - - `origin` contains `rpId` ("fivucsas.com") -3. **Validate authenticatorData** (lines 252-291): - - Minimum 37 bytes (32 rpIdHash + 1 flags + 4 signCount) - - SHA-256 of rpId ("fivucsas.com") must match first 32 bytes - - User Present (UP) flag bit 0 must be set -4. **Verify ECDSA signature** (lines 153-184): - - Decode public key (base64url -> X.509 -> EC PublicKey) - - Build signed data: `authenticatorData || SHA-256(clientDataJSON)` - - Verify with `SHA256withECDSA` signature algorithm -5. Consume challenge from Redis (one-time use) - -6. **Update sign count** (FingerprintAuthHandler.java:108-112): - - Extract from authenticatorData bytes 33-36 (big-endian uint32) - - If new > stored: update credential (detects cloned authenticators) - -### 7.3 Database Queries During Verification - -```sql --- 1. Find credential by ID -SELECT * FROM webauthn_credentials WHERE credential_id = ?; - --- 2. Challenge from Redis -GET webauthn:challenge: - --- 3. Update sign count after successful verification -UPDATE webauthn_credentials SET sign_count = ?, last_used_at = NOW() -WHERE id = ?; -``` - ---- - -## 8. Complete Database Schema Summary - -### identity_core Database - -**`user_enrollments`** (V16): -```sql -CREATE TABLE user_enrollments ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE, - tenant_id UUID NOT NULL REFERENCES tenants(id), - auth_method_type VARCHAR(30) NOT NULL, -- FACE, VOICE, FINGERPRINT, etc. - status VARCHAR(20) NOT NULL DEFAULT 'NOT_ENROLLED', - enrollment_data JSONB DEFAULT '{}', - enrolled_at TIMESTAMP WITH TIME ZONE, - expires_at TIMESTAMP WITH TIME ZONE, - revoked_at TIMESTAMP WITH TIME ZONE, - created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(), - updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(), - UNIQUE (user_id, auth_method_type, tenant_id) -); -``` - -**`webauthn_credentials`** (V18): -```sql -CREATE TABLE webauthn_credentials ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE, - credential_id VARCHAR(512) NOT NULL UNIQUE, - public_key TEXT NOT NULL, - public_key_algorithm VARCHAR(20) NOT NULL DEFAULT 'ES256', - sign_count BIGINT NOT NULL DEFAULT 0, - device_name VARCHAR(100), - attestation_format VARCHAR(50), - transports VARCHAR(255), - created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(), - last_used_at TIMESTAMP WITH TIME ZONE -); -``` - -### biometric_db Database - -**`face_embeddings`**: -```sql -CREATE TABLE face_embeddings ( - id UUID PRIMARY KEY DEFAULT uuid_generate_v4(), - user_id VARCHAR(255) NOT NULL, - tenant_id VARCHAR(255), - embedding vector(512) NOT NULL, - quality_score FLOAT NOT NULL, -- 0.0-1.0 (normalized) - enrollment_type VARCHAR, -- 'INDIVIDUAL' or 'CENTROID' - is_active BOOLEAN DEFAULT TRUE, - deleted_at TIMESTAMP WITH TIME ZONE, - created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(), - updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(), - metadata JSONB DEFAULT '{}' -); --- HNSW index: idx_face_embeddings_embedding_hnsw (m=16, ef_construction=64) -``` - -**`voice_enrollments`**: -```sql -CREATE TABLE voice_enrollments ( - -- Same structure as face_embeddings but with vector(256) - user_id VARCHAR, - tenant_id VARCHAR, - embedding vector(256) NOT NULL, - quality_score FLOAT, - enrollment_type VARCHAR, -- 'INDIVIDUAL' or 'CENTROID' - deleted_at TIMESTAMP WITH TIME ZONE, - created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(), - updated_at TIMESTAMP WITH TIME ZONE -); --- HNSW index: idx_voice_enrollments_embedding_hnsw (m=16, ef_construction=64) -``` - ---- - -## 9. Known Issues & Gaps - -### 9.1 Face - -1. **Liveness score is hardcoded**: `EnrollmentResponse.liveness_score = 1.0` (enrollment.py:127). Server-side anti-spoofing runs during verification (SPOOF_DETECTED check in FaceAuthHandler) but not during enrollment. - -2. **FaceAuthHandler confidence fallback**: If biometric-processor returns `verified: false` but `confidence >= 0.7`, the handler overrides to success (FaceAuthHandler.java:66-68). This secondary threshold (0.7) differs from the processor's own threshold (0.6) and could cause inconsistent behavior. - -3. **Init SQL schema drift**: The `scripts/db/init.sql` defines `face_embeddings` without `enrollment_type`, `deleted_at`, or `is_active` columns that the repository code uses. The production schema was likely altered via manual SQL or a separate migration. The `scripts/init-database.sql` shows an older 128-dim schema. - -4. **Unique constraint conflict**: `init.sql` has `UNIQUE (user_id, tenant_id)` on face_embeddings, but the repository stores multiple INDIVIDUAL rows per user. The production schema must have dropped this constraint. - -5. **Direct browser -> biometric-processor path**: Face enrollment bypasses identity-core-api, meaning JWT auth is not enforced at the biometric level (only API key). The CLAUDE.md notes bio.fivucsas.com is internal-only, but the BiometricService.ts has a fallback URL. - -### 9.2 Voice - -6. **No voice quality metric**: `quality_score` is always 1.0 (voice.py:83). No SNR, speech clarity, or minimum energy checks beyond the basic amplitude gate (0.05 threshold in the browser). - -7. **No voice liveness detection**: No anti-replay or anti-spoofing for voice. A recording of someone's voice would pass verification. - -8. **Voice centroid unbounded**: Unlike face (capped at 5 INDIVIDUAL rows), voice enrollment has no cap on individual enrollments, which could dilute the centroid over time. - -### 9.3 Fingerprint/WebAuthn - -9. **No attestation verification**: The backend does NOT verify the attestation object during registration (DeviceController.java:137-138 only validates the challenge, not the attestation signature). This means any client can register a credential without proving it came from a genuine authenticator. - -10. **Public key source ambiguity**: The frontend sends `getPublicKey()` if available, otherwise falls back to `attestationObject` (WebAuthnEnrollment.tsx:208-211). The backend stores whatever is sent without validation -- if attestationObject is sent instead of the raw public key, signature verification during authentication will fail. - -### 9.4 Cross-Cutting - -11. **Enrollment status can desync**: Face and voice enrollment data lives in biometric_db while enrollment status lives in identity_core. If biometric-processor succeeds but the subsequent `PUT /enrollments/FACE/complete` call fails, data exists in biometric_db but status remains PENDING. - -12. **No enrollment health verification for voice**: The enrollment health check validates face by calling the biometric processor, but voice enrollment health is not explicitly checked. - ---- - -## 10. Recommendations - -1. **Add server-side liveness during enrollment**: Run anti-spoofing checks during face enrollment, not just verification. Reject enrollment of photos/screens. - -2. **Harmonize face confidence thresholds**: Use a single configurable threshold rather than having 0.6 in biometric-processor and 0.7 fallback in FaceAuthHandler. - -3. **Add voice quality scoring**: Implement SNR measurement and minimum speech energy checks in the biometric processor. - -4. **Add attestation verification**: Verify the attestation signature chain during WebAuthn registration to ensure credentials come from genuine authenticators. - -5. **Cap voice enrollments**: Add MAX_INDIVIDUAL_ENROLLMENTS limit for voice (same as face's 5-cap) to prevent centroid dilution. - -6. **Add enrollment saga/compensation**: If biometric enrollment succeeds but enrollment record update fails, implement a compensation mechanism to clean up orphaned biometric data. - -7. **Fix init.sql schema**: Update `scripts/db/init.sql` to match the production schema (add enrollment_type, deleted_at, is_active; remove UNIQUE constraint; update vector dimension to 512). - -8. **Add voice anti-replay**: Implement challenge-response for voice (e.g., require reading a random phrase) and/or add server-side replay detection using audio fingerprinting. diff --git a/archive/2026-04-16/DOCS_MODULE_PROFESSIONAL_DESIGN.md b/archive/2026-04-16/DOCS_MODULE_PROFESSIONAL_DESIGN.md deleted file mode 100644 index 02183a0..0000000 --- a/archive/2026-04-16/DOCS_MODULE_PROFESSIONAL_DESIGN.md +++ /dev/null @@ -1,1123 +0,0 @@ -# Documentation Module - Professional Design - -**Document Version:** 1.0 -**Date:** 2025-11-17 -**Design Approach:** SOLID, DRY, KISS, YAGNI Compliant -**Target:** University Engineering Project -**Status:** ✅ PROFESSIONAL DESIGN - READY FOR IMPLEMENTATION - ---- - -## Executive Summary - -This document provides a professional, principle-driven design for the FIVUCSAS documentation module that: - -✅ **Respects SOLID principles** - Proper separation of concerns -✅ **Follows DRY** - Reuses existing 90% complete documentation -✅ **Applies KISS** - Simple, maintainable solution -✅ **Honors YAGNI** - Documents what exists, not what's planned -✅ **Embraces automation** - Auto-generated API docs from code -✅ **Ensures maintainability** - Single source of truth - -### Key Metrics - -| Metric | Current Plan | Professional Design | Improvement | -|--------|--------------|---------------------|-------------| -| **Implementation Time** | 18-26 hours | 4-6 hours | **77% faster** | -| **Maintenance Effort** | High (manual) | Low (automated) | **85% reduction** | -| **Documentation Accuracy** | Manual sync required | Auto-synced from code | **100% accurate** | -| **DRY Compliance** | 10% | 95% | **850% improvement** | -| **YAGNI Compliance** | 15% | 95% | **533% improvement** | - ---- - -## 1. Design Philosophy - -### 1.1 Core Principles - -#### Principle 1: Document Reality, Not Plans (YAGNI) -``` -❌ BAD: Document features you plan to build -✅ GOOD: Document features that exist and work -``` - -**Rationale:** Documentation for non-existent features becomes outdated before it's even published. - -#### Principle 2: Single Source of Truth (DRY) -``` -❌ BAD: Code + Manual docs (two sources of truth) -✅ GOOD: Code with annotations → Auto-generated docs (one source) -``` - -**Rationale:** Manual documentation inevitably gets out of sync with code. - -#### Principle 3: Automate Everything Possible (KISS) -``` -❌ BAD: Manually write and maintain OpenAPI YAML -✅ GOOD: Generate from Spring Boot annotations -``` - -**Rationale:** Automation ensures consistency and reduces maintenance burden. - -#### Principle 4: Separation of Concerns (SOLID - SRP) -``` -❌ BAD: One repo for API docs, user guides, architecture, deployment -✅ GOOD: Separate documentation by audience and purpose -``` - -**Rationale:** Different audiences need different documentation. - -### 1.2 Documentation Audiences - -``` -┌─────────────────────────────────────────────────────────────┐ -│ DOCUMENTATION PYRAMID │ -├─────────────────────────────────────────────────────────────┤ -│ │ -│ ┌────────────────────────────────────────────┐ │ -│ │ Level 1: DEVELOPERS (Internal) │ │ -│ │ - CLAUDE.md (how to work with codebase) │ │ -│ │ - Architecture decisions │ │ -│ │ - Implementation guides │ │ -│ │ Audience: Team members │ │ -│ └────────────────────────────────────────────┘ │ -│ │ │ -│ ▼ │ -│ ┌────────────────────────────────────────────┐ │ -│ │ Level 2: API CONSUMERS (External) │ │ -│ │ - Auto-generated API docs (OpenAPI) │ │ -│ │ - Integration guides │ │ -│ │ - Code examples │ │ -│ │ Audience: External developers │ │ -│ └────────────────────────────────────────────┘ │ -│ │ │ -│ ▼ │ -│ ┌────────────────────────────────────────────┐ │ -│ │ Level 3: END USERS (Non-technical) │ │ -│ │ - User guides with screenshots │ │ -│ │ - How-to tutorials │ │ -│ │ - FAQ │ │ -│ │ Audience: Admin users, kiosk operators │ │ -│ └────────────────────────────────────────────┘ │ -│ │ │ -│ ▼ │ -│ ┌────────────────────────────────────────────┐ │ -│ │ Level 4: OPERATIONS (DevOps) │ │ -│ │ - Deployment guides │ │ -│ │ - Monitoring setup │ │ -│ │ - Troubleshooting │ │ -│ │ Audience: System administrators │ │ -│ └────────────────────────────────────────────┘ │ -│ │ -└─────────────────────────────────────────────────────────────┘ -``` - -**Design Decision:** Separate documentation by audience, not by topic. - ---- - -## 2. Architecture Design - -### 2.1 Documentation Architecture - -``` -FIVUCSAS Documentation System -│ -├─── Source Layer (SINGLE SOURCE OF TRUTH) -│ │ -│ ├─ Java Code -│ │ ├─ Spring Boot annotations (@RestController, @Operation) -│ │ ├─ JPA entities (@Entity, @Table) -│ │ └─ Bean Validation (@NotBlank, @Email) -│ │ -│ ├─ Python Code -│ │ ├─ FastAPI decorators (@app.post, @app.get) -│ │ └─ Pydantic models (BaseModel) -│ │ -│ └─ Markdown Files -│ └─ Architecture decisions, guides -│ -├─── Generation Layer (AUTOMATION) -│ │ -│ ├─ SpringDoc OpenAPI (Java → OpenAPI 3.0) -│ │ └─ Auto-generates: /v3/api-docs, /swagger-ui.html -│ │ -│ ├─ FastAPI OpenAPI (Python → OpenAPI 3.0) -│ │ └─ Auto-generates: /docs, /openapi.json -│ │ -│ └─ Documentation Index (README generator) -│ └─ Auto-generates: Table of contents from file structure -│ -├─── Presentation Layer (USER-FACING) -│ │ -│ ├─ Interactive API Docs -│ │ ├─ Swagger UI (backend: localhost:8080/swagger-ui.html) -│ │ └─ FastAPI Docs (biometric: localhost:8001/docs) -│ │ -│ ├─ GitHub Repository -│ │ ├─ Organized markdown files -│ │ └─ README.md with navigation -│ │ -│ └─ (Future) Documentation Site -│ └─ Only if project becomes public SaaS -│ -└─── Quality Layer (VALIDATION) - │ - ├─ Link Checker (CI/CD) - ├─ Code Example Tests (CI/CD) - └─ Documentation Coverage (CI/CD) -``` - -### 2.2 Design Patterns Applied - -#### Pattern 1: **Repository Pattern** (for documentation organization) - -``` -docs/ -├── README.md # Index (Navigation interface) -├── 01-getting-started/ # Repository: Getting Started -├── 02-architecture/ # Repository: Architecture -├── 03-development/ # Repository: Development -├── 04-api/ # Repository: API (auto-generated) -├── 05-testing/ # Repository: Testing -├── 06-deployment/ # Repository: Deployment -└── 07-status/ # Repository: Project Status -``` - -**Benefits:** -- Clear separation of concerns -- Easy to find documentation -- Scalable structure - -#### Pattern 2: **Factory Pattern** (for API documentation generation) - -```java -// Factory: Generates documentation based on source code -@Configuration -public class DocumentationFactory { - - @Bean - public OpenAPI createOpenAPISpecification() { - // Automatically creates OpenAPI spec from controllers - return new OpenAPI() - .info(createAPIInfo()) - .servers(createServers()) - .components(createComponents()); - } - - private Info createAPIInfo() { - return new Info() - .title("FIVUCSAS API") - .version("1.0.0") - .description("Auto-generated from source code"); - } -} -``` - -**Benefits:** -- Centralized documentation configuration -- Auto-generation from source -- Always in sync - -#### Pattern 3: **Decorator Pattern** (for code annotations) - -```java -// Decorators: Add documentation metadata to code -@RestController -@RequestMapping("/api/v1/auth") -@Tag(name = "Authentication", description = "User authentication endpoints") -public class AuthController { - - @PostMapping("/login") - @Operation( - summary = "User login", - description = "Authenticate user with email and password, returns JWT token" - ) - @ApiResponses({ - @ApiResponse(responseCode = "200", description = "Login successful"), - @ApiResponse(responseCode = "401", description = "Invalid credentials") - }) - public ResponseEntity login(@RequestBody LoginRequest request) { - // Implementation - } -} -``` - -**Benefits:** -- Documentation lives with code -- No separate maintenance -- Always accurate - -#### Pattern 4: **Template Method Pattern** (for consistent documentation structure) - -```markdown - -# [Feature Name] - -## Overview -[Brief description] - -## Prerequisites -[What's needed] - -## Step-by-Step Guide -[Numbered steps] - -## Example -[Code example] - -## Troubleshooting -[Common issues] - -## Related Documentation -[Links] -``` - -**Benefits:** -- Consistent documentation structure -- Easy to read -- Professional appearance - ---- - -## 3. Technical Design - -### 3.1 API Documentation (Auto-Generated) - -#### Backend API (Spring Boot) - -**Implementation:** - -```groovy -// build.gradle -dependencies { - // SpringDoc OpenAPI - implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0' -} -``` - -```java -// src/main/java/config/OpenAPIConfig.java -package com.fivucsas.identity.config; - -import io.swagger.v3.oas.models.OpenAPI; -import io.swagger.v3.oas.models.info.Contact; -import io.swagger.v3.oas.models.info.Info; -import io.swagger.v3.oas.models.info.License; -import io.swagger.v3.oas.models.security.SecurityScheme; -import io.swagger.v3.oas.models.security.SecurityRequirement; -import io.swagger.v3.oas.models.servers.Server; -import org.springframework.context.annotation.Bean; -import org.springframework.context.annotation.Configuration; - -import java.util.List; - -@Configuration -public class OpenAPIConfig { - - @Bean - public OpenAPI fivucsasOpenAPI() { - return new OpenAPI() - .info(new Info() - .title("FIVUCSAS API") - .version("1.0.0") - .description("Face and Identity Verification Using Cloud-based SaaS\n\n" + - "A multi-tenant biometric authentication platform for face recognition, " + - "liveness detection, and identity management.") - .contact(new Contact() - .name("FIVUCSAS Team") - .email("contact@fivucsas.com") - .url("https://github.com/Rollingcat-Software/FIVUCSAS")) - .license(new License() - .name("MIT License") - .url("https://opensource.org/licenses/MIT"))) - .servers(List.of( - new Server() - .url("http://localhost:8080") - .description("Development Server"), - new Server() - .url("https://api.fivucsas.com") - .description("Production Server (Future)") - )) - .addSecurityItem(new SecurityRequirement().addList("bearerAuth")) - .components(new io.swagger.v3.oas.models.Components() - .addSecuritySchemes("bearerAuth", - new SecurityScheme() - .type(SecurityScheme.Type.HTTP) - .scheme("bearer") - .bearerFormat("JWT") - .description("JWT token authentication"))); - } -} -``` - -**Endpoints Auto-Generated:** -- Swagger UI: `http://localhost:8080/swagger-ui/index.html` -- OpenAPI JSON: `http://localhost:8080/v3/api-docs` -- OpenAPI YAML: `http://localhost:8080/v3/api-docs.yaml` - -**Example Controller Documentation:** - -```java -@RestController -@RequestMapping("/api/v1/users") -@Tag(name = "User Management", description = "Endpoints for managing users") -public class UserController { - - @GetMapping - @Operation( - summary = "Get all users", - description = "Retrieves a list of all users in the system. Requires ADMIN role." - ) - @ApiResponses({ - @ApiResponse( - responseCode = "200", - description = "Successfully retrieved users", - content = @Content( - mediaType = "application/json", - array = @ArraySchema(schema = @Schema(implementation = UserDTO.class)) - ) - ), - @ApiResponse(responseCode = "403", description = "Forbidden - requires ADMIN role") - }) - @SecurityRequirement(name = "bearerAuth") - public ResponseEntity> getAllUsers() { - // Implementation - } - - @PostMapping - @Operation( - summary = "Create new user", - description = "Creates a new user account with the provided information" - ) - @ApiResponses({ - @ApiResponse( - responseCode = "201", - description = "User created successfully", - content = @Content(schema = @Schema(implementation = UserDTO.class)) - ), - @ApiResponse(responseCode = "400", description = "Invalid input data"), - @ApiResponse(responseCode = "409", description = "User already exists") - }) - public ResponseEntity createUser( - @Parameter(description = "User creation request", required = true) - @Valid @RequestBody CreateUserRequest request - ) { - // Implementation - } -} -``` - -**DTO Documentation:** - -```java -@Schema(description = "User data transfer object") -public class UserDTO { - - @Schema( - description = "Unique user identifier", - example = "123e4567-e89b-12d3-a456-426614174000", - accessMode = Schema.AccessMode.READ_ONLY - ) - private UUID id; - - @Schema( - description = "User email address", - example = "john.doe@example.com", - required = true - ) - @Email(message = "Invalid email format") - @NotBlank(message = "Email is required") - private String email; - - @Schema( - description = "User first name", - example = "John", - required = true, - minLength = 2, - maxLength = 50 - ) - @NotBlank(message = "First name is required") - @Size(min = 2, max = 50) - private String firstName; - - @Schema( - description = "User last name", - example = "Doe", - required = true - ) - @NotBlank - private String lastName; - - @Schema( - description = "User account status", - example = "ACTIVE", - allowableValues = {"ACTIVE", "INACTIVE", "SUSPENDED"} - ) - private UserStatus status; - - @Schema( - description = "Whether biometric enrollment is completed", - example = "true" - ) - private Boolean isBiometricEnrolled; - - // Getters, setters, constructors -} -``` - -**Benefits:** -- ✅ **Zero maintenance** - Auto-generated from code -- ✅ **Always accurate** - Reflects current API -- ✅ **Interactive** - Try API calls directly from Swagger UI -- ✅ **Exportable** - OpenAPI YAML for Postman, clients -- ✅ **DRY compliant** - Single source of truth (code) - -#### Biometric Service (FastAPI) - -**Current State:** Already auto-generates docs! - -**Access:** -- Interactive Docs: `http://localhost:8001/docs` -- ReDoc: `http://localhost:8001/redoc` -- OpenAPI JSON: `http://localhost:8001/openapi.json` - -**Enhancement:** Add better descriptions - -```python -# app/main.py -from fastapi import FastAPI - -app = FastAPI( - title="FIVUCSAS Biometric Processor", - description=""" - Biometric processing microservice for face recognition and liveness detection. - - ## Features - * Face embedding extraction (VGG-Face model) - * Face similarity verification - * Liveness detection (Biometric Puzzle - planned) - - ## Models - * DeepFace with VGG-Face backend - * 512-dimensional face embeddings - * Cosine similarity threshold: 0.30 - """, - version="1.0.0", - contact={ - "name": "FIVUCSAS Team", - "email": "contact@fivucsas.com", - }, - license_info={ - "name": "MIT License", - "url": "https://opensource.org/licenses/MIT", - }, -) - -# app/api/endpoints/face.py -from fastapi import APIRouter, UploadFile, File, HTTPException -from app.models.schemas import EnrollResponse, VerifyRequest, VerifyResponse - -router = APIRouter() - -@router.post( - "/enroll", - response_model=EnrollResponse, - summary="Enroll face biometric", - description=""" - Extracts a 512-dimensional face embedding from the provided image. - - The embedding can be stored and used later for face verification. - Supports JPG, PNG image formats. Maximum file size: 10MB. - """, - responses={ - 200: {"description": "Face embedding extracted successfully"}, - 400: {"description": "Invalid image or no face detected"}, - 413: {"description": "File too large"}, - }, - tags=["Face Recognition"] -) -async def enroll_face( - image: UploadFile = File(..., description="Face image file (JPG/PNG)") -): - # Implementation - pass -``` - -**Benefits:** Already implemented! Just needs enhancement. - -### 3.2 Documentation Organization - -#### Folder Structure (DRY-Compliant) - -``` -docs/ -│ -├── README.md # ⭐ NEW: Main navigation index -│ -├── 01-getting-started/ # ⭐ NEW FOLDER -│ ├── README.md # Folder index -│ ├── START_HERE.md # Existing (moved) -│ ├── QUICK_START.md # Existing (moved) -│ ├── HOW_TO_RUN_APPS.md # Existing (moved) -│ └── HOW_TO_RUN_AND_TEST.md # Existing (moved) -│ -├── 02-architecture/ # ⭐ NEW FOLDER -│ ├── README.md # Folder index -│ ├── ARCHITECTURE_ANALYSIS.md # Existing (moved) -│ ├── SYSTEM_DESIGN_ANALYSIS.md # Existing (moved) -│ ├── PROJECT_DESIGN_AUDIT.md # Existing (moved) -│ ├── DESIGN_AUDIT_REPORT.md # Existing (moved) -│ └── diagrams/ # Existing (moved) -│ ├── README.md # ⭐ NEW: Diagram index -│ └── *.png # Existing 35 diagrams -│ -├── 03-development/ # ⭐ NEW FOLDER -│ ├── README.md # Folder index -│ ├── CLAUDE.md # Existing (moved) - Main dev guide -│ ├── KOTLIN_MULTIPLATFORM_GUIDE.md # Existing (moved) -│ ├── FLUTTER_APP_GUIDE.md # Existing (moved) -│ ├── COMPLETE_IMPLEMENTATION_GUIDE.md # Existing (moved) -│ ├── IMPLEMENTATION_ROADMAP.md # Existing (moved) -│ ├── CODE_REVIEW_ACTION_GUIDE.md # Existing (moved) -│ └── REFACTORING_CHECKLIST.md # Existing (moved) -│ -├── 04-api/ # ⭐ NEW FOLDER -│ ├── README.md # ⭐ NEW: API index + links -│ ├── RUNNING_SERVICES_CAPABILITIES.md # Existing (moved) -│ ├── backend-api/ -│ │ └── README.md # ⭐ NEW: Link to Swagger UI -│ └── biometric-service/ -│ └── README.md # ⭐ NEW: Link to FastAPI docs -│ -├── 05-testing/ # ⭐ NEW FOLDER -│ ├── README.md # Folder index -│ ├── TESTING_GUIDE.md # Existing (moved) -│ ├── MOBILE_TESTING_GUIDE.md # Existing (moved) -│ └── BACKEND_TEST_REPORT.md # Existing (moved) -│ -├── 06-deployment/ # ⭐ NEW FOLDER -│ ├── README.md # Folder index -│ ├── START_ALL_SERVICES.md # Existing (moved) -│ └── local-development.md # ⭐ NEW: Consolidated guide -│ -├── 07-status/ # ⭐ NEW FOLDER -│ ├── README.md # Folder index -│ ├── PROJECT_STATUS_NOW.md # Existing (moved) -│ ├── CURRENT_PROJECT_STATUS.md # Existing (moved) -│ ├── IMPLEMENTATION_STATUS.md # Existing (moved) -│ └── FINAL_COMPLETION_REPORT.md # Existing (moved) -│ -└── 99-archive/ # ⭐ NEW FOLDER - └── [Old status files] # Existing (moved) -``` - -**Key Decisions:** -1. **Numbered folders** - Clear hierarchy and reading order -2. **README.md in each folder** - Navigation and context -3. **Reuse 100% of existing docs** - DRY principle -4. **Archive old status files** - Keep history but declutter - -### 3.3 Main README.md Design - -```markdown -# 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:** 65% Complete | **University:** Marmara University | **Department:** Computer Engineering - ---- - -## 🚀 Quick Links - -| I want to... | Go to... | -|-------------|----------| -| **Start using the project** | [Getting Started Guide](01-getting-started/START_HERE.md) | -| **Run the applications** | [How to Run](01-getting-started/HOW_TO_RUN_APPS.md) | -| **Explore the API** | [Backend API](http://localhost:8080/swagger-ui.html) · [Biometric Service](http://localhost:8001/docs) | -| **Understand the architecture** | [Architecture Overview](02-architecture/ARCHITECTURE_ANALYSIS.md) | -| **Develop features** | [Developer Guide](03-development/CLAUDE.md) | -| **Run tests** | [Testing Guide](05-testing/TESTING_GUIDE.md) | -| **Check project status** | [Current Status](07-status/PROJECT_STATUS_NOW.md) | - ---- - -## 📚 Documentation Structure - -### 1️⃣ [Getting Started](01-getting-started/) -New to FIVUCSAS? Start here! -- [START_HERE.md](01-getting-started/START_HERE.md) - First steps -- [QUICK_START.md](01-getting-started/QUICK_START.md) - Quick start guide -- [HOW_TO_RUN_APPS.md](01-getting-started/HOW_TO_RUN_APPS.md) - Running applications -- [HOW_TO_RUN_AND_TEST.md](01-getting-started/HOW_TO_RUN_AND_TEST.md) - Running tests - -### 2️⃣ [Architecture](02-architecture/) -System design and architecture decisions -- [ARCHITECTURE_ANALYSIS.md](02-architecture/ARCHITECTURE_ANALYSIS.md) - Complete architecture analysis -- [SYSTEM_DESIGN_ANALYSIS.md](02-architecture/SYSTEM_DESIGN_ANALYSIS_AND_DECISION.md) - Design decisions -- [Diagrams](02-architecture/diagrams/) - 35+ UML/PlantUML diagrams - -### 3️⃣ [Development](03-development/) -Guides for developers working on FIVUCSAS -- [CLAUDE.md](03-development/CLAUDE.md) - ⭐ **Main developer guide** -- [KOTLIN_MULTIPLATFORM_GUIDE.md](03-development/KOTLIN_MULTIPLATFORM_GUIDE.md) - Mobile app development -- [COMPLETE_IMPLEMENTATION_GUIDE.md](03-development/COMPLETE_IMPLEMENTATION_GUIDE.md) - Implementation details -- [CODE_REVIEW_ACTION_GUIDE.md](03-development/CODE_REVIEW_ACTION_GUIDE.md) - Code review process - -### 4️⃣ [API Documentation](04-api/) -Interactive API documentation (auto-generated) -- **Backend API:** [Swagger UI](http://localhost:8080/swagger-ui.html) (run backend first) -- **Biometric Service:** [FastAPI Docs](http://localhost:8001/docs) (run biometric service first) -- [RUNNING_SERVICES_CAPABILITIES.md](04-api/RUNNING_SERVICES_CAPABILITIES.md) - Service capabilities - -### 5️⃣ [Testing](05-testing/) -Testing guides and reports -- [TESTING_GUIDE.md](05-testing/TESTING_GUIDE.md) - Complete testing guide -- [MOBILE_TESTING_GUIDE.md](05-testing/MOBILE_TESTING_GUIDE.md) - Mobile app testing -- [BACKEND_TEST_REPORT.md](05-testing/BACKEND_TEST_REPORT.md) - Backend test results - -### 6️⃣ [Deployment](06-deployment/) -Deployment and operations guides -- [START_ALL_SERVICES.md](06-deployment/START_ALL_SERVICES.md) - Starting all services -- Local development setup - -### 7️⃣ [Project Status](07-status/) -Current project status and roadmaps -- [PROJECT_STATUS_NOW.md](07-status/PROJECT_STATUS_NOW.md) - ⭐ **Current status** -- [IMPLEMENTATION_STATUS.md](07-status/IMPLEMENTATION_STATUS.md) - Implementation progress - ---- - -## 🏗️ 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│ - └─────────────┘ └────────────────┘ -``` - -See [full architecture documentation](02-architecture/ARCHITECTURE_ANALYSIS.md) - ---- - -## 🛠️ Technology Stack - -| Layer | Technology | Status | -|-------|-----------|--------| -| **Backend Core** | Spring Boot 3.2 (Java 21) | ✅ 78% Complete | -| **ML Service** | FastAPI (Python 3.12) | ✅ 80% Complete | -| **Mobile/Desktop** | Kotlin Multiplatform | ✅ 95% Complete | -| **Database** | H2 (dev), PostgreSQL (prod planned) | ⚠️ Dev only | -| **Cache/Queue** | Redis 7 | ⚠️ Not deployed | -| **Web Frontend** | React 18 | ❌ Not started | - ---- - -## 📊 Project Status - -**Overall Completion:** 65% - -``` -Mobile App: ████████████████████ 95% ✅ -Backend API: ████████████████ 78% ⚠️ -Biometric: ████████████████ 80% ✅ -Documentation: ██████████████████ 90% ✅ -Web Dashboard: ░░░░░░░░░░░░░░░░░░░░ 0% ❌ -Deployment: ░░░░░░░░░░░░░░░░░░░░ 0% ❌ -``` - -See [detailed status](07-status/PROJECT_STATUS_NOW.md) - ---- - -## 🎓 Academic Information - -**Institution:** Marmara University -**Department:** Computer Engineering -**Course:** Engineering Project -**Project Type:** Multi-tenant Biometric SaaS Platform - ---- - -## 📖 Additional Resources - -- **Original Specification:** [PSD.docx](PSD.docx) -- **Project Proposal:** [CSE4297_Project_Proposal.pdf](CSE4297_Project_Proposal.pdf) -- **Diagrams:** [PlantUML Diagrams](02-architecture/diagrams/) - ---- - -## 🤝 Contributing - -This is a university engineering project. For development guidelines, see: -- [Developer Guide (CLAUDE.md)](03-development/CLAUDE.md) -- [Code Review Guide](03-development/CODE_REVIEW_ACTION_GUIDE.md) -- [Refactoring Checklist](03-development/REFACTORING_CHECKLIST.md) - ---- - -**Last Updated:** 2025-11-17 -**Documentation Version:** 1.0 -**Project Version:** 1.0.0-SNAPSHOT -``` - ---- - -## 4. Automation Strategy - -### 4.1 Automated Documentation Generation - -```yaml -# .github/workflows/docs.yml -name: Documentation CI/CD - -on: - push: - branches: [ main, develop ] - pull_request: - branches: [ main, develop ] - -jobs: - validate-docs: - runs-on: ubuntu-latest - name: Validate Documentation - - steps: - - name: Checkout code - uses: actions/checkout@v3 - - - name: Check broken links - uses: lycheeverse/lychee-action@v1 - with: - args: --verbose --no-progress '**/*.md' '**/*.html' - fail: true - - - name: Validate markdown formatting - uses: DavidAnson/markdownlint-cli2-action@v9 - with: - globs: '**/*.md' - - - name: Check documentation coverage - run: | - # Ensure all major features have documentation - ./scripts/check-docs-coverage.sh - - generate-api-docs: - runs-on: ubuntu-latest - name: Generate API Documentation - - steps: - - name: Checkout code - uses: actions/checkout@v3 - - - name: Set up JDK 21 - uses: actions/setup-java@v3 - with: - java-version: '21' - distribution: 'temurin' - - - name: Generate OpenAPI spec (Backend) - run: | - cd identity-core-api - ./gradlew clean build - ./gradlew generateOpenApiDocs - - - name: Set up Python - uses: actions/setup-python@v4 - with: - python-version: '3.12' - - - name: Generate OpenAPI spec (Biometric) - run: | - cd biometric-processor - pip install -r requirements.txt - python scripts/generate_openapi.py - - - name: Commit updated API docs - run: | - git config user.name "Documentation Bot" - git config user.email "bot@fivucsas.com" - git add docs/04-api/ - git diff --quiet && git diff --staged --quiet || git commit -m "docs: Update auto-generated API documentation" - git push - - test-code-examples: - runs-on: ubuntu-latest - name: Test Documentation Code Examples - - steps: - - name: Checkout code - uses: actions/checkout@v3 - - - name: Extract and test Java examples - run: | - # Extract Java code blocks from markdown - ./scripts/extract-java-examples.sh - # Compile extracted examples - ./scripts/test-java-examples.sh - - - name: Extract and test Python examples - run: | - ./scripts/extract-python-examples.sh - ./scripts/test-python-examples.sh - - - name: Extract and test curl examples - run: | - # Start services - docker-compose up -d - # Test curl examples - ./scripts/test-curl-examples.sh -``` - -### 4.2 Documentation Coverage Script - -```bash -#!/bin/bash -# scripts/check-docs-coverage.sh - -# Ensure key features have documentation - -echo "Checking documentation coverage..." - -REQUIRED_DOCS=( - "01-getting-started/START_HERE.md" - "03-development/CLAUDE.md" - "04-api/README.md" - "05-testing/TESTING_GUIDE.md" - "07-status/PROJECT_STATUS_NOW.md" -) - -MISSING=0 - -for doc in "${REQUIRED_DOCS[@]}"; do - if [ ! -f "docs/$doc" ]; then - echo "❌ Missing: $doc" - MISSING=$((MISSING + 1)) - else - echo "✅ Found: $doc" - fi -done - -if [ $MISSING -gt 0 ]; then - echo "❌ Documentation coverage check failed: $MISSING required files missing" - exit 1 -else - echo "✅ Documentation coverage check passed" - exit 0 -fi -``` - ---- - -## 5. Quality Metrics - -### 5.1 Documentation Quality Checklist - -```markdown -## Documentation Quality Standards - -### Completeness -- [ ] All public APIs documented -- [ ] All major features have user guides -- [ ] Architecture decisions documented (ADR) -- [ ] Setup instructions complete -- [ ] Troubleshooting section exists - -### Accuracy -- [ ] API docs auto-generated from code (100% accurate) -- [ ] Code examples tested in CI/CD -- [ ] Screenshots up-to-date -- [ ] Version numbers correct - -### Discoverability -- [ ] Clear navigation in README.md -- [ ] Search functionality (if using doc site) -- [ ] Cross-references between docs -- [ ] Table of contents in long documents - -### Maintainability -- [ ] Single source of truth (code annotations) -- [ ] Automated generation where possible -- [ ] CI/CD validates documentation -- [ ] Clear ownership/maintenance responsibility - -### Accessibility -- [ ] Clear, simple language -- [ ] Proper heading hierarchy -- [ ] Alt text for images -- [ ] Code examples include explanations -``` - -### 5.2 Documentation Metrics Dashboard - -```markdown -# Documentation Metrics - -| Metric | Target | Current | Status | -|--------|--------|---------|--------| -| **API Endpoint Coverage** | 100% | 100% | ✅ Auto-generated | -| **Broken Links** | 0 | 0 | ✅ CI/CD validated | -| **Code Examples Working** | 100% | 100% | ✅ CI/CD tested | -| **Documentation Updated** | < 1 week | 2 days | ✅ Recently updated | -| **User Guide Coverage** | 80% | 85% | ✅ Good coverage | -``` - ---- - -## 6. Implementation Phases - -### Phase 1: Foundation (1-2 hours) - CRITICAL -1. Add SpringDoc OpenAPI dependency (15 min) -2. Configure OpenAPI (30 min) -3. Add annotations to existing controllers (45 min) - -**Deliverable:** Auto-generated API documentation at `/swagger-ui.html` - -### Phase 2: Organization (1-2 hours) - HIGH -1. Create folder structure (30 min) -2. Move existing files to appropriate folders (45 min) -3. Create README.md in each folder (30 min) -4. Update main README.md with navigation (15 min) - -**Deliverable:** Organized, navigable documentation structure - -### Phase 3: Enhancement (1 hour) - MEDIUM -1. Improve FastAPI documentation (30 min) -2. Add missing descriptions to endpoints (30 min) - -**Deliverable:** Better API documentation descriptions - -### Phase 4: Automation (1-2 hours) - MEDIUM -1. Create documentation CI/CD workflow (1 hour) -2. Add link checking (30 min) -3. Add documentation coverage check (30 min) - -**Deliverable:** Automated documentation validation - -**Total Time: 4-6 hours** (vs. 18-26 hours in original plan) - ---- - -## 7. Success Criteria - -### Functional Requirements -✅ All APIs have interactive documentation -✅ Navigation structure is clear and logical -✅ Setup instructions work end-to-end -✅ Code examples are tested and working -✅ Architecture is fully documented with diagrams - -### Non-Functional Requirements -✅ API docs auto-generated (zero maintenance) -✅ CI/CD validates documentation quality -✅ No broken links -✅ DRY principle followed (no duplication) -✅ YAGNI principle followed (document what exists) -✅ KISS principle followed (simple, maintainable) - -### Quality Metrics -- API Coverage: 100% -- Documentation Accuracy: 100% (auto-generated) -- Maintenance Effort: <1 hour/month -- User Satisfaction: Measurable through feedback - ---- - -## 8. Maintenance Plan - -### 8.1 Automated Maintenance -``` -API Documentation: Auto-generated on every build (zero effort) -Link Validation: Automated in CI/CD (zero effort) -Code Examples: Tested in CI/CD (zero effort) -``` - -### 8.2 Manual Maintenance -``` -User Guides: Update when UI changes (quarterly review) -Architecture Docs: Update on major architectural changes -Deployment Guides: Update when deployment process changes -``` - -### 8.3 Ownership -``` -API Docs: Backend developers (auto-generated, minimal maintenance) -User Guides: Product owner (review quarterly) -Architecture: Tech lead (update on major changes) -Operations: DevOps team (update on process changes) -``` - ---- - -## 9. Design Approval Checklist - -### SOLID Principles -- [x] **Single Responsibility** - Each documentation folder has single purpose -- [x] **Open/Closed** - Auto-generated docs extend without modification -- [x] **Liskov Substitution** - N/A (documentation) -- [x] **Interface Segregation** - Separate docs by audience -- [x] **Dependency Inversion** - Docs generated from abstractions (interfaces/controllers) - -### DRY (Don't Repeat Yourself) -- [x] No duplication of existing documentation (reuse 100%) -- [x] Single source of truth (code annotations → documentation) -- [x] No manual YAML files (auto-generated from code) - -### KISS (Keep It Simple, Stupid) -- [x] Simple folder structure -- [x] No complex documentation site (unless needed later) -- [x] Standard markdown format -- [x] Minimal setup (add one dependency) - -### YAGNI (You Ain't Gonna Need It) -- [x] Document only what exists -- [x] No hypothetical deployment guides -- [x] No SDK documentation (SDKs don't exist) -- [x] No webhook documentation (not implemented) - -### Additional Principles -- [x] Automation over manual work -- [x] Quality assurance (CI/CD validation) -- [x] Clear ownership and maintenance plan -- [x] Measurable success criteria - ---- - -## 10. Conclusion - -This professional design provides: - -✅ **77% time savings** (4-6 hours vs. 18-26 hours) -✅ **100% DRY compliance** (zero duplication) -✅ **100% YAGNI compliance** (document reality, not plans) -✅ **Automated API documentation** (always accurate) -✅ **CI/CD validation** (quality assurance) -✅ **Clear maintenance plan** (sustainable long-term) - -**Next Step:** Proceed to `DOCS_MODULE_IMPLEMENTATION_PLAN.md` for detailed implementation instructions. - ---- - -**Document Status:** ✅ Design Complete - Ready for Implementation -**Review Status:** ✅ Approved - Follows SOLID, DRY, KISS, YAGNI -**Implementation Status:** ⏳ Pending - Awaiting execution diff --git a/archive/2026-04-16/IDENTITY_CORE_API_ANALYSIS.md b/archive/2026-04-16/IDENTITY_CORE_API_ANALYSIS.md deleted file mode 100644 index 836613f..0000000 --- a/archive/2026-04-16/IDENTITY_CORE_API_ANALYSIS.md +++ /dev/null @@ -1,454 +0,0 @@ -# Identity Core API - Security Analysis & Architectural Decision - -**Date:** December 28, 2025 -**Author:** Claude Code Analysis -**Status:** Critical Review for January 7, 2026 Defense - ---- - -## Executive Summary - -This document analyzes whether `identity-core-api` (Spring Boot) is necessary alongside `biometric-processor` (FastAPI), examining security implementations, gaps, and providing recommendations. - -**Verdict:** Keep both services, but fix critical security gaps before production. - ---- - -## 1. Architecture Overview - -### Current Architecture -``` -┌─────────────┐ ┌─────────────────────┐ ┌─────────────────────┐ -│ Clients │────>│ identity-core-api │────>│ biometric-processor │ -│ (Web/App) │ │ (Spring Boot) │ │ (FastAPI) │ -└─────────────┘ │ :8080 │ │ :8001 │ - └──────────┬──────────┘ └──────────┬───────────┘ - │ │ - └───────────┬───────────────┘ - │ - ┌──────▼──────┐ - │ PostgreSQL │ - │ + pgvector │ - └─────────────┘ -``` - -### Service Responsibilities - -| Service | Responsibility | Completion | -|---------|---------------|------------| -| **identity-core-api** | Authentication, Authorization, User Management | 68% | -| **biometric-processor** | Face Recognition, Liveness Detection, ML Processing | 100% | - ---- - -## 2. identity-core-api Security Analysis - -### 2.1 What's Implemented (Good) - -#### JWT Authentication -- **Location:** `src/main/java/com/fivucsas/identity/security/JwtService.java` -- **Algorithm:** HMAC-SHA (HS512) -- **Access Token Expiry:** 24 hours -- **Refresh Token Expiry:** 7 days -- **Secret:** Base64-encoded, 256+ bits - -#### Password Security -- **Location:** `src/main/java/com/fivucsas/identity/infrastructure/adapter/PasswordEncoderAdapter.java` -- **Algorithm:** BCrypt (Spring Security default strength) -- **Storage:** Hashed passwords only, never plaintext - -#### Refresh Token Management -- **Location:** `src/main/java/com/fivucsas/identity/service/RefreshTokenService.java` -- **Features:** - - Database-backed token storage - - Token rotation on refresh - - Revocation tracking - - IP address and User-Agent logging - - Automatic cleanup of expired tokens - -#### Authentication Filter -- **Location:** `src/main/java/com/fivucsas/identity/security/JwtAuthenticationFilter.java` -- **Type:** OncePerRequestFilter -- **Flow:** Extract Bearer token → Validate → Load user → Set SecurityContext - -### 2.2 Critical Security Gaps - -#### GAP 1: No User Data Isolation (CRITICAL) -```java -// CURRENT: Any authenticated user can access ANY user's data -@GetMapping("/{id}") -public ResponseEntity getUserById(@PathVariable UUID id) { - return userService.findById(id) // NO ownership check! - .map(ResponseEntity::ok) - .orElse(ResponseEntity.notFound().build()); -} -``` - -**Impact:** User A can view/edit/delete User B's profile and biometric data. - -#### GAP 2: No RBAC Implementation (CRITICAL) -```java -// CURRENT: All users get ROLE_USER -List authorities = Collections.singletonList( - new SimpleGrantedAuthority("ROLE_USER") // Hardcoded! -); -// TODO comments throughout codebase indicate RBAC not implemented -``` - -**Impact:** No admin vs user distinction. All authenticated users have same permissions. - -#### GAP 3: No Multi-Tenancy Enforcement (HIGH) -- `X-Tenant-ID` header is configured in CORS but never processed -- No tenant filtering in database queries -- All data shared across what should be isolated tenants - -**Impact:** In a multi-tenant deployment, tenants can see each other's data. - -#### GAP 4: No Service-to-Service Authentication (MEDIUM) -```java -// BiometricServiceAdapter calls FastAPI with NO authentication -WebClient.builder() - .baseUrl("http://localhost:8001") // No API key, no JWT - .build(); -``` - -**Impact:** Anyone who can reach port 8001 can call biometric endpoints directly. - -#### GAP 5: Biometric Endpoint Authorization (CRITICAL) -```java -// CURRENT: Any authenticated user can enroll biometrics for ANY user -@PostMapping("/enroll/{userId}") -public ResponseEntity enrollBiometric(@PathVariable UUID userId, ...) { - // NO check that authenticated user == userId -} -``` - -**Impact:** User A can enroll fake biometrics for User B. - -### 2.3 Security Configuration Summary - -| Feature | Status | Risk Level | -|---------|--------|------------| -| JWT Token Generation | ✅ Implemented | Low | -| JWT Token Validation | ✅ Implemented | Low | -| Password Hashing (BCrypt) | ✅ Implemented | Low | -| Refresh Token Storage | ✅ Implemented | Low | -| Token Revocation | ✅ Implemented | Low | -| CSRF Protection | ✅ Disabled (stateless API) | Low | -| CORS Configuration | ✅ Configured | Low | -| **User Data Isolation** | ❌ **NOT IMPLEMENTED** | **CRITICAL** | -| **RBAC** | ❌ **NOT IMPLEMENTED** | **CRITICAL** | -| **Multi-Tenancy** | ❌ **NOT IMPLEMENTED** | **HIGH** | -| **Service-to-Service Auth** | ❌ **NOT IMPLEMENTED** | **MEDIUM** | - ---- - -## 3. biometric-processor Security Analysis - -### 3.1 What's Implemented (Good) - -#### API Key Authentication -- **Location:** `app/api/middleware/api_key_auth.py` -- **Method:** X-API-Key header -- **Storage:** SHA-256 hashed keys (plaintext never stored) -- **Features:** Key prefix tracking, expiration, soft delete - -#### Security Headers (OWASP Compliant) -- **Location:** `app/api/middleware/security_headers.py` -- **Headers:** - - `X-Content-Type-Options: nosniff` - - `X-Frame-Options: DENY` - - `X-XSS-Protection: 1; mode=block` - - `Strict-Transport-Security` (HTTPS) - - `Content-Security-Policy` - - `Referrer-Policy` - -#### Rate Limiting (Tier-Based) -- **Location:** `app/api/middleware/rate_limit.py` -- **Tiers:** Free (30/min), Standard (60/min), Premium (300/min), Unlimited -- **Per-Endpoint Limits:** - - Enrollment: 10 req/min - - Verification: 30 req/min - - Search: 20 req/min - - Batch: 5 req/min - -#### Input Validation & Sanitization -- **Location:** `app/api/middleware/security.py` -- **Protection Against:** - - SQL Injection patterns - - XSS patterns - - Path traversal attacks - -#### CORS Configuration -- **Location:** `app/main.py` -- **Rule:** No wildcards allowed in production -- **Validation:** Runtime check prevents misconfiguration - -### 3.2 Security Gaps - -#### GAP 1: No User Model -- No dedicated Users table -- User IDs are just strings passed in requests -- No user authentication (relies on API keys) - -#### GAP 2: Weak Tenant Isolation -- `tenant_id` exists in models but not enforced -- Developers must manually check tenant ownership -- No automatic tenant scoping in queries - -#### GAP 3: Admin Routes Unprotected -- **Location:** `app/api/routes/admin.py` -- Admin endpoints exist but lack authorization decorators - -### 3.3 Security Configuration Summary - -| Feature | Status | Risk Level | -|---------|--------|------------| -| API Key Authentication | ✅ Implemented | Low | -| SHA-256 Key Hashing | ✅ Implemented | Low | -| Security Headers | ✅ Implemented | Low | -| Rate Limiting | ✅ Implemented | Low | -| Input Validation | ✅ Implemented | Low | -| CORS (No Wildcards) | ✅ Implemented | Low | -| Path Traversal Protection | ✅ Implemented | Low | -| **User Management** | ❌ **NO USER MODEL** | **HIGH** | -| **Tenant Isolation** | ⚠️ **WEAK** | **MEDIUM** | -| **Admin Authorization** | ⚠️ **INCOMPLETE** | **MEDIUM** | - ---- - -## 4. Comparative Analysis - -### Security Features Comparison - -| Feature | identity-core-api | biometric-processor | -|---------|-------------------|---------------------| -| User Authentication | ✅ JWT | ✅ API Key | -| Password Management | ✅ BCrypt | ❌ None | -| Token Refresh/Revocation | ✅ DB-backed | ❌ None | -| Security Headers | ⚠️ Basic | ✅ OWASP | -| Rate Limiting | ❌ None | ✅ Tier-based | -| Input Validation | ⚠️ JPA only | ✅ Middleware | -| User Data Model | ✅ Full User entity | ❌ No user model | -| User Isolation | ❌ Not enforced | N/A | -| RBAC | ❌ Not implemented | ❌ Not implemented | -| Multi-Tenancy | ❌ Not implemented | ⚠️ Partial | - -### What Each Service Provides Uniquely - -**identity-core-api provides:** -- User registration and login flows -- Password hashing and verification -- JWT token lifecycle management -- Refresh token rotation and revocation -- User entity with profile data - -**biometric-processor provides:** -- OWASP-compliant security headers -- Tier-based rate limiting -- SQL injection/XSS protection middleware -- API key management system -- All biometric ML functionality - ---- - -## 5. Architectural Decision - -### Question: Should We Remove identity-core-api? - -### Answer: NO - Keep Both Services - -**Rationale:** - -1. **Separation of Concerns** - - Authentication/Identity is a distinct domain from Biometric Processing - - Different scaling requirements (auth is lightweight, ML is heavy) - -2. **Technology Fit** - - Spring Security is mature for enterprise authentication - - FastAPI is optimal for ML/async processing - -3. **Migration Risk** - - Moving auth to FastAPI requires 2-3 days minimum - - Risk of introducing bugs before defense deadline - -4. **Academic Value** - - Demonstrates microservices architecture - - Shows polyglot programming (Java + Python) - -### Alternative Considered: Merge into biometric-processor - -**Would require adding to FastAPI:** -- User model and migrations -- JWT token generation/validation -- Password hashing (bcrypt) -- Refresh token management -- Login/Register endpoints - -**Estimated effort:** 2-3 days -**Risk before deadline:** HIGH - ---- - -## 6. TODO List - Security Fixes Required - -### Priority 1: CRITICAL (Before Defense) - -#### TODO 1.1: Add User Ownership Checks in identity-core-api -**Location:** All controller methods in `UserController.java`, `BiometricController.java` -**Effort:** 2-3 hours - -```java -// Add to each endpoint that accesses user data -private void validateUserOwnership(UUID requestedUserId, Authentication auth) { - User currentUser = (User) auth.getPrincipal(); - if (!currentUser.getId().equals(requestedUserId) && - !hasRole(auth, "ADMIN")) { - throw new ForbiddenException("Cannot access other user's data"); - } -} -``` - -**Files to modify:** -- [ ] `UserController.java` - getUserById, updateUser, deleteUser -- [ ] `BiometricController.java` - enrollBiometric, verifyBiometric -- [ ] `StatisticsController.java` - restrict to admin only - -#### TODO 1.2: Implement Basic RBAC -**Location:** `CustomUserDetailsService.java`, database schema -**Effort:** 4-6 hours - -```sql --- Add to Flyway migration -CREATE TABLE roles ( - id UUID PRIMARY KEY, - name VARCHAR(50) UNIQUE NOT NULL -); - -CREATE TABLE user_roles ( - user_id UUID REFERENCES users(id), - role_id UUID REFERENCES roles(id), - PRIMARY KEY (user_id, role_id) -); - -INSERT INTO roles (id, name) VALUES - (gen_random_uuid(), 'ROLE_USER'), - (gen_random_uuid(), 'ROLE_ADMIN'), - (gen_random_uuid(), 'ROLE_TENANT_ADMIN'); -``` - -**Files to modify:** -- [ ] Add `V7__add_roles_table.sql` migration -- [ ] Create `Role.java` entity -- [ ] Update `User.java` with roles relationship -- [ ] Update `CustomUserDetailsService.java` to load roles -- [ ] Add `@PreAuthorize` annotations to controllers - -#### TODO 1.3: Protect Admin Routes in biometric-processor -**Location:** `app/api/routes/admin.py` -**Effort:** 1 hour - -```python -# Add to all admin endpoints -@router.get("/stats", dependencies=[Depends(RequireAPIKey(required_scope="admin"))]) -async def get_stats(): - ... -``` - -### Priority 2: HIGH (Before Production) - -#### TODO 2.1: Implement Multi-Tenancy in identity-core-api -**Effort:** 1-2 days - -- [ ] Add `tenant_id` column to users table -- [ ] Create `TenantContext` thread-local holder -- [ ] Add tenant filter to all repository queries -- [ ] Extract tenant from JWT claims or header - -#### TODO 2.2: Service-to-Service Authentication -**Effort:** 4-6 hours - -- [ ] Generate API key for identity-core-api -- [ ] Add X-API-Key header to BiometricServiceAdapter -- [ ] Validate API key in biometric-processor for internal calls - -#### TODO 2.3: Enforce Tenant Isolation in biometric-processor -**Effort:** 4-6 hours - -- [ ] Create `TenantMiddleware` to extract tenant from API key -- [ ] Add automatic tenant filtering to repositories -- [ ] Validate tenant ownership on all data access - -### Priority 3: MEDIUM (Future Enhancement) - -#### TODO 3.1: Add Rate Limiting to identity-core-api -- [ ] Add Spring Boot rate limiting (bucket4j or resilience4j) -- [ ] Configure per-endpoint limits - -#### TODO 3.2: Add Security Headers to identity-core-api -- [ ] Add OWASP security headers via Spring Security - -#### TODO 3.3: Implement Audit Logging -- [ ] Replace SLF4J audit with database-backed audit log -- [ ] Track all security-relevant events - -#### TODO 3.4: Add Email Verification -- [ ] Implement email sending service -- [ ] Add verification token flow - -#### TODO 3.5: Add Password Reset -- [ ] Implement password reset token -- [ ] Add reset email flow - ---- - -## 7. Summary - -### Current State -- **identity-core-api:** Has auth infrastructure but critical security gaps -- **biometric-processor:** Has excellent middleware security but no user management - -### Recommendation -1. **Keep both services** for defense -2. **Fix critical gaps** (user isolation, basic RBAC) - 1 day effort -3. **Document architecture** decision for presentation -4. **Plan post-defense** improvements for production readiness - -### Risk Assessment - -| Risk | Likelihood | Impact | Mitigation | -|------|------------|--------|------------| -| User data breach | HIGH (current) | CRITICAL | Implement TODO 1.1 | -| Privilege escalation | HIGH (current) | HIGH | Implement TODO 1.2 | -| Cross-tenant data leak | MEDIUM | HIGH | Implement TODO 2.1 | -| Direct API bypass | LOW | MEDIUM | Implement TODO 2.2 | - ---- - -## 8. Files Examined - -### identity-core-api (47 files) -- `src/main/java/com/fivucsas/identity/config/SecurityConfig.java` -- `src/main/java/com/fivucsas/identity/security/JwtService.java` -- `src/main/java/com/fivucsas/identity/security/JwtAuthenticationFilter.java` -- `src/main/java/com/fivucsas/identity/security/CustomUserDetailsService.java` -- `src/main/java/com/fivucsas/identity/service/RefreshTokenService.java` -- `src/main/java/com/fivucsas/identity/controller/UserController.java` -- `src/main/java/com/fivucsas/identity/controller/BiometricController.java` -- `src/main/java/com/fivucsas/identity/infrastructure/adapter/BiometricServiceAdapter.java` -- And 39 more... - -### biometric-processor (Key files) -- `app/api/middleware/api_key_auth.py` -- `app/api/middleware/security_headers.py` -- `app/api/middleware/rate_limit.py` -- `app/api/middleware/security.py` -- `app/core/config.py` -- `app/infrastructure/database/models.py` -- `app/api/routes/admin.py` - ---- - -**Document Version:** 1.0 -**Last Updated:** December 28, 2025 -**Next Review:** After January 7, 2026 Defense diff --git a/archive/2026-04-16/PGVECTOR_SETUP.md b/archive/2026-04-16/PGVECTOR_SETUP.md deleted file mode 100644 index b69fb6a..0000000 --- a/archive/2026-04-16/PGVECTOR_SETUP.md +++ /dev/null @@ -1,480 +0,0 @@ -# PostgreSQL with pgvector Setup Guide - -## Overview - -This guide explains how to set up and use PostgreSQL with the pgvector extension for efficient face embedding storage and similarity search in the FIVUCSAS system. - -## Architecture - -The system uses PostgreSQL with pgvector for production-grade face embedding storage: - -- **Database**: PostgreSQL 16 with pgvector extension -- **Embedding Storage**: `biometric_data` table with vector column -- **Similarity Search**: Cosine distance using pgvector operators -- **Indexing**: HNSW or IVFFlat for approximate nearest neighbor search -- **Multi-Tenancy**: Tenant isolation via `tenant_id` column - -## Components Modified - -### 1. Biometric Processor (Python/FastAPI) - -#### New Repository Implementation -- **File**: `biometric-processor/app/infrastructure/persistence/repositories/pgvector_embedding_repository.py` -- **Purpose**: Production-ready PostgreSQL repository with pgvector support -- **Features**: - - Async operations using asyncpg - - Connection pooling (configurable size) - - Vector similarity search (cosine distance) - - Multi-tenancy support - - UPSERT logic for embeddings - -#### Configuration Updates -- **File**: `biometric-processor/app/core/config.py` -- **New Settings**: - - `DATABASE_URL`: PostgreSQL connection string - - `DATABASE_POOL_MIN_SIZE`: Minimum connections (default: 10) - - `DATABASE_POOL_MAX_SIZE`: Maximum connections (default: 20) - - `USE_PGVECTOR`: Toggle between pgvector and in-memory (default: False) - - `EMBEDDING_DIMENSION`: Vector dimension (FaceNet: 512, VGG-Face: 2622) - -#### Dependency Injection -- **File**: `biometric-processor/app/core/container.py` -- **Update**: `get_embedding_repository()` now returns either: - - `PgVectorEmbeddingRepository` if `USE_PGVECTOR=True` - - `InMemoryEmbeddingRepository` if `USE_PGVECTOR=False` - -#### Dependencies -- **File**: `biometric-processor/requirements.txt` -- **Added**: - - `asyncpg>=0.29.0` - PostgreSQL async driver - - `pgvector>=0.2.4` - Python client for pgvector - -### 2. Identity Core API (Java/Spring Boot) - -#### Database Migration -- **File**: `identity-core-api/src/main/resources/db/migration/V4__create_biometric_tables.sql` -- **Updates**: - - Changed `embedding vector(2622)` to `embedding vector` (flexible dimension) - - Added `embedding_dimension INTEGER` column to track vector size - - Added unique constraint on `(user_id, tenant_id, biometric_type)` - - Updated comments to reflect multi-model support - -### 3. Docker Compose - -#### PostgreSQL Service -- **Image**: `pgvector/pgvector:pg16` -- **Volume Mount**: `./docs/sql/init:/docker-entrypoint-initdb.d` -- **Auto-initialization**: Runs all `.sql` files in init directory on first start - -#### Biometric Processor Service -- **New Environment Variables**: - ```yaml - DATABASE_URL: postgresql://postgres:postgres_dev_password@postgres:5432/identity_core_db - DATABASE_POOL_MIN_SIZE: 10 - DATABASE_POOL_MAX_SIZE: 20 - USE_PGVECTOR: "False" # Set to "True" to enable - EMBEDDING_DIMENSION: 512 - ``` -- **Dependencies**: Now depends on PostgreSQL service health check - -### 4. Database Initialization Scripts - -#### init.sql -- **File**: `docs/sql/init/init.sql` -- **Purpose**: Basic database setup -- **Actions**: - - Creates pgvector extension - - Creates uuid-ossp extension - - Sets timezone to UTC - -#### 02_pgvector_setup.sql -- **File**: `docs/sql/init/02_pgvector_setup.sql` (NEW) -- **Purpose**: pgvector-specific setup and utilities -- **Features**: - - Helper function: `check_embedding_similarity()` - Compare two user embeddings - - Helper function: `find_similar_faces()` - Test 1:N identification - - View: `active_face_embeddings` - Convenient access to active embeddings - - View: `biometric_statistics` - Monitoring statistics by tenant/model - - Additional indexes for common query patterns - -## Usage - -### Development Mode (In-Memory Repository) - -By default, the system uses in-memory storage for development: - -```bash -# In docker-compose.yml or .env -USE_PGVECTOR=False -``` - -Features: -- Fast startup -- No database dependency -- Data lost on restart -- Suitable for testing and development - -### Production Mode (pgvector Repository) - -Enable PostgreSQL storage for production: - -```bash -# In docker-compose.yml or .env -USE_PGVECTOR=True -DATABASE_URL=postgresql://postgres:password@postgres:5432/identity_core_db -EMBEDDING_DIMENSION=512 # Match your face recognition model -``` - -Features: -- Persistent storage -- Scalable to millions of faces -- Sub-second similarity search with indexes -- Multi-tenant support -- ACID compliance - -## Face Recognition Models Support - -The system supports multiple face recognition models with different embedding dimensions: - -| Model | Dimension | Configuration | -|-------|-----------|---------------| -| FaceNet | 512 | `EMBEDDING_DIMENSION=512` | -| Facenet512 | 512 | `EMBEDDING_DIMENSION=512` | -| VGG-Face | 2622 | `EMBEDDING_DIMENSION=2622` | -| ArcFace | 512 | `EMBEDDING_DIMENSION=512` | -| OpenFace | 128 | `EMBEDDING_DIMENSION=128` | - -**Important**: The `EMBEDDING_DIMENSION` must match your chosen `FACE_RECOGNITION_MODEL`. - -## Vector Similarity Search - -### Distance Metrics - -pgvector supports multiple distance metrics. This implementation uses **cosine distance**: - -- **Operator**: `<=>` -- **Range**: 0.0 (identical) to 1.0 (opposite) -- **Formula**: `1 - cosine_similarity` -- **Best for**: Face embeddings (normalized vectors) - -### Indexing Strategies - -Two index types are available for approximate nearest neighbor search: - -#### 1. IVFFlat (Default in V4 migration) -```sql -CREATE INDEX idx_biometric_embedding_ivfflat - ON biometric_data - USING ivfflat (embedding vector_cosine_ops) - WITH (lists = 100); -``` - -**Characteristics**: -- Faster index build time -- Lower memory usage -- Good recall with proper `lists` parameter -- Recommended for: 100K - 1M embeddings - -**Tuning**: -- `lists`: Typically `sqrt(total_rows)` to `4 * sqrt(total_rows)` -- More lists = faster search, slower build - -#### 2. HNSW (Alternative, commented in migration) -```sql -CREATE INDEX idx_biometric_embedding_hnsw - ON biometric_data - USING hnsw (embedding vector_cosine_ops) - WITH (m = 16, ef_construction = 64); -``` - -**Characteristics**: -- Better recall than IVFFlat -- Higher memory usage -- More consistent performance -- Recommended for: High-accuracy requirements - -**Tuning**: -- `m`: Higher = better recall, more memory (default: 16) -- `ef_construction`: Higher = better index quality, slower build (default: 64) - -### Query Performance - -Expected query performance (approximate): - -| Records | IVFFlat | HNSW | Notes | -|---------|---------|------|-------| -| 10K | <10ms | <5ms | Linear scan still fast | -| 100K | 10-50ms | 5-20ms | Indexes recommended | -| 1M | 50-200ms | 20-100ms | Indexes required | -| 10M+ | 100-500ms | 50-200ms | Consider partitioning | - -## API Examples - -### Save Embedding - -```python -from app.core.container import get_embedding_repository -import numpy as np - -repository = get_embedding_repository() - -# Save face embedding -await repository.save( - user_id="550e8400-e29b-41d4-a716-446655440000", - embedding=np.random.rand(512), # Your face embedding - quality_score=85.5, - tenant_id="123e4567-e89b-12d3-a456-426614174000" -) -``` - -### Find by User ID (1:1 Verification) - -```python -# Retrieve user's embedding -embedding = await repository.find_by_user_id( - user_id="550e8400-e29b-41d4-a716-446655440000", - tenant_id="123e4567-e89b-12d3-a456-426614174000" -) - -if embedding is not None: - # Compare with new image embedding - distance = calculate_cosine_distance(embedding, new_embedding) - is_match = distance < 0.6 # Threshold -``` - -### Find Similar (1:N Identification) - -```python -# Search for similar faces -matches = await repository.find_similar( - embedding=query_embedding, - threshold=0.6, # Maximum cosine distance - limit=5, # Top 5 matches - tenant_id="123e4567-e89b-12d3-a456-426614174000" -) - -for user_id, distance in matches: - similarity = 1.0 - distance - print(f"User: {user_id}, Similarity: {similarity:.2%}") -``` - -### Delete Embedding - -```python -# Soft delete (sets deleted_at timestamp) -deleted = await repository.delete( - user_id="550e8400-e29b-41d4-a716-446655440000", - tenant_id="123e4567-e89b-12d3-a456-426614174000" -) -``` - -## Database Utilities - -### Check Embedding Similarity (SQL) - -```sql --- Compare two users' face embeddings -SELECT * FROM check_embedding_similarity( - '550e8400-e29b-41d4-a716-446655440000'::UUID, -- user1 - '6ba7b810-9dad-11d1-80b4-00c04fd430c8'::UUID, -- user2 - '123e4567-e89b-12d3-a456-426614174000'::UUID -- tenant (optional) -); -``` - -### Find Similar Faces (SQL) - -```sql --- Search for similar embeddings -SELECT * FROM find_similar_faces( - '[0.1, 0.2, ..., 0.5]'::vector, -- query embedding - 0.6, -- threshold - 5, -- limit - '123e4567-e89b-12d3-a456-426614174000'::UUID -- tenant (optional) -); -``` - -### View Statistics - -```sql --- Check biometric data statistics by tenant -SELECT * FROM biometric_statistics; - --- Count total active embeddings -SELECT COUNT(*) FROM active_face_embeddings; - --- Average quality by model -SELECT - embedding_model, - AVG(quality_score) as avg_quality, - COUNT(*) as total -FROM active_face_embeddings -GROUP BY embedding_model; -``` - -## Migration Guide - -### From In-Memory to pgvector - -1. **Update configuration**: - ```bash - USE_PGVECTOR=True - EMBEDDING_DIMENSION=512 # Match your model - ``` - -2. **Restart services**: - ```bash - docker-compose down - docker-compose up -d - ``` - -3. **Verify connection**: - ```bash - docker-compose logs biometric-processor | grep "pgvector" - # Should see: "Creating embedding repository (pgvector)" - ``` - -4. **Re-enroll faces**: Existing in-memory data is lost; users must re-enroll. - -### Between Face Recognition Models - -If changing models (e.g., VGG-Face → FaceNet): - -1. **Update configuration**: - ```bash - FACE_RECOGNITION_MODEL=Facenet512 - EMBEDDING_DIMENSION=512 # Must match model - ``` - -2. **Migration strategy** (choose one): - - **Option A**: Soft delete old embeddings, re-enroll all users - - **Option B**: Keep both models temporarily, migrate gradually - - **Option C**: Extract new embeddings from stored images (if available) - -3. **Update database** (if needed): - ```sql - -- Mark old embeddings as inactive - UPDATE biometric_data - SET is_active = FALSE - WHERE embedding_model = 'VGG-Face'; - ``` - -## Performance Tuning - -### Connection Pooling - -Adjust based on your workload: - -```bash -# For high concurrency (many simultaneous users) -DATABASE_POOL_MIN_SIZE=20 -DATABASE_POOL_MAX_SIZE=50 - -# For low concurrency (fewer users, save resources) -DATABASE_POOL_MIN_SIZE=5 -DATABASE_POOL_MAX_SIZE=10 -``` - -### Index Optimization - -Monitor and rebuild indexes periodically: - -```sql --- Check index usage -SELECT schemaname, tablename, indexname, idx_scan -FROM pg_stat_user_indexes -WHERE tablename = 'biometric_data'; - --- Rebuild index if needed (after bulk inserts) -REINDEX INDEX CONCURRENTLY idx_biometric_embedding_ivfflat; -``` - -### Query Optimization - -```sql --- Analyze table for query planner -ANALYZE biometric_data; - --- Check query plan -EXPLAIN ANALYZE -SELECT user_id, embedding <=> '[...]'::vector AS distance -FROM biometric_data -WHERE tenant_id = '...' - AND is_active = TRUE - AND deleted_at IS NULL -ORDER BY distance -LIMIT 5; -``` - -## Monitoring - -### Health Check - -```python -repository = get_embedding_repository() -is_healthy = await repository.health_check() -``` - -### Metrics to Monitor - -1. **Embedding count**: `SELECT COUNT(*) FROM active_face_embeddings` -2. **Query latency**: Monitor p50, p95, p99 search times -3. **Connection pool**: Watch for pool exhaustion -4. **Index usage**: Ensure vector index is being used -5. **Storage size**: `SELECT pg_size_pretty(pg_total_relation_size('biometric_data'))` - -## Troubleshooting - -### "pgvector extension not found" - -```bash -# Ensure using pgvector-enabled PostgreSQL image -docker-compose down -docker-compose pull postgres -docker-compose up -d postgres -``` - -### "Embedding dimension mismatch" - -- Ensure `EMBEDDING_DIMENSION` matches your `FACE_RECOGNITION_MODEL` -- Check application logs for actual embedding size -- Verify database column can store the dimension - -### Slow similarity search - -1. Check if index exists: - ```sql - SELECT indexname FROM pg_indexes - WHERE tablename = 'biometric_data' AND indexname LIKE '%embedding%'; - ``` - -2. Ensure index is being used: - ```sql - EXPLAIN SELECT ... FROM biometric_data WHERE embedding <=> ... - -- Should show "Index Scan using idx_biometric_embedding_..." - ``` - -3. Rebuild index if needed: - ```sql - REINDEX INDEX CONCURRENTLY idx_biometric_embedding_ivfflat; - ``` - -### Connection pool exhausted - -- Increase `DATABASE_POOL_MAX_SIZE` -- Check for connection leaks (unclosed connections) -- Monitor concurrent requests - -## Security Considerations - -1. **Encryption at rest**: Consider PostgreSQL TDE for sensitive biometric data -2. **Access control**: Use separate database users with minimal permissions -3. **Audit logging**: Enable PostgreSQL audit log for compliance -4. **Network security**: Use SSL/TLS for database connections in production -5. **Backup**: Regular backups of biometric_data table - -## References - -- [pgvector Documentation](https://github.com/pgvector/pgvector) -- [asyncpg Documentation](https://magicstack.github.io/asyncpg/) -- [PostgreSQL Performance Tuning](https://wiki.postgresql.org/wiki/Performance_Optimization) -- [Vector Similarity Search Best Practices](https://github.com/pgvector/pgvector#performance) diff --git a/archive/2026-04-16/PLANTUML_DIAGRAMS.md b/archive/2026-04-16/PLANTUML_DIAGRAMS.md deleted file mode 100644 index 4657ff4..0000000 --- a/archive/2026-04-16/PLANTUML_DIAGRAMS.md +++ /dev/null @@ -1,2083 +0,0 @@ -# FIVUCSAS - Complete PlantUML Diagrams Collection - -**Document Version:** 2.0 -**Date:** November 4, 2025 -**Purpose:** Production-ready diagrams for documentation and architecture review - ---- - -## Table of Contents - -1. [Entity-Relationship Diagrams](#1-entity-relationship-diagrams) -2. [Class Diagrams](#2-class-diagrams) -3. [Sequence Diagrams](#3-sequence-diagrams) -4. [State Machine Diagrams](#4-state-machine-diagrams) -5. [Activity Diagrams](#5-activity-diagrams) - ---- - -## 1. Entity-Relationship Diagrams - -### 1.1 Complete Database ER Diagram - -```plantuml -@startuml fivucsas_er_diagram - -skinparam linetype ortho -skinparam packageStyle rectangle - -' Shared Schema Tables -package "Shared Schema" <> { - entity tenants { - * id : UUID <> - -- - name : VARCHAR(255) - slug : VARCHAR(100) <> - domain : VARCHAR(255) - subscription_plan : VARCHAR(50) - subscription_status : VARCHAR(50) - max_users : INTEGER - max_storage_gb : INTEGER - max_api_calls_per_day : INTEGER - current_user_count : INTEGER - current_storage_mb : NUMERIC - api_calls_today : INTEGER - is_active : BOOLEAN - is_trial : BOOLEAN - contact_email : VARCHAR(255) - settings : JSONB - features : JSONB - created_at : TIMESTAMP - updated_at : TIMESTAMP - deleted_at : TIMESTAMP - } - - entity system_admins { - * id : UUID <> - -- - email : VARCHAR(255) <> - password_hash : VARCHAR(255) - first_name : VARCHAR(100) - last_name : VARCHAR(100) - mfa_enabled : BOOLEAN - mfa_secret : VARCHAR(255) - is_active : BOOLEAN - is_super_admin : BOOLEAN - last_login_at : TIMESTAMP - last_login_ip : INET - created_at : TIMESTAMP - } -} - -' Tenant Schema Tables -package "Tenant Schema (per tenant)" <> { - entity users { - * id : UUID <> - -- - email : VARCHAR(255) <> - password_hash : VARCHAR(255) - first_name : VARCHAR(100) - last_name : VARCHAR(100) - phone_number : VARCHAR(20) - id_number : VARCHAR(50) <> - date_of_birth : DATE - address_line1 : VARCHAR(255) - city : VARCHAR(100) - country : VARCHAR(2) - status : VARCHAR(20) - is_biometric_enrolled : BOOLEAN - verification_count : INTEGER - created_at : TIMESTAMP - updated_at : TIMESTAMP - } - - entity roles { - * id : UUID <> - -- - name : VARCHAR(100) <> - description : VARCHAR(500) - is_system_role : BOOLEAN - created_at : TIMESTAMP - } - - entity permissions { - * id : UUID <> - -- - code : VARCHAR(100) <> - name : VARCHAR(200) - category : VARCHAR(50) - description : VARCHAR(500) - } - - entity user_roles { - * id : UUID <> - -- - user_id : UUID <> - role_id : UUID <> - assigned_at : TIMESTAMP - assigned_by : UUID - } - - entity role_permissions { - * id : UUID <> - -- - role_id : UUID <> - permission_id : UUID <> - } - - entity biometric_data { - * id : UUID <> - -- - user_id : UUID <> - biometric_type : VARCHAR(50) - embedding : VECTOR(512) - quality_score : NUMERIC(3,2) - is_active : BOOLEAN - is_primary : BOOLEAN - enrolled_at : TIMESTAMP - updated_at : TIMESTAMP - } - - entity verification_logs { - * id : UUID <> - -- - user_id : UUID <> - biometric_id : UUID <> - verified : BOOLEAN - confidence : NUMERIC(5,4) - verification_method : VARCHAR(50) - ip_address : INET - user_agent : VARCHAR(500) - location : GEOGRAPHY - verified_at : TIMESTAMP - } - - entity sessions { - * id : UUID <> - -- - user_id : UUID <> - refresh_token_hash : VARCHAR(255) - ip_address : INET - user_agent : VARCHAR(500) - is_active : BOOLEAN - created_at : TIMESTAMP - expires_at : TIMESTAMP - last_activity_at : TIMESTAMP - } - - entity audit_logs { - * id : UUID <> - -- - user_id : UUID <> - action : VARCHAR(100) - entity_type : VARCHAR(100) - entity_id : UUID - old_value : JSONB - new_value : JSONB - ip_address : INET - user_agent : VARCHAR(500) - created_at : TIMESTAMP - } -} - -' Relationships -users ||--o{ user_roles : has -roles ||--o{ user_roles : assigned_to -roles ||--o{ role_permissions : has -permissions ||--o{ role_permissions : granted_in - -users ||--o{ biometric_data : has -users ||--o{ verification_logs : generates -users ||--o{ sessions : has -users ||--o{ audit_logs : creates - -biometric_data ||--o{ verification_logs : used_in - -@enduml -``` - -### 1.2 Core Business Entities ER Diagram (Simplified) - -```plantuml -@startuml core_entities_er - -entity "Tenant" as tenant { - * id : UUID <> - -- - * name : VARCHAR - * slug : VARCHAR - subscription_plan : VARCHAR - max_users : INTEGER - is_active : BOOLEAN -} - -entity "User" as user { - * id : UUID <> - -- - * email : VARCHAR - * password_hash : VARCHAR - * first_name : VARCHAR - * last_name : VARCHAR - * status : VARCHAR - is_biometric_enrolled : BOOLEAN - verification_count : INTEGER -} - -entity "Role" as role { - * id : UUID <> - -- - * name : VARCHAR - display_name : VARCHAR - is_system_role : BOOLEAN -} - -entity "Permission" as permission { - * id : UUID <> - -- - * code : VARCHAR - * resource : VARCHAR - * action : VARCHAR -} - -entity "BiometricData" as biometric { - * id : UUID <> - -- - user_id : UUID <> - biometric_type : VARCHAR - embedding : vector(512) - quality_score : NUMERIC - is_active : BOOLEAN - is_primary : BOOLEAN -} - -entity "VerificationLog" as verification { - * id : UUID <> - -- - user_id : UUID <> - biometric_data_id : UUID <> - verified : BOOLEAN - confidence : NUMERIC - distance : NUMERIC - verified_at : TIMESTAMP -} - -' Relationships -tenant ||--o{ user : "manages" -user ||--o{ role : "has (M:N)" -role ||--o{ permission : "has (M:N)" -user ||--|{ biometric : "has" -user ||--o{ verification : "verified" -biometric ||--o{ verification : "used in" - -@enduml -``` - ---- - -## 2. Class Diagrams - -### 2.1 Domain Model - Complete Class Diagram - -```plantuml -@startuml domain_model - -skinparam classAttributeIconSize 0 -skinparam linetype ortho - -package "Domain Layer" { - - ' Aggregate Roots - class Tenant <> { - - id: UUID - - name: String - - slug: String - - subscriptionPlan: SubscriptionPlan - - subscriptionStatus: SubscriptionStatus - - maxUsers: Int - - currentUserCount: Int - - isActive: Boolean - - settings: Map - - features: Set - - createdAt: Instant - - updatedAt: Instant - -- - + activate(): void - + suspend(): void - + upgradePlan(plan: SubscriptionPlan): void - + canAddUser(): Boolean - + incrementUserCount(): void - + decrementUserCount(): void - } - - class User <> { - - id: UUID - - email: String - - passwordHash: String - - firstName: String - - lastName: String - - phoneNumber: String? - - status: UserStatus - - isBiometricEnrolled: Boolean - - verificationCount: Int - - failedVerificationCount: Int - - enrolledAt: Instant? - - lastVerifiedAt: Instant? - - createdAt: Instant - - updatedAt: Instant - -- - + enroll(biometricData: BiometricData): void - + verify(verificationResult: VerificationResult): void - + activate(): void - + suspend(): void - + lock(): void - + unlock(): void - + hasRole(roleName: String): Boolean - + hasPermission(permissionCode: String): Boolean - + changePassword(newPassword: String): void - + incrementVerificationCount(): void - + incrementFailedVerificationCount(): void - + resetFailedAttempts(): void - } - - ' Value Objects - class Email <> { - - value: String - -- - + Email(value: String) - + validate(): Boolean - + toString(): String - + equals(other: Email): Boolean - } - - class PhoneNumber <> { - - value: String - - countryCode: String - -- - + PhoneNumber(value: String) - + validate(): Boolean - + format(): String - } - - ' Entities - class Role <> { - - id: UUID - - name: String - - displayName: String - - description: String - - parentRole: Role? - - level: Int - - isSystemRole: Boolean - - permissions: Set - -- - + addPermission(permission: Permission): void - + removePermission(permission: Permission): void - + hasPermission(permissionCode: String): Boolean - + getAllPermissions(): Set - } - - class Permission <> { - - id: UUID - - code: String - - resource: String - - action: String - - description: String - -- - + matches(resource: String, action: String): Boolean - } - - class BiometricData <> { - - id: UUID - - userId: UUID - - biometricType: BiometricType - - modelName: String - - modelVersion: String - - embedding: FloatArray - - qualityScore: Float - - sharpnessScore: Float - - brightnessScore: Float - - contrastScore: Float - - enrolledAt: Instant - - isActive: Boolean - - isPrimary: Boolean - - version: Int - - previousVersionId: UUID? - -- - + calculateDistance(otherEmbedding: FloatArray): Float - + verify(queryEmbedding: FloatArray, threshold: Float): Boolean - + archive(): void - + makeObsolete(): void - + isHighQuality(): Boolean - } - - class VerificationLog <> { - - id: UUID - - userId: UUID - - biometricDataId: UUID? - - verified: Boolean - - confidence: Float - - distance: Float - - threshold: Float - - modelName: String - - detectorBackend: String - - verifiedAt: Instant - - verificationContext: String - - processingTimeMs: Int - - failureReason: String? - -- - + isSuccessful(): Boolean - + isFastEnough(): Boolean - } - - class AuditLog <> { - - id: UUID - - eventType: String - - eventCategory: EventCategory - - severity: Severity - - actorType: ActorType - - actorId: UUID? - - targetType: String? - - targetId: UUID? - - description: String - - changes: Map - - ipAddress: String - - occurredAt: Instant - -- - + isSecurityEvent(): Boolean - + requiresAlert(): Boolean - } - - class Session <> { - - id: UUID - - userId: UUID - - refreshTokenHash: String - - accessTokenJti: String - - deviceFingerprint: String - - deviceName: String - - ipAddress: String - - createdAt: Instant - - lastActivityAt: Instant - - expiresAt: Instant - - isActive: Boolean - -- - + isExpired(): Boolean - + revoke(reason: String): void - + updateActivity(): void - + isFromSameDevice(fingerprint: String): Boolean - } - - ' Enums - enum UserStatus { - ACTIVE - INACTIVE - SUSPENDED - LOCKED - PENDING_VERIFICATION - } - - enum BiometricType { - FACE - FINGERPRINT - VOICE - IRIS - } - - enum SubscriptionPlan { - TRIAL - BASIC - PROFESSIONAL - ENTERPRISE - CUSTOM - } - - enum SubscriptionStatus { - ACTIVE - SUSPENDED - CANCELLED - EXPIRED - } - - enum EventCategory { - SECURITY - DATA_CHANGE - AUTHENTICATION - AUTHORIZATION - SYSTEM - } - - enum Severity { - DEBUG - INFO - WARNING - ERROR - CRITICAL - } - - enum ActorType { - USER - SYSTEM - ADMIN - API - } -} - -' Relationships -Tenant "1" *-- "many" User : manages -User "1" *-- "many" BiometricData : has -User "many" -- "many" Role : has -Role "many" -- "many" Permission : has -Role "1" o-- "many" Role : parent of -User "1" *-- "many" VerificationLog : verified -BiometricData "1" o-- "many" VerificationLog : used in -User "1" *-- "many" Session : has -User "1" *-- "many" AuditLog : performed - -User *-- Email -User *-- PhoneNumber -User -- UserStatus -BiometricData -- BiometricType -Tenant -- SubscriptionPlan -Tenant -- SubscriptionStatus -AuditLog -- EventCategory -AuditLog -- Severity -AuditLog -- ActorType - -@enduml -``` - -### 2.2 Service Layer Class Diagram - -```plantuml -@startuml service_layer - -skinparam classAttributeIconSize 0 - -package "Application Layer" { - - ' Service Interfaces - interface UserService { - + createUser(request: CreateUserRequest): User - + updateUser(id: UUID, request: UpdateUserRequest): User - + deleteUser(id: UUID): void - + findById(id: UUID): User? - + findAll(pageable: Pageable): Page - + search(query: String): List - } - - interface AuthService { - + register(request: RegisterRequest): AuthResponse - + login(request: LoginRequest): AuthResponse - + logout(userId: UUID): void - + refreshToken(refreshToken: String): TokenPair - + verifyToken(token: String): Boolean - + resetPassword(email: String): void - } - - interface BiometricService { - + enrollFace(userId: UUID, image: ByteArray): EnrollmentResponse - + verifyFace(userId: UUID, image: ByteArray): VerificationResponse - + deleteBiometric(id: UUID): void - + getBiometricData(userId: UUID): List - } - - interface RoleService { - + createRole(request: CreateRoleRequest): Role - + updateRole(id: UUID, request: UpdateRoleRequest): Role - + deleteRole(id: UUID): void - + assignPermission(roleId: UUID, permissionId: UUID): void - + removePermission(roleId: UUID, permissionId: UUID): void - } - - ' Service Implementations - class UserServiceImpl implements UserService { - - userRepository: UserRepository - - passwordEncoder: PasswordEncoder - - eventPublisher: EventPublisher - -- - + createUser(request: CreateUserRequest): User - + updateUser(id: UUID, request: UpdateUserRequest): User - - validateUser(request: CreateUserRequest): void - - publishUserCreatedEvent(user: User): void - } - - class AuthServiceImpl implements AuthService { - - userRepository: UserRepository - - passwordEncoder: PasswordEncoder - - jwtService: JwtService - - sessionRepository: SessionRepository - -- - + register(request: RegisterRequest): AuthResponse - + login(request: LoginRequest): AuthResponse - - validateCredentials(email: String, password: String): User - - handleFailedLogin(user: User): void - } - - class BiometricServiceImpl implements BiometricService { - - biometricRepository: BiometricDataRepository - - userRepository: UserRepository - - biometricClient: BiometricProcessorClient - -- - + enrollFace(userId: UUID, image: ByteArray): EnrollmentResponse - + verifyFace(userId: UUID, image: ByteArray): VerificationResponse - - validateImageQuality(image: ByteArray): void - - extractEmbedding(image: ByteArray): FloatArray - } - - ' External Clients - class BiometricProcessorClient { - - webClient: WebClient - - baseUrl: String - -- - + enrollFace(image: ByteArray): EmbeddingResponse - + verifyFace(image: ByteArray, embedding: FloatArray): VerificationResult - + healthCheck(): Boolean - } - - ' Repositories (Ports) - interface UserRepository { - + save(user: User): User - + findById(id: UUID): User? - + findByEmail(email: String): User? - + findAll(pageable: Pageable): Page - + delete(id: UUID): void - } - - interface BiometricDataRepository { - + save(data: BiometricData): BiometricData - + findByUserId(userId: UUID): List - + findPrimaryByUserId(userId: UUID): BiometricData? - + searchSimilar(embedding: FloatArray, threshold: Float): List - } - - interface SessionRepository { - + save(session: Session): Session - + findByRefreshTokenHash(hash: String): Session? - + findActiveByUserId(userId: UUID): List - + deleteExpired(): Int - } - - ' DTOs - class CreateUserRequest { - + email: String - + password: String - + firstName: String - + lastName: String - + phoneNumber: String? - } - - class AuthResponse { - + accessToken: String - + refreshToken: String - + tokenType: String - + expiresIn: Long - + user: UserDto - } - - class EnrollmentResponse { - + success: Boolean - + userId: UUID - + qualityScore: Float - + message: String - } - - class VerificationResponse { - + verified: Boolean - + confidence: Float - + distance: Float - + message: String - } -} - -' Relationships -UserServiceImpl ..> UserRepository : uses -AuthServiceImpl ..> UserRepository : uses -AuthServiceImpl ..> SessionRepository : uses -BiometricServiceImpl ..> BiometricDataRepository : uses -BiometricServiceImpl ..> UserRepository : uses -BiometricServiceImpl ..> BiometricProcessorClient : uses - -@enduml -``` - -### 2.3 Biometric Processor Class Diagram - -```plantuml -@startuml biometric_processor_classes - -skinparam classAttributeIconSize 0 - -package "Biometric Processor" { - - ' Service Classes - class FaceRecognitionService { - - model_name: str - - detector_backend: str - - verification_threshold: float - -- - + __init__(model_name: str, detector_backend: str) - + extract_embedding(image_path: str): Tuple[bool, str, str] - + verify_faces(image_path: str, stored_embedding: str): Tuple[bool, float, str] - - _calculate_cosine_distance(emb1: ndarray, emb2: ndarray): float - + validate_image(image_path: str): Tuple[bool, str] - } - - class LivenessDetectionService { - - puzzle_steps: List[PuzzleStep] - - timeout_seconds: int - -- - + generate_puzzle(): BiometricPuzzle - + verify_liveness(video_frames: List[bytes], puzzle_id: str): LivenessResult - - _detect_action(frame: bytes, action: str): bool - - _calculate_ear(landmarks: List[Point]): float - - _calculate_mar(landmarks: List[Point]): float - } - - class ImageQualityValidator { - - min_sharpness: float - - min_brightness: float - - min_contrast: float - -- - + validate(image_path: str): QualityMetrics - - _calculate_sharpness(image: ndarray): float - - _calculate_brightness(image: ndarray): float - - _calculate_contrast(image: ndarray): float - - _detect_face_size(image: ndarray): float - } - - ' Model Classes - class FaceEmbedding { - + embedding: List[float] - + dimension: int - + model_name: str - -- - + to_numpy(): ndarray - + calculate_distance(other: FaceEmbedding, metric: str): float - + get_statistics(): Dict[str, float] - } - - class VerificationResult { - + verified: bool - + confidence: float - + distance: float - + threshold: float - + model_name: str - -- - + is_successful(): bool - + to_dict(): Dict[str, Any] - } - - class QualityMetrics { - + sharpness_score: float - + brightness_score: float - + contrast_score: float - + face_size_score: float - + pose_quality_score: float - + overall_score: float - + quality_level: QualityLevel - + issues: List[str] - -- - + is_acceptable(): bool - + get_problematic_metrics(): List[str] - } - - class BiometricPuzzle { - + puzzle_id: str - + steps: List[PuzzleStep] - + timeout: int - + created_at: datetime - + expires_at: datetime - -- - + is_expired(): bool - + get_next_step(): PuzzleStep - } - - class PuzzleStep { - + action: str - + duration: int - + order: int - -- - + validate_action(detected_action: str): bool - } - - class LivenessResult { - + success: bool - + liveness_confirmed: bool - + steps_completed: int - + total_steps: int - + completion_time: float - + failure_reason: str - -- - + is_successful(): bool - } - - ' Enums - enum QualityLevel { - EXCELLENT - GOOD - FAIR - POOR - VERY_POOR - } - - enum BiometricAction { - SMILE - BLINK_LEFT - BLINK_RIGHT - BLINK_BOTH - LOOK_LEFT - LOOK_RIGHT - LOOK_UP - LOOK_DOWN - NEUTRAL - } -} - -' Relationships -FaceRecognitionService --> FaceEmbedding : creates -FaceRecognitionService --> VerificationResult : returns -ImageQualityValidator --> QualityMetrics : returns -LivenessDetectionService --> BiometricPuzzle : generates -LivenessDetectionService --> LivenessResult : returns -BiometricPuzzle *-- PuzzleStep : contains -QualityMetrics -- QualityLevel : uses -PuzzleStep -- BiometricAction : defines - -@enduml -``` - ---- - -## 3. Sequence Diagrams - -### 3.1 User Registration Flow - -```plantuml -@startuml user_registration - -actor User -participant "Mobile App" as App -participant "API Gateway" as Gateway -participant "Identity Core" as Identity -participant "Database" as DB -participant "Email Service" as Email - -User -> App: Enter registration details -App -> App: Validate input locally - -App -> Gateway: POST /api/v1/auth/register -Gateway -> Identity: Forward request - -Identity -> Identity: Validate email format -Identity -> Identity: Check password strength - -Identity -> DB: Check if email exists -alt Email already exists - DB --> Identity: User found - Identity --> Gateway: 409 Conflict - Gateway --> App: Email already registered - App --> User: Show error message -else Email not found - DB --> Identity: No user found - - Identity -> Identity: Hash password (BCrypt) - Identity -> Identity: Create User entity - - Identity -> DB: INSERT user - DB --> Identity: User created (UUID) - - Identity -> Identity: Generate email verification token - - Identity -> DB: INSERT verification_token - DB --> Identity: Token saved - - Identity -> Email: Send verification email - Email --> Identity: Email queued - - Identity -> Identity: Generate JWT tokens - - Identity -> DB: INSERT session - DB --> Identity: Session created - - Identity --> Gateway: 201 Created + AuthResponse - Gateway --> App: Registration successful - App --> User: Show success message - App -> App: Store tokens securely -end - -@enduml -``` - -### 3.2 Face Enrollment with Quality Validation - -```plantuml -@startuml face_enrollment_quality - -actor User -participant "Mobile App" as App -participant "Camera" as Camera -participant "API Gateway" as Gateway -participant "Identity Core" as Identity -participant "Biometric Processor" as Biometric -participant "Database" as DB - -User -> App: Navigate to enrollment -App -> Camera: Request camera permission -Camera --> App: Permission granted - -App -> Camera: Start preview -Camera --> App: Camera stream active - -User -> App: Capture face photo -App -> Camera: Capture image -Camera --> App: Image captured (ByteArray) - -App -> App: Compress image (< 5MB) - -App -> Gateway: POST /biometric/enroll/{userId}\n(multipart/form-data) -Gateway -> Identity: Forward request - -Identity -> DB: Check user exists -DB --> Identity: User found - -Identity -> DB: Check if already enrolled -DB --> Identity: Not enrolled yet - -Identity -> Biometric: POST /face/enroll\n(image data) - -Biometric -> Biometric: Save temp file -Biometric -> Biometric: Validate image format - -Biometric -> Biometric: **Quality Validation**\n- Check resolution\n- Check file size\n- Verify not corrupted - -alt Quality Check Failed - Biometric --> Identity: 400 Bad Request\n(Quality issues) - Identity --> Gateway: Error response - Gateway --> App: Quality validation failed - App --> User: Show specific issues:\n- Resolution too low\n- Image too dark\n- etc. - - User -> App: Retake photo - App -> Camera: Capture again -else Quality Check Passed - - Biometric -> Biometric: **Detect Face**\nUsing RetinaFace - - alt No Face Detected - Biometric --> Identity: 400 Bad Request\n(No face found) - Identity --> Gateway: Error response - Gateway --> App: No face detected - App --> User: Please center face\nin camera - else Multiple Faces - Biometric --> Identity: 400 Bad Request\n(Multiple faces) - Identity --> Gateway: Error response - Gateway --> App: Multiple faces detected - App --> User: Ensure only one person\nin frame - else Single Face Detected - - Biometric -> Biometric: **Calculate Quality Scores**\n- Sharpness: 85/100\n- Brightness: 78/100\n- Contrast: 82/100\n- Face size: 90/100\n- Pose: 88/100 - - alt Overall Quality < Threshold (50) - Biometric --> Identity: 400 Bad Request\n(Low quality) - Identity --> Gateway: Error with scores - Gateway --> App: Quality too low - App --> User: Show quality report:\n- Improve lighting\n- Hold steady\n- Move closer - else Quality Acceptable - - Biometric -> Biometric: **Extract Embedding**\nVGG-Face model - Biometric -> Biometric: Generate 512-D vector - - Biometric -> Biometric: Cleanup temp file - - Biometric --> Identity: 200 OK\n{embedding, quality_score} - - Identity -> Identity: Convert embedding to JSONB - Identity -> Identity: Encrypt embedding (AES-256) - - Identity -> DB: INSERT biometric_data - DB --> Identity: Biometric saved (UUID) - - Identity -> DB: UPDATE users\nSET is_biometric_enrolled = true - DB --> Identity: User updated - - Identity -> DB: INSERT audit_log\n(biometric.enrolled event) - DB --> Identity: Audit logged - - Identity --> Gateway: 200 OK\n{success, userId, confidence} - Gateway --> App: Enrollment successful - - App --> User: Face enrolled successfully!\nQuality Score: 85/100 - end - end -end - -@enduml -``` - -### 3.3 Face Verification with Liveness Detection - -```plantuml -@startuml face_verification_liveness - -actor User -participant "Mobile App" as App -participant "Camera" as Camera -participant "API Gateway" as Gateway -participant "Identity Core" as Identity -participant "Biometric Processor" as Biometric -participant "Database" as DB -participant "Redis" as Redis - -User -> App: Initiate verification -App -> App: Check network connectivity - -App -> Gateway: GET /api/v1/liveness/generate-puzzle -Gateway -> Biometric: Forward request - -Biometric -> Biometric: Generate random puzzle\n(3-5 steps) -Biometric -> Redis: SETEX puzzle:{id} 60 -Redis --> Biometric: Cached - -Biometric --> Gateway: 200 OK\n{puzzle_id, steps[], timeout} -Gateway --> App: Puzzle received - -App -> Camera: Start video stream -Camera --> App: Stream active - -App --> User: **Show Instructions**\n1. Smile\n2. Blink both eyes\n3. Look right\n4. Return to neutral - -loop For each puzzle step - App --> User: Display current step:\n"Please SMILE" - - User -> Camera: Perform action - Camera --> App: Video frames - - App -> App: **Detect facial landmarks**\nUsing MediaPipe - - App -> App: **Calculate metrics**\n- EAR (Eye Aspect Ratio)\n- MAR (Mouth Aspect Ratio)\n- Head pose angles - - alt Action detected correctly - App --> User: Step complete (green) - App -> App: Move to next step - else Action timeout (no detection) - App --> User: Timeout, try again - App -> App: Retry current step - end -end - -App -> App: Capture final frame -App -> App: Extract landmarks sequence - -App -> Gateway: POST /api/v1/liveness/verify -note right -{ - "puzzle_id": "uuid", - "video_frames": [base64...], - "landmarks_sequence": [[x,y]...], - "user_id": "uuid" -} -end note - -Gateway -> Biometric: Forward request - -Biometric -> Redis: GET puzzle:{id} -Redis --> Biometric: Puzzle data - -Biometric -> Biometric: Validate puzzle not expired -Biometric -> Biometric: Verify step sequence matches -Biometric -> Biometric: Analyze timing patterns - -alt Liveness check failed - Biometric --> Gateway: 403 Forbidden\n(Liveness not confirmed) - Gateway --> App: Liveness failed - App --> User: Verification failed:\nCould not confirm liveness -else Liveness confirmed - - Biometric --> Gateway: 200 OK\n{liveness_confirmed, final_frame} - Gateway -> Identity: POST /biometric/verify/{userId}\n(final_frame) - - Identity -> DB: SELECT embedding\nFROM biometric_data\nWHERE user_id = ? - DB --> Identity: Stored embedding - - Identity -> Biometric: POST /face/verify\n{image, stored_embedding} - - Biometric -> Biometric: Extract new embedding - Biometric -> Biometric: Calculate cosine distance - Biometric -> Biometric: Compare with threshold - - alt Distance < Threshold (0.30) - Biometric --> Identity: {verified: true,\nconfidence: 0.92} - - Identity -> DB: UPDATE users\nSET verification_count++,\nlast_verified_at = NOW() - - Identity -> DB: INSERT verification_logs - - Identity -> Redis: PUBLISH user.verified - - Identity --> Gateway: 200 OK\n{verified: true,\nconfidence: 92%} - Gateway --> App: Verification successful - - App --> User: **Verified Successfully!**\nConfidence: 92%\nWelcome back! - else Distance >= Threshold - Biometric --> Identity: {verified: false,\nconfidence: 0.45} - - Identity -> DB: UPDATE users\nSET failed_verification_count++ - - Identity -> DB: INSERT verification_logs\n(failed) - - Identity --> Gateway: 200 OK\n{verified: false,\nconfidence: 45%} - Gateway --> App: Verification failed - - App --> User: **Verification Failed**\nFace does not match\nConfidence: 45% - end -end - -@enduml -``` - -### 3.4 Multi-Tenant User Creation - -```plantuml -@startuml multi_tenant_creation - -actor "Tenant Admin" as Admin -participant "Admin Dashboard" as Dashboard -participant "API Gateway" as Gateway -participant "Identity Core" as Identity -participant "PostgreSQL" as DB - -Admin -> Dashboard: Login to tenant\n(tenant-acme) -Dashboard -> Dashboard: Set tenant context\nX-Tenant-ID: tenant-acme - -Admin -> Dashboard: Navigate to\n"Add User" page -Admin -> Dashboard: Fill user form - -Dashboard -> Dashboard: Validate form\n- Email format\n- Password strength\n- Required fields - -Dashboard -> Gateway: POST /api/v1/users\nHeader: X-Tenant-ID: tenant-acme -note right -{ - "email": "john@acme.com", - "firstName": "John", - "lastName": "Doe", - "roles": ["END_USER"] -} -end note - -Gateway -> Gateway: Extract tenant ID\nfrom header -Gateway -> Identity: Forward with\ntenant context - -Identity -> Identity: Set database schema:\ntenant_acme - -Identity -> DB: SET search_path = 'tenant_acme' -DB --> Identity: Schema set - -Identity -> DB: BEGIN TRANSACTION - -Identity -> DB: SELECT tenant_id, max_users,\ncurrent_user_count\nFROM shared.tenants\nWHERE slug = 'tenant-acme' -DB --> Identity: Tenant info - -alt Current users >= Max users - Identity -> DB: ROLLBACK - Identity --> Gateway: 403 Forbidden\n(User limit reached) - Gateway --> Dashboard: Quota exceeded - Dashboard --> Admin: Cannot add user:\nPlan limit reached (100/100)\nPlease upgrade plan -else Quota available - - Identity -> DB: SELECT * FROM users\nWHERE email = 'john@acme.com' - DB --> Identity: No user found - - alt Email already exists - Identity -> DB: ROLLBACK - Identity --> Gateway: 409 Conflict - Gateway --> Dashboard: Email exists - Dashboard --> Admin: User already exists\nin your organization - else Email unique - - Identity -> Identity: Hash password - Identity -> Identity: Create User entity - - Identity -> DB: INSERT INTO users\n(id, email, first_name, ...)\nVALUES (?, ?, ?, ...) - DB --> Identity: User created (UUID) - - Identity -> DB: INSERT INTO user_roles\n(user_id, role_id)\nSELECT ?, id FROM roles\nWHERE name = 'END_USER' - DB --> Identity: Roles assigned - - Identity -> DB: UPDATE shared.tenants\nSET current_user_count =\n current_user_count + 1\nWHERE slug = 'tenant-acme' - DB --> Identity: Count updated - - Identity -> DB: INSERT INTO audit_logs\n(event_type, actor_id,\n target_id, description) - DB --> Identity: Audit logged - - Identity -> DB: COMMIT TRANSACTION - DB --> Identity: Transaction committed - - Identity --> Gateway: 201 Created\n{user object} - Gateway --> Dashboard: User created - - Dashboard --> Admin: User created successfully!\nInvitation email sent to:\njohn@acme.com - - Dashboard -> Dashboard: Refresh user list - Dashboard --> Admin: Updated list:\nUsers: 51/100 - end -end - -note right of DB -**Multi-Tenancy Isolation:** -- Each tenant has separate schema -- tenant_acme.users -- tenant_techcorp.users -- Complete data isolation -- Shared tables in 'shared' schema -end note - -@enduml -``` - ---- - -## 4. State Machine Diagrams - -### 4.1 User Lifecycle State Machine - -```plantuml -@startuml user_state_machine - -[*] --> PENDING_VERIFICATION : User registers - -PENDING_VERIFICATION --> ACTIVE : Email verified\n& email verification -PENDING_VERIFICATION --> PENDING_VERIFICATION : Resend verification - -ACTIVE --> SUSPENDED : Admin suspends\nOR policy violation -ACTIVE --> LOCKED : Too many\nfailed login attempts -ACTIVE --> INACTIVE : Admin deactivates\nOR user requests - -SUSPENDED --> ACTIVE : Admin reinstates -SUSPENDED --> INACTIVE : Permanent suspension - -LOCKED --> ACTIVE : Unlock timeout expires\nOR admin unlocks -LOCKED --> ACTIVE : Password reset\ncompleted - -INACTIVE --> ACTIVE : Admin reactivates\nOR user re-registers - -ACTIVE --> [*] : Account deleted\n(soft delete) -SUSPENDED --> [*] : Account deleted -LOCKED --> [*] : Account deleted -INACTIVE --> [*] : Account deleted - -note right of PENDING_VERIFICATION - **Initial State** - - Created but not verified - - Limited access - - Email verification required -end note - -note right of ACTIVE - **Normal State** - - Full access - - Can enroll biometric - - Can verify identity -end note - -note right of LOCKED - **Security State** - - Auto-locked after 5 failed attempts - - Requires password reset - - Or auto-unlock after 15 minutes -end note - -note right of SUSPENDED - **Administrative State** - - Admin action required - - Policy violation or security concern - - All access revoked -end note - -@enduml -``` - -### 4.2 Biometric Enrollment State Machine - -```plantuml -@startuml biometric_enrollment_state - -[*] --> NOT_ENROLLED : User created - -NOT_ENROLLED --> CAPTURING : Start enrollment - -CAPTURING --> VALIDATING_QUALITY : Image captured - -VALIDATING_QUALITY --> QUALITY_FAILED : Quality check fails\n(too dark, blurry, etc.) -QUALITY_FAILED --> CAPTURING : Retry capture - -VALIDATING_QUALITY --> DETECTING_FACE : Quality acceptable - -DETECTING_FACE --> FACE_NOT_DETECTED : No face found\nOR multiple faces -FACE_NOT_DETECTED --> CAPTURING : Retry capture - -DETECTING_FACE --> EXTRACTING_EMBEDDING : Single face detected - -EXTRACTING_EMBEDDING --> EXTRACTION_FAILED : Model error\nOR processing error -EXTRACTION_FAILED --> CAPTURING : Retry enrollment - -EXTRACTING_EMBEDDING --> STORING : Embedding extracted - -STORING --> STORAGE_FAILED : Database error -STORAGE_FAILED --> EXTRACTING_EMBEDDING : Retry storage - -STORING --> ENROLLED : Successfully stored - -ENROLLED --> UPDATING : Re-enrollment requested -UPDATING --> VALIDATING_QUALITY : New image captured - -ENROLLED --> ARCHIVED : User deactivated\nOR biometric expired -ARCHIVED --> UPDATING : Re-activation - -ENROLLED --> [*] : User deleted - -note right of VALIDATING_QUALITY - **Quality Checks:** - - Sharpness ≥ 40/100 - - Brightness ≥ 30/100 - - Contrast ≥ 30/100 - - Face size ≥ 50% of image - - Pose quality ≥ 40/100 -end note - -note right of ENROLLED - **Final State** - - Biometric data stored - - User can verify - - Version tracking enabled -end note - -@enduml -``` - -### 4.3 Verification Attempt State Machine - -```plantuml -@startuml verification_state_machine - -[*] --> INITIATED : User starts verification - -INITIATED --> LIVENESS_CHECK : Liveness enabled -INITIATED --> FACE_CAPTURE : Liveness disabled - -LIVENESS_CHECK --> PUZZLE_GENERATED : Generate puzzle - -PUZZLE_GENERATED --> PERFORMING_ACTIONS : Show instructions - -PERFORMING_ACTIONS --> LIVENESS_FAILED : Timeout\nOR wrong sequence\nOR spoofing detected -LIVENESS_FAILED --> [*] : Return failure - -PERFORMING_ACTIONS --> LIVENESS_CONFIRMED : All steps completed\ncorrectly - -LIVENESS_CONFIRMED --> FACE_CAPTURE : Capture final frame - -FACE_CAPTURE --> QUALITY_CHECK : Image captured - -QUALITY_CHECK --> LOW_QUALITY : Quality < threshold -LOW_QUALITY --> FACE_CAPTURE : Retry capture - -QUALITY_CHECK --> EXTRACTING : Quality acceptable - -EXTRACTING --> EXTRACTION_ERROR : Processing failed -EXTRACTION_ERROR --> [*] : Return error - -EXTRACTING --> COMPARING : Embedding extracted - -COMPARING --> RETRIEVING_STORED : Get stored embedding - -RETRIEVING_STORED --> DATABASE_ERROR : User not found\nOR no biometric data -DATABASE_ERROR --> [*] : Return error - -RETRIEVING_STORED --> CALCULATING_DISTANCE : Embeddings retrieved - -CALCULATING_DISTANCE --> VERIFICATION_SUCCESS : Distance < threshold\n(e.g., < 0.30) -CALCULATING_DISTANCE --> VERIFICATION_FAILURE : Distance >= threshold - -VERIFICATION_SUCCESS --> LOGGING_SUCCESS : Log successful verification -LOGGING_SUCCESS --> [*] : Return success - -VERIFICATION_FAILURE --> LOGGING_FAILURE : Log failed verification -LOGGING_FAILURE --> [*] : Return failure - -note right of LIVENESS_CHECK - **Optional Step** - - Enabled for high-security contexts - - Random puzzle generation - - Prevents photo/video attacks -end note - -note right of COMPARING - **Distance Calculation** - - Cosine similarity - - Threshold: 0.30 (configurable) - - Lower distance = higher similarity -end note - -@enduml -``` - -### 4.4 Session Lifecycle State Machine - -```plantuml -@startuml session_state_machine - -[*] --> CREATED : User logs in - -CREATED --> ACTIVE : Token validated - -ACTIVE --> ACTIVE : API requests\n(update last_activity) - -ACTIVE --> EXPIRED : Reaches expiry time\n(default: 7 days) - -ACTIVE --> REVOKED_BY_USER : User logs out - -ACTIVE --> REVOKED_BY_ADMIN : Admin revokes session - -ACTIVE --> REVOKED_BY_SYSTEM : Security policy\nOR suspicious activity - -ACTIVE --> REFRESHED : Refresh token used - -REFRESHED --> ACTIVE : New token pair issued - -EXPIRED --> [*] : Cleanup job\ndeletes session - -REVOKED_BY_USER --> [*] : Session terminated -REVOKED_BY_ADMIN --> [*] : Session terminated -REVOKED_BY_SYSTEM --> [*] : Session terminated - -note right of ACTIVE - **Active Session** - - Valid refresh token - - Can generate access tokens - - Tracks last activity - - Device information stored -end note - -note right of REFRESHED - **Token Rotation** - - Old refresh token invalidated - - New refresh token issued - - New access token issued - - Prevents token replay attacks -end note - -@enduml -``` - ---- - -## 5. Activity Diagrams - -### 5.1 Complete User Onboarding Activity - -```plantuml -@startuml user_onboarding_activity - -start - -:User opens mobile app; - -if (User has account?) then (yes) - :Navigate to login; - stop -else (no) - :Tap "Register"; -endif - -partition "Registration Process" { - :Enter registration details: - - Email - - Password - - First name - - Last name - - Phone number; - - :Validate input locally; - - if (All fields valid?) then (no) - :Show validation errors; - stop - endif - - :Submit registration request; - - fork - :Create user account; - fork again - :Send verification email; - end fork - - :Show success message; - :Auto-login with JWT tokens; -} - -partition "Email Verification" { - :User opens email; - :Click verification link; - - if (Link valid & not expired?) then (yes) - :Mark email as verified; - :Show success notification; - else (no) - :Show error: "Link expired"; - :Offer resend option; - endif -} - -partition "Profile Completion" { - :Navigate to profile; - - if (Profile complete?) then (no) - :Prompt to complete profile: - - Profile photo (optional) - - Date of birth - - Address; - - :Save profile updates; - endif -} - -partition "Biometric Enrollment" { - :Show enrollment prompt: - "Secure your account with - face recognition"; - - if (User agrees?) then (yes) - :Navigate to enrollment screen; - - repeat - :Request camera permission; - - if (Permission granted?) then (no) - :Show permission explanation; - :Request again; - stop - endif - - :Show camera preview; - :Display face position guide; - - :User captures face photo; - - :Validate image quality; - - repeat while (Quality acceptable?) is (no) - ->yes; - - :Extract face embedding; - :Store biometric data; - - :Show success: - "Face enrolled successfully!"; - else (no) - :Show "Skip for now" option; - note right - User can enroll later - from settings - end note - endif -} - -partition "Onboarding Complete" { - :Show welcome tour; - :Highlight key features; - :Navigate to home screen; -} - -stop - -@enduml -``` - -### 5.2 Face Verification Decision Activity - -```plantuml -@startuml verification_decision_activity - -start - -:Receive verification request; - -partition "Pre-Verification Checks" { - if (User exists?) then (no) - :Return 404 Not Found; - stop - endif - - if (User is active?) then (no) - :Return 403 Forbidden\n"Account suspended"; - stop - endif - - if (User has biometric enrolled?) then (no) - :Return 400 Bad Request\n"No biometric data"; - stop - endif - - :Check rate limit; - - if (Rate limit exceeded?) then (yes) - :Return 429 Too Many Requests; - stop - endif -} - -partition "Liveness Detection" { - if (Liveness required?) then (yes) - :Generate liveness puzzle; - :Return puzzle to client; - - :Wait for liveness verification; - - if (Liveness confirmed?) then (no) - :Log liveness failure; - :Return 403 Forbidden\n"Liveness check failed"; - stop - endif - endif -} - -partition "Image Processing" { - :Receive face image; - - fork - :Validate image format; - fork again - :Check file size; - fork again - :Validate image dimensions; - end fork - - if (Image valid?) then (no) - :Return 400 Bad Request\n"Invalid image"; - stop - endif - - :Forward to Biometric Processor; -} - -partition "Quality Assessment" { - :Calculate quality metrics; - - if (Sharpness < 40?) then (yes) - :Return error: "Image too blurry"; - stop - endif - - if (Brightness < 30 OR > 80?) then (yes) - :Return error: "Poor lighting"; - stop - endif - - if (Face size < 50%?) then (yes) - :Return error: "Face too small"; - stop - endif -} - -partition "Face Detection" { - :Detect faces in image; - - if (Faces detected?) then (== 0) - :Return error: "No face detected"; - stop - elseif (> 1) - :Return error: "Multiple faces"; - stop - endif -} - -partition "Embedding Extraction & Comparison" { - :Extract embedding from image; - - :Retrieve stored embedding(s); - - if (Primary biometric exists?) then (yes) - :Use primary embedding; - else (no) - :Use most recent active embedding; - endif - - :Calculate cosine distance; - - if (Distance < threshold?) then (yes) - :Set verified = true; - :Calculate confidence = 1 - distance; - else (no) - :Set verified = false; - :Calculate confidence; - endif -} - -partition "Post-Verification Actions" { - if (Verified?) then (yes) - fork - :Increment verification_count; - fork again - :Update last_verified_at; - fork again - :Reset failed_verification_count; - fork again - :Log successful verification; - fork again - :Publish "user.verified" event; - end fork - - :Return success response: - { - verified: true, - confidence: 0.92, - message: "Verified successfully" - }; - else (no) - fork - :Increment failed_verification_count; - fork again - :Log failed verification; - end fork - - if (Failed count > 5?) then (yes) - :Lock user account; - :Send security alert; - endif - - :Return failure response: - { - verified: false, - confidence: 0.45, - message: "Face does not match" - }; - endif -} - -stop - -@enduml -``` - -### 5.3 Tenant Management Activity - -```plantuml -@startuml tenant_management_activity - -start - -:System Admin logs in; - -partition "Tenant Creation" { - :Navigate to "Create Tenant"; - - :Enter tenant details: - - Organization name - - Domain (optional) - - Contact email - - Subscription plan; - - :Validate input; - - if (Slug available?) then (no) - :Show error: "Name taken"; - stop - endif - - fork - :Create tenant in shared schema; - fork again - :Create dedicated schema\n"tenant_{slug}"; - fork again - :Copy schema structure; - fork again - :Insert default roles\nand permissions; - fork again - :Generate API credentials; - end fork - - :Send welcome email to tenant; - - :Show tenant dashboard; -} - -partition "Tenant Configuration" { - :Tenant Admin logs in; - - repeat - :View current configuration; - - if (Need to change settings?) then (yes) - :Select setting to modify: - |Settings| - - Subscription plan - - User quota - - Feature flags - - Security policies - - Branding - - Notification settings; - - :Update configuration; - - if (Requires approval?) then (yes) - :Submit change request; - :Notify system admin; - - :System admin reviews; - - if (Approved?) then (yes) - :Apply changes; - else (no) - :Notify tenant admin; - endif - else (no) - :Apply changes immediately; - endif - - :Log configuration change; - endif - repeat while (More changes?) is (yes) - ->no; -} - -partition "Usage Monitoring" { - :View tenant dashboard; - - fork - :Show current user count; - fork again - :Show API call statistics; - fork again - :Show storage usage; - fork again - :Show verification metrics; - end fork - - if (Approaching quota limits?) then (yes) - :Show warning notification; - - if (Upgrade offered?) then (yes) - :Initiate upgrade process; - - :Select new plan; - :Process payment; - :Update subscription; - :Increase quotas; - - :Send confirmation; - endif - endif -} - -partition "Tenant Suspension/Deletion" { - if (Suspend tenant?) then (yes) - :System admin suspends; - - fork - :Set is_active = false; - fork again - :Revoke all active sessions; - fork again - :Notify tenant admin; - fork again - :Log suspension event; - end fork - - :All access blocked; - endif - - if (Delete tenant?) then (yes) - :Confirm deletion; - - if (Data retention required?) then (yes) - :Export tenant data; - :Store in archive; - endif - - fork - :Soft delete tenant record; - fork again - :Mark schema for cleanup; - fork again - :Revoke all credentials; - fork again - :Cancel subscription; - fork again - :Send deletion confirmation; - end fork - endif -} - -stop - -@enduml -``` - -### 5.4 Biometric Re-enrollment Activity - -```plantuml -@startuml biometric_reenrollment_activity - -start - -:User initiates re-enrollment; - -partition "Reason Determination" { - if (Why re-enroll?) then (Quality improvement) - :User wants better quality; - elseif (Appearance changed) - :Significant change: - - Weight loss/gain - - Surgery - - Aging; - elseif (Failed verifications) - :Multiple verification failures; - elseif (Security concern) - :Suspected compromise; - elseif (Upgrade model) - :New model available; - endif -} - -partition "Pre-Enrollment Validation" { - :Retrieve existing biometric data; - - if (Active biometric exists?) then (no) - :Redirect to initial enrollment; - stop - endif - - :Check re-enrollment cooldown; - - if (Too soon since last enrollment?) then (yes) - :Show warning: - "Please wait 24 hours - between enrollments"; - - if (Admin override?) then (no) - stop - endif - endif - - :Require re-authentication; - - if (Password verified?) then (no) - :Return to login; - stop - endif -} - -partition "Capture New Biometric" { - :Show camera interface; - - repeat - :Capture face image; - :Validate quality; - repeat while (Quality < existing?) is (yes) - ->better; - - :Extract new embedding; -} - -partition "Comparison with Existing" { - :Compare new vs. old embedding; - - if (Similarity > 0.5?) then (yes) - :Likely same person; - :Proceed with re-enrollment; - else (no) - :Suspiciously different; - - if (Admin approval required?) then (yes) - :Create approval request; - :Notify admin; - - :Wait for admin review; - - if (Approved?) then (no) - :Reject re-enrollment; - :Log security event; - stop - endif - endif - endif -} - -partition "Version Management" { - :Create new biometric_data record: - - version = old_version + 1 - - previous_version_id = old_id; - - :Store new embedding; - - if (Keep old version?) then (yes) - :Archive old biometric: - - Set is_active = false - - Keep for audit; - else (no) - :Delete old biometric; - endif - - :Update user record: - - enrolled_at = NOW() - - Set new as primary; -} - -partition "Testing New Biometric" { - :Prompt user: - "Test new enrollment?"; - - if (User agrees?) then (yes) - :Perform test verification; - - repeat - :Capture test image; - :Verify against new embedding; - - if (Verified successfully?) then (yes) - :Show success message; - else (no) - :Show failure; - - if (Rollback?) then (yes) - :Restore old biometric; - :Delete new biometric; - stop - endif - endif - repeat while (Try again?) is (yes) - endif -} - -partition "Finalization" { - fork - :Log re-enrollment event; - fork again - :Update verification logs; - fork again - :Notify user via email; - fork again - :Update analytics; - end fork - - :Show success screen: - "Biometric updated successfully - Quality improved: 75 → 92"; -} - -stop - -@enduml -``` - ---- - -**This file contains:** -- ER Diagrams (2 variants) -- Class Diagrams (3 detailed diagrams) -- Sequence Diagrams (4 comprehensive flows) -- State Machine Diagrams (4 lifecycle diagrams) -- Activity Diagrams (4 complex processes) - -**Continue to PLANTUML_DIAGRAMS_PART2.md for:** -- Component Diagrams -- Deployment Diagrams -- Use Case Diagrams -- Additional Diagrams diff --git a/archive/2026-04-16/PLANTUML_DIAGRAMS_PART2.md b/archive/2026-04-16/PLANTUML_DIAGRAMS_PART2.md deleted file mode 100644 index a219eb8..0000000 --- a/archive/2026-04-16/PLANTUML_DIAGRAMS_PART2.md +++ /dev/null @@ -1,1728 +0,0 @@ -# FIVUCSAS - PlantUML Diagrams Collection (Part 2) - -**Document Version:** 2.0 -**Date:** November 4, 2025 -**Continuation of:** PLANTUML_DIAGRAMS.md - ---- - -## 6. Component Diagrams - -### 6.1 System-Wide Component Architecture - -```plantuml -@startuml system_components - -skinparam componentStyle rectangle -skinparam packageStyle rectangle - -package "API Gateway Layer" { - [NGINX Reverse Proxy] as nginx - [Rate Limiter] as rate_limiter - [Auth Middleware] as auth_middleware -} - -package "Identity Core API" { - component "Presentation Layer" { - [Auth Controller] as auth_ctrl - [User Controller] as user_ctrl - [Biometric Controller] as bio_ctrl - } - - component "Application Layer" { - [Auth Service] as auth_svc - [User Service] as user_svc - [Biometric Service] as bio_svc - } - - component "Domain Layer" { - [User Entity] as user_entity - [Biometric Entity] as bio_entity - [Repository Interfaces] as repo_interfaces - } - - component "Infrastructure Layer" { - [JPA Repositories] as jpa_repo - [JWT Service] as jwt_svc - [Password Encoder] as pwd_encoder - [HTTP Client] as http_client - } -} - -package "Biometric Processor (Python)" { - [Face API Endpoints] as face_api - [Liveness API Endpoints] as liveness_api - - [Face Recognition Service] as face_recognition - [Liveness Detection Service] as liveness_detection - [Quality Validator] as quality_validator - - [DeepFace Engine] as deepface - [MediaPipe Engine] as mediapipe -} - -package "Mobile/Desktop App (KMP)" { - [UI Layer (Compose)] as ui_layer - [ViewModel Layer] as vm_layer - [Repository Layer] as app_repo - [Camera Service] as camera_svc -} - -database "PostgreSQL 16" { - [Users Table] as users_table - [Biometric Data (pgvector)] as bio_table -} - -database "Redis 7" { - [Session Cache] as session_cache - [Rate Limit Cache] as rate_cache - [Message Queue] as message_queue -} - -' API Gateway Flow -nginx --> auth_middleware : forwards -auth_middleware --> rate_limiter : validates -rate_limiter --> auth_ctrl : allows -rate_limiter --> user_ctrl : allows -rate_limiter --> bio_ctrl : allows - -' Identity Core Internal Flow -auth_ctrl --> auth_svc -user_ctrl --> user_svc -bio_ctrl --> bio_svc - -auth_svc --> jwt_svc : generates tokens -auth_svc --> pwd_encoder : hashes passwords -user_svc --> jpa_repo : CRUD operations -bio_svc --> http_client : calls biometric API - -jpa_repo --> user_entity -jpa_repo --> bio_entity -jpa_repo ..> repo_interfaces : implements - -jpa_repo --> users_table : SQL -jpa_repo --> bio_table : pgvector queries -jwt_svc --> session_cache : stores sessions -rate_limiter --> rate_cache : checks limits -auth_svc --> message_queue : publishes events - -' Biometric Processor Flow -http_client --> face_api : REST -http_client --> liveness_api : REST - -face_api --> face_recognition -liveness_api --> liveness_detection -face_api --> quality_validator - -face_recognition --> deepface : uses models -liveness_detection --> mediapipe : facial landmarks - -' Mobile App Flow -camera_svc --> vm_layer : provides images -vm_layer --> ui_layer : updates state -app_repo --> nginx : HTTPS API calls -vm_layer --> app_repo : data requests - -@enduml -``` - -### 6.2 Identity Core API Internal Components - -```plantuml -@startuml identity_core_internal - -package "Presentation Layer" { - [Auth Controller] as auth_ctrl - [User Controller] as user_ctrl - [Biometric Controller] as bio_ctrl - [Role Controller] as role_ctrl - [Tenant Controller] as tenant_ctrl -} - -package "Application Layer" { - [Auth Service] as auth_svc - [User Service] as user_svc - [Biometric Service] as bio_svc - [Role Service] as role_svc - [Tenant Service] as tenant_svc - [Email Service] as email_svc - [SMS Service] as sms_svc -} - -package "Domain Layer" { - [User Entity] as user_entity - [Role Entity] as role_entity - [BiometricData Entity] as bio_entity - [Session Entity] as session_entity - [Tenant Entity] as tenant_entity - - [User Repository Interface] as user_repo_i - [Role Repository Interface] as role_repo_i - [Biometric Repository Interface] as bio_repo_i -} - -package "Infrastructure Layer" { - [JPA User Repository] as user_repo - [JPA Role Repository] as role_repo - [JPA Biometric Repository] as bio_repo - [Redis Session Repository] as session_repo - - [JWT Service] as jwt - [Password Encoder] as pwd_encoder - [Biometric Client] as bio_client - [Email Provider] as email_provider - [SMS Provider] as sms_provider -} - -package "Cross-Cutting Concerns" { - [Exception Handler] as exc_handler - [Security Config] as security - [Logging Aspect] as logging - [Metrics Collector] as metrics - [Audit Interceptor] as audit -} - -' Controller -> Service -auth_ctrl --> auth_svc -user_ctrl --> user_svc -bio_ctrl --> bio_svc -role_ctrl --> role_svc -tenant_ctrl --> tenant_svc - -' Service -> Service -auth_svc --> email_svc -user_svc --> email_svc -auth_svc --> sms_svc - -' Service -> Repository Interface -auth_svc --> user_repo_i -user_svc --> user_repo_i -bio_svc --> bio_repo_i -role_svc --> role_repo_i -tenant_svc --> user_repo_i - -' Service -> Infrastructure -auth_svc --> jwt -auth_svc --> pwd_encoder -auth_svc --> session_repo -bio_svc --> bio_client -email_svc --> email_provider -sms_svc --> sms_provider - -' Repository Interface -> Repository Impl -user_repo_i <|.. user_repo -role_repo_i <|.. role_repo -bio_repo_i <|.. bio_repo - -' Repository -> Entity -user_repo --> user_entity -role_repo --> role_entity -bio_repo --> bio_entity - -' Cross-cutting -exc_handler ..> auth_ctrl : handles -exc_handler ..> user_ctrl : handles -security ..> auth_ctrl : secures -logging ..> auth_svc : logs -logging ..> user_svc : logs -metrics ..> auth_svc : measures -audit ..> user_svc : audits - -note right of bio_client - WebClient to Biometric - Processor on port 8001 -end note - -note bottom of user_repo - Uses Spring Data JPA - Custom queries for - complex operations -end note - -@enduml -``` - -### 6.3 Biometric Processor Internal Components - -```plantuml -@startuml biometric_processor_internal - -package "API Layer" { - [Face Endpoints] as face_api - [Liveness Endpoints] as liveness_api - [Health Endpoint] as health_api -} - -package "Service Layer" { - [Face Recognition Service] as face_svc - [Liveness Detection Service] as liveness_svc - [Image Quality Service] as quality_svc - [Person Manager Service] as person_svc -} - -package "Core ML Layer" { - [DeepFace Wrapper] as deepface - [MediaPipe Wrapper] as mediapipe - [OpenCV Utils] as opencv - [Model Manager] as model_mgr -} - -package "Models" { - [VGG-Face Model] as vgg - [ArcFace Model] as arcface - [Facenet Model] as facenet - [RetinaFace Detector] as retinaface -} - -package "Utilities" { - [Image Preprocessor] as preprocessor - [Vector Operations] as vector_ops - [File Handler] as file_handler - [Config Manager] as config - [Logger] as logger -} - -package "Data Models" { - [FaceEmbedding] as embedding - [VerificationResult] as verification - [QualityMetrics] as quality - [BiometricPuzzle] as puzzle -} - -' API -> Service -face_api --> face_svc -face_api --> quality_svc -liveness_api --> liveness_svc - -' Service -> Core ML -face_svc --> deepface -face_svc --> opencv -quality_svc --> opencv -liveness_svc --> mediapipe -person_svc --> face_svc - -' Core ML -> Models -deepface --> model_mgr -model_mgr --> vgg -model_mgr --> arcface -model_mgr --> facenet -deepface --> retinaface - -' Service -> Utilities -face_svc --> preprocessor -face_svc --> vector_ops -face_svc --> file_handler -liveness_svc --> file_handler -quality_svc --> preprocessor - -face_svc --> config -liveness_svc --> config -quality_svc --> config - -face_api --> logger -face_svc --> logger -liveness_svc --> logger - -' Service -> Data Models -face_svc ..> embedding : creates -face_svc ..> verification : creates -quality_svc ..> quality : creates -liveness_svc ..> puzzle : creates - -note right of model_mgr - Lazy loading of models - Cache in memory - GPU acceleration if available -end note - -note bottom of deepface - Abstraction over DeepFace library - Handles model loading, inference - Vector extraction -end note - -@enduml -``` - ---- - -## 7. Deployment Diagrams - -### 7.1 Production Kubernetes Deployment - -```plantuml -@startuml kubernetes_deployment - -skinparam componentStyle rectangle - -node "Kubernetes Cluster" { - - package "Ingress Layer" { - [NGINX Ingress Controller] as ingress - [Cert Manager] as cert_manager - } - - package "Application Namespace" { - node "Identity API Pod 1" { - [Identity API Container] as identity1 - } - node "Identity API Pod 2" { - [Identity API Container] as identity2 - } - node "Identity API Pod 3" { - [Identity API Container] as identity3 - } - - [Identity Service\n(ClusterIP)] as identity_svc - [Horizontal Pod Autoscaler] as hpa - - node "Biometric Pod 1" { - [Biometric Processor] as bio1 - } - node "Biometric Pod 2" { - [Biometric Processor] as bio2 - } - - [Biometric Service\n(ClusterIP)] as bio_svc - } - - package "Data Namespace" { - node "PostgreSQL Master" { - [PostgreSQL 16] as postgres_master - database "Persistent Volume\n(100Gi SSD)" as postgres_pv - } - - node "PostgreSQL Replica 1" { - [PostgreSQL 16 Replica] as postgres_replica1 - } - - node "PostgreSQL Replica 2" { - [PostgreSQL 16 Replica] as postgres_replica2 - } - - [PostgreSQL Service\n(ClusterIP)] as postgres_svc - - node "Redis Master" { - [Redis 7] as redis_master - } - - node "Redis Replica 1" { - [Redis 7 Replica] as redis_replica1 - } - - [Redis Service\n(ClusterIP)] as redis_svc - } - - package "Monitoring Namespace" { - [Prometheus] as prometheus - [Grafana] as grafana - [Jaeger] as jaeger - } -} - -cloud "External Access" { - [Users] as users - [Mobile Apps] as mobile -} - -' Connections -users --> ingress : HTTPS -mobile --> ingress : HTTPS -ingress --> identity_svc : routes /api/v1/auth, /api/v1/users -ingress --> bio_svc : routes /api/v1/face - -identity_svc --> identity1 -identity_svc --> identity2 -identity_svc --> identity3 - -bio_svc --> bio1 -bio_svc --> bio2 - -hpa ..> identity1 : scales -hpa ..> identity2 : scales -hpa ..> identity3 : scales - -identity1 --> postgres_svc : SQL queries -identity2 --> postgres_svc : SQL queries -identity3 --> postgres_svc : SQL queries - -identity1 --> redis_svc : cache/sessions -identity2 --> redis_svc : cache/sessions -identity3 --> redis_svc : cache/sessions - -identity1 --> bio_svc : REST calls -identity2 --> bio_svc : REST calls -identity3 --> bio_svc : REST calls - -postgres_svc --> postgres_master : write -postgres_svc --> postgres_replica1 : read -postgres_svc --> postgres_replica2 : read - -postgres_master ..> postgres_pv : mounts - -redis_svc --> redis_master : write -redis_svc --> redis_replica1 : read - -prometheus --> identity_svc : scrapes metrics -prometheus --> bio_svc : scrapes metrics -prometheus --> postgres_svc : scrapes metrics -prometheus --> redis_svc : scrapes metrics - -grafana --> prometheus : queries -jaeger <-- identity1 : traces -jaeger <-- identity2 : traces -jaeger <-- identity3 : traces - -@enduml -``` - -### 7.2 Development Environment Deployment - -```plantuml -@startuml development_deployment - -node "Developer Workstation" { - [IntelliJ IDEA] as ide - [Android Studio] as android_studio - [VS Code] as vscode - [Docker Desktop] as docker_desktop -} - -node "Local Docker Environment" { - rectangle "Docker Compose" { - component "identity-core-api\n:8080" as identity_local - component "biometric-processor\n:8001" as biometric_local - component "PostgreSQL\n:5432" as postgres_local - component "Redis\n:6379" as redis_local - component "Mailhog\n:8025" as mailhog - } -} - -node "Mobile Emulators" { - [Android Emulator] as android_emu - [iOS Simulator] as ios_sim -} - -node "Desktop App" { - [Desktop Application\n(Compose)] as desktop_app -} - -cloud "External Services" { - [GitHub] as github - [Docker Hub] as dockerhub -} - -' IDE connections -ide --> identity_local : Debug\nGradle bootRun -vscode --> biometric_local : Debug\nuvicorn -android_studio --> android_emu : Deploy APK - -' Docker Compose -identity_local --> postgres_local : JDBC -identity_local --> redis_local : Redis Protocol -identity_local --> mailhog : SMTP -identity_local --> biometric_local : REST - -' Mobile/Desktop connections -android_emu --> identity_local : HTTP (localhost) -ios_sim --> identity_local : HTTP (localhost) -desktop_app --> identity_local : HTTP (localhost) - -' External services -ide --> github : Git push -docker_desktop --> dockerhub : Pull images - -note right of mailhog - **Development Email Testing:** - - Captures all emails - - Web UI at localhost:8025 - - No external email sending -end note - -note bottom of docker_desktop - **Docker Compose:** - docker-compose.dev.yml - - Hot reload enabled - - Debug ports exposed - - Volume mounts for code -end note - -@enduml -``` - -### 7.3 Multi-Region Production Deployment - -```plantuml -@startuml multi_region_deployment - -skinparam componentStyle rectangle - -cloud "US-East-1 (Primary)" { - package "Production Stack" { - [API Gateway US] as api_gw_us - [Identity API Cluster (3 pods)] as identity_us - [Biometric Processor Cluster (2 pods)] as bio_us - database "PostgreSQL Primary" as db_us_primary - database "PostgreSQL Read Replica" as db_us_replica - database "Redis Cluster" as redis_us - } - - [S3 Bucket US] as s3_us - [CloudFront Distribution] as cloudfront_us -} - -cloud "EU-West-1 (Secondary)" { - package "EU Stack" { - [API Gateway EU] as api_gw_eu - [Identity API Cluster (2 pods)] as identity_eu - [Biometric Processor Cluster (2 pods)] as bio_eu - database "PostgreSQL Read Replica" as db_eu - database "Redis Cluster" as redis_eu - } - - [S3 Bucket EU] as s3_eu - [CloudFront Distribution] as cloudfront_eu -} - -cloud "AP-Southeast-1 (Tertiary)" { - package "APAC Stack" { - [API Gateway APAC] as api_gw_apac - [Identity API Cluster (2 pods)] as identity_apac - [Biometric Processor Cluster (2 pods)] as bio_apac - database "PostgreSQL Read Replica" as db_apac - database "Redis Cluster" as redis_apac - } - - [S3 Bucket APAC] as s3_apac -} - -[Route 53 Global DNS] as route53 -[WAF (Web Application Firewall)] as waf - -actor "US Users" as us_users -actor "EU Users" as eu_users -actor "APAC Users" as apac_users - -' Traffic Routing -us_users --> route53 : DNS query -eu_users --> route53 : DNS query -apac_users --> route53 : DNS query - -route53 --> waf : geolocation routing -waf --> api_gw_us : US traffic -waf --> api_gw_eu : EU traffic -waf --> api_gw_apac : APAC traffic - -' US Region Flow -api_gw_us --> identity_us -identity_us --> bio_us -identity_us --> db_us_primary : write -identity_us --> db_us_replica : read -identity_us --> redis_us -bio_us --> s3_us : store images -cloudfront_us --> s3_us - -' EU Region Flow -api_gw_eu --> identity_eu -identity_eu --> bio_eu -identity_eu --> db_eu : read -identity_eu --> redis_eu -bio_eu --> s3_eu : store images -cloudfront_eu --> s3_eu - -' APAC Region Flow -api_gw_apac --> identity_apac -identity_apac --> bio_apac -identity_apac --> db_apac : read -identity_apac --> redis_apac -bio_apac --> s3_apac : store images - -' Database Replication -db_us_primary ..> db_us_replica : streaming replication (sync) -db_us_primary ..> db_eu : logical replication (async) -db_us_primary ..> db_apac : logical replication (async) - -' Cross-Region Data -s3_us ..> s3_eu : S3 Cross-Region Replication -s3_us ..> s3_apac : S3 Cross-Region Replication - -note right of route53 - Routing Policy: - - Geolocation routing for optimal latency - - Health checks on all regions - - Automatic failover to nearest healthy region - - Latency-based routing as fallback -end note - -note bottom of db_us_primary - Write operations only in US-East-1 - All other regions read-only - Replication lag typically <2 seconds -end note - -@enduml -``` - -### 7.4 High Availability Deployment - -```plantuml -@startuml ha_deployment - -skinparam componentStyle rectangle - -cloud "Region: US-East-1" { - node "Availability Zone 1a" { - [Load Balancer AZ-1a] as lb1 - [Identity API Pod 1] as api1 - [Biometric Processor Pod 1] as bio1 - database "PostgreSQL Primary" as db1 - database "Redis Primary" as redis1 - } - - node "Availability Zone 1b" { - [Load Balancer AZ-1b] as lb2 - [Identity API Pod 2] as api2 - [Biometric Processor Pod 2] as bio2 - database "PostgreSQL Replica" as db2 - database "Redis Replica" as redis2 - } - - node "Availability Zone 1c" { - [Load Balancer AZ-1c] as lb3 - [Identity API Pod 3] as api3 - [Biometric Processor Pod 3] as bio3 - database "PostgreSQL Replica" as db3 - database "Redis Replica" as redis3 - } - - [Global Load Balancer\n(Route 53)] as global_lb -} - -cloud "Region: EU-West-1" { - node "AZ eu-west-1a" { - [Identity API Pod EU-1] as api_eu1 - database "PostgreSQL Replica EU" as db_eu1 - } - - node "AZ eu-west-1b" { - [Identity API Pod EU-2] as api_eu2 - database "PostgreSQL Replica EU-2" as db_eu2 - } -} - -cloud "Monitoring & Backup" { - [CloudWatch] as cloudwatch - [S3 Backup Storage] as s3_backup - [RDS Snapshots] as rds_snapshots -} - -actor "Users" as users - -' Traffic Flow -users --> global_lb : HTTPS -global_lb --> lb1 : primary region -global_lb ..> api_eu1 : failover to EU - -lb1 --> api1 -lb2 --> api2 -lb3 --> api3 - -api1 --> bio1 : REST -api2 --> bio2 : REST -api3 --> bio3 : REST - -api1 --> db1 : write -api2 --> db1 : write -api3 --> db1 : write - -api1 --> db2 : read -api2 --> db2 : read -api3 --> db3 : read - -api1 --> redis1 : cache -api2 --> redis1 : cache -api3 --> redis1 : cache - -db1 ..> db2 : replication -db1 ..> db3 : replication -db1 ..> db_eu1 : cross-region replication -db1 ..> db_eu2 : cross-region replication - -redis1 ..> redis2 : replication -redis1 ..> redis3 : replication - -db1 --> rds_snapshots : automated backups -db1 --> s3_backup : continuous archival - -api1 --> cloudwatch : logs/metrics -api2 --> cloudwatch : logs/metrics -api3 --> cloudwatch : logs/metrics - -api_eu1 --> db_eu1 : read -api_eu2 --> db_eu2 : read - -note right of global_lb - Route 53 Health Checks: - - Primary: US-East-1 - - Failover: EU-West-1 - - Latency-based routing -end note - -note right of db1 - PostgreSQL Configuration: - - Synchronous replication to AZ-1b - - Async replication to AZ-1c - - Cross-region async to EU - - RPO: <5 minutes - - RTO: <10 minutes -end note - -@enduml -``` - ---- - -## 8. Use Case Diagrams - -### 8.1 End User Use Cases - -```plantuml -@startuml end_user_use_cases - -left to right direction - -actor "End User" as user -actor "Mobile App" as mobile -actor "Desktop Kiosk" as kiosk - -rectangle "FIVUCSAS Platform" { - - rectangle "Authentication" { - usecase "Register Account" as UC1 - usecase "Login with Password" as UC2 - usecase "Login with Face" as UC3 - usecase "Reset Password" as UC4 - usecase "Logout" as UC5 - usecase "Verify Email" as UC6 - } - - rectangle "Biometric Management" { - usecase "Enroll Face" as UC7 - usecase "Complete Liveness Check" as UC8 - usecase "View Biometric Status" as UC9 - usecase "Re-enroll Face" as UC10 - usecase "Delete Biometric" as UC11 - } - - rectangle "Profile Management" { - usecase "View Profile" as UC12 - usecase "Update Profile" as UC13 - usecase "Change Password" as UC14 - usecase "Upload Profile Photo" as UC15 - usecase "Manage Preferences" as UC16 - } - - rectangle "Verification" { - usecase "Verify Identity\nat Door" as UC17 - usecase "Verify for Login" as UC18 - usecase "View Verification\nHistory" as UC19 - } - - rectangle "Notifications" { - usecase "Receive Email\nNotifications" as UC20 - usecase "Receive Push\nNotifications" as UC21 - usecase "Configure\nNotification Prefs" as UC22 - } -} - -' User to Authentication -user --> UC1 -user --> UC2 -user --> UC3 -user --> UC4 -user --> UC5 -user --> UC6 - -' User to Biometric -user --> UC7 -user --> UC8 -user --> UC9 -user --> UC10 -user --> UC11 - -' User to Profile -user --> UC12 -user --> UC13 -user --> UC14 -user --> UC15 -user --> UC16 - -' User to Verification -user --> UC17 : via kiosk -user --> UC18 : via mobile -user --> UC19 - -' Notifications -user <-- UC20 -user <-- UC21 -user --> UC22 - -' Include relationships -UC1 ..> UC6 : <> -UC2 ..> UC5 : <> -UC3 ..> UC5 : <> -UC7 ..> UC8 : <> -UC17 ..> UC8 : <> - -' Extend relationships -UC3 ..> UC17 : <> -UC10 ..> UC7 : <> - -note right of UC8 - **Liveness Check:** - Required for all - face-based authentication - to prevent spoofing attacks -end note - -note bottom of UC17 - **Physical Access:** - Used at building entry, - office doors, restricted areas -end note - -@enduml -``` - -### 8.2 Tenant Admin Use Cases - -```plantuml -@startuml tenant_admin_use_cases - -left to right direction - -actor "Tenant Admin" as admin -actor "System" as system - -rectangle "FIVUCSAS Platform" { - - rectangle "User Management" { - usecase "Create User" as UC1 - usecase "View All Users" as UC2 - usecase "Search Users" as UC3 - usecase "Update User" as UC4 - usecase "Deactivate User" as UC5 - usecase "Reactivate User" as UC6 - usecase "Delete User" as UC7 - usecase "Reset User Password" as UC8 - usecase "Unlock User Account" as UC9 - } - - rectangle "Role Management" { - usecase "Create Role" as UC10 - usecase "Assign Role to User" as UC11 - usecase "Remove Role from User" as UC12 - usecase "Update Role Permissions" as UC13 - usecase "View Role Hierarchy" as UC14 - } - - rectangle "Biometric Management" { - usecase "View User Biometrics" as UC15 - usecase "Force Biometric\nRe-enrollment" as UC16 - usecase "Delete User Biometric" as UC17 - usecase "View Biometric\nQuality Reports" as UC18 - } - - rectangle "Monitoring & Reports" { - usecase "View Dashboard" as UC19 - usecase "Generate User Report" as UC20 - usecase "View Verification Logs" as UC21 - usecase "Export Audit Logs" as UC22 - usecase "View System Statistics" as UC23 - usecase "Monitor Active Sessions" as UC24 - } - - rectangle "Configuration" { - usecase "Update Tenant Settings" as UC25 - usecase "Configure Security Policies" as UC26 - usecase "Manage API Keys" as UC27 - usecase "Configure Notifications" as UC28 - usecase "Set Verification Thresholds" as UC29 - } - - rectangle "Compliance" { - usecase "Download GDPR\nData Export" as UC30 - usecase "Process Data\nDeletion Request" as UC31 - usecase "View Consent Records" as UC32 - } -} - -' Admin to User Management -admin --> UC1 -admin --> UC2 -admin --> UC3 -admin --> UC4 -admin --> UC5 -admin --> UC6 -admin --> UC7 -admin --> UC8 -admin --> UC9 - -' Admin to Role Management -admin --> UC10 -admin --> UC11 -admin --> UC12 -admin --> UC13 -admin --> UC14 - -' Admin to Biometric Management -admin --> UC15 -admin --> UC16 -admin --> UC17 -admin --> UC18 - -' Admin to Monitoring -admin --> UC19 -admin --> UC20 -admin --> UC21 -admin --> UC22 -admin --> UC23 -admin --> UC24 - -' Admin to Configuration -admin --> UC25 -admin --> UC26 -admin --> UC27 -admin --> UC28 -admin --> UC29 - -' Admin to Compliance -admin --> UC30 -admin --> UC31 -admin --> UC32 - -' System actor -UC1 ..> UC8 : <> -system --> UC24 : auto-cleanup -system --> UC21 : auto-log - -' Include relationships -UC2 ..> UC3 : <> -UC4 ..> UC11 : <> -UC20 ..> UC21 : <> - -note right of UC26 - **Security Policies:** - - Password requirements - - Lockout thresholds - - Session timeout - - MFA enforcement - - Verification strictness -end note - -note bottom of UC30 - **GDPR Compliance:** - Admin can export all user - data upon request. - Must complete within 30 days. -end note - -@enduml -``` - -### 8.3 System Admin Use Cases - -```plantuml -@startuml system_admin_use_cases - -left to right direction - -actor "System Admin" as sysadmin -actor "DevOps" as devops - -rectangle "FIVUCSAS Platform" { - - rectangle "Tenant Management" { - usecase "Create Tenant" as UC1 - usecase "View All Tenants" as UC2 - usecase "Update Tenant Plan" as UC3 - usecase "Suspend Tenant" as UC4 - usecase "Activate Tenant" as UC5 - usecase "Delete Tenant" as UC6 - usecase "Manage Tenant Quotas" as UC7 - } - - rectangle "System Configuration" { - usecase "Configure Global\nSecurity Settings" as UC8 - usecase "Manage Feature Flags" as UC9 - usecase "Update System\nParameters" as UC10 - usecase "Configure Rate Limits" as UC11 - } - - rectangle "Monitoring & Diagnostics" { - usecase "View System Health" as UC12 - usecase "Monitor Service Metrics" as UC13 - usecase "View Error Logs" as UC14 - usecase "Analyze Performance" as UC15 - usecase "View Distributed Traces" as UC16 - usecase "Check Database Status" as UC17 - } - - rectangle "User Support" { - usecase "Search Across Tenants" as UC18 - usecase "Unlock Any Account" as UC19 - usecase "Reset MFA" as UC20 - usecase "Investigate Security\nIncident" as UC21 - usecase "View User Activity" as UC22 - } - - rectangle "System Maintenance" { - usecase "Run Database Migration" as UC23 - usecase "Clear Cache" as UC24 - usecase "Restart Services" as UC25 - usecase "Trigger Manual Backup" as UC26 - usecase "Cleanup Old Sessions" as UC27 - } - - rectangle "Model Management" { - usecase "Update Biometric Models" as UC28 - usecase "Configure Model\nParameters" as UC29 - usecase "A/B Test Models" as UC30 - usecase "View Model Performance" as UC31 - } - - rectangle "Security & Compliance" { - usecase "Review Audit Logs" as UC32 - usecase "Manage Admin Accounts" as UC33 - usecase "Configure IP Whitelist" as UC34 - usecase "Manage SSL Certificates" as UC35 - usecase "Review Security Alerts" as UC36 - } -} - -' System Admin connections -sysadmin --> UC1 -sysadmin --> UC2 -sysadmin --> UC3 -sysadmin --> UC4 -sysadmin --> UC5 -sysadmin --> UC6 -sysadmin --> UC7 -sysadmin --> UC8 -sysadmin --> UC9 -sysadmin --> UC10 -sysadmin --> UC11 -sysadmin --> UC12 -sysadmin --> UC13 -sysadmin --> UC14 -sysadmin --> UC18 -sysadmin --> UC19 -sysadmin --> UC20 -sysadmin --> UC21 -sysadmin --> UC22 -sysadmin --> UC28 -sysadmin --> UC29 -sysadmin --> UC30 -sysadmin --> UC31 -sysadmin --> UC32 -sysadmin --> UC33 -sysadmin --> UC34 -sysadmin --> UC35 -sysadmin --> UC36 - -' DevOps connections -devops --> UC12 -devops --> UC13 -devops --> UC14 -devops --> UC15 -devops --> UC16 -devops --> UC17 -devops --> UC23 -devops --> UC24 -devops --> UC25 -devops --> UC26 -devops --> UC27 - -' Include/Extend relationships -UC4 ..> UC6 : <> -UC3 ..> UC7 : <> -UC21 ..> UC22 : <> -UC21 ..> UC32 : <> - -note right of UC1 - **Tenant Creation:** - - Provision isolated schema - - Create admin account - - Set initial quotas - - Generate API credentials -end note - -note bottom of UC23 - **Database Migrations:** - Zero-downtime migrations - using Flyway or Liquibase - Automatic rollback on failure -end note - -note right of UC30 - **A/B Testing:** - Compare VGG-Face vs ArcFace - Measure accuracy & performance - Gradual rollout strategy -end note - -@enduml -``` - -### 8.4 External System Integration Use Cases - -```plantuml -@startuml external_system_use_cases - -left to right direction - -actor "Door Controller" as door -actor "HR System" as hr -actor "Mobile App" as mobile -actor "Third-Party App" as thirdparty - -rectangle "FIVUCSAS Platform API" { - - rectangle "Public API" { - usecase "Authenticate via API Key" as UC1 - usecase "Get API Documentation" as UC2 - usecase "Check API Health" as UC3 - } - - rectangle "User Management API" { - usecase "Create User via API" as UC4 - usecase "Sync User Data" as UC5 - usecase "Bulk Import Users" as UC6 - usecase "Get User Details" as UC7 - usecase "Update User via API" as UC8 - } - - rectangle "Biometric API" { - usecase "Enroll Face via API" as UC9 - usecase "Verify Face via API" as UC10 - usecase "Check Enrollment\nStatus" as UC11 - } - - rectangle "Verification API" { - usecase "Request Door Access" as UC12 - usecase "Verify at Kiosk" as UC13 - usecase "Authenticate User" as UC14 - usecase "Get Verification Result" as UC15 - } - - rectangle "Webhook API" { - usecase "Register Webhook" as UC16 - usecase "Receive User Created\nEvent" as UC17 - usecase "Receive Verification\nEvent" as UC18 - usecase "Receive Enrollment\nEvent" as UC19 - } - - rectangle "Analytics API" { - usecase "Get Tenant Statistics" as UC20 - usecase "Get Verification Metrics" as UC21 - usecase "Export Audit Logs" as UC22 - } -} - -' Door Controller use cases -door --> UC1 -door --> UC12 -door --> UC15 - -' HR System use cases -hr --> UC1 -hr --> UC4 -hr --> UC5 -hr --> UC6 -hr --> UC7 -hr --> UC8 -hr --> UC16 - -' Mobile App use cases -mobile --> UC1 -mobile --> UC9 -mobile --> UC10 -mobile --> UC14 - -' Third-party App use cases -thirdparty --> UC1 -thirdparty --> UC2 -thirdparty --> UC3 -thirdparty --> UC7 -thirdparty --> UC11 -thirdparty --> UC20 -thirdparty --> UC21 -thirdparty --> UC22 - -' Webhook subscriptions -hr <-- UC17 -hr <-- UC18 -hr <-- UC19 -thirdparty <-- UC17 - -' Include relationships -UC4 ..> UC1 : <> -UC5 ..> UC1 : <> -UC9 ..> UC1 : <> -UC10 ..> UC1 : <> -UC12 ..> UC10 : <> - -note right of UC1 - **API Key Auth:** - - Bearer token authentication - - Rate limiting per key - - Scope-based permissions - - Usage tracking -end note - -note bottom of UC12 - **Door Access Flow:** - 1. Capture face at kiosk - 2. Call verify API - 3. Check result - 4. Grant/deny access - Response time: <2 seconds -end note - -note right of UC16 - **Webhook System:** - - HTTP POST to endpoint - - Retry on failure (3x) - - HMAC signature verification - - Event types: user.*, verification.* -end note - -@enduml -``` - ---- - -## 9. Additional Diagrams - -### 9.1 Data Flow Diagram - Face Verification - -```plantuml -@startuml data_flow_verification - -!define RECTANGLE class - -skinparam component { - BackgroundColor<> LightBlue - BackgroundColor<> LightGreen - BackgroundColor<> LightYellow -} - -RECTANGLE "User" as user <> -RECTANGLE "Mobile App" as app <> -RECTANGLE "API Gateway" as gateway <> -RECTANGLE "Identity API" as identity <> -RECTANGLE "Biometric Processor" as biometric <> -RECTANGLE "Database" as db <> -RECTANGLE "Redis" as redis <> - -user -> app : 1.0 User face image -app -> gateway : 2.0 Verification request\n+ image bytes -gateway -> identity : 3.0 Authenticated request -identity -> redis : 4.0 Check rate limit -redis --> identity : 4.1 Limit status -identity -> db : 5.0 Query stored embedding -db --> identity : 5.1 Embedding vector (512-D) -identity -> biometric : 6.0 Image + stored embedding -biometric -> biometric : 7.0 Extract new embedding -biometric -> biometric : 8.0 Calculate distance -biometric --> identity : 9.0 Verification result\n{verified, confidence} -identity -> db : 10.0 Log verification attempt -identity -> redis : 11.0 Publish event -identity --> gateway : 12.0 Response DTO -gateway --> app : 13.0 JSON response -app --> user : 14.0 Display result - -note right of biometric - **Processing:** - - Face detection - - Embedding extraction (VGG-Face) - - Cosine similarity calculation - - Threshold comparison (0.30) -end note - -note bottom of db - **Data Stored:** - - User metadata - - Biometric embeddings (encrypted) - - Verification logs - - Audit trail -end note - -@enduml -``` - -### 9.2 Network Architecture Diagram - -```plantuml -@startuml network_architecture - -skinparam componentStyle rectangle - -package "VPC (10.0.0.0/16)" { - - package "Public Subnets (10.0.1.0/24, 10.0.2.0/24)" { - [Internet Gateway] as igw - [NAT Gateway AZ-1] as nat1 - [NAT Gateway AZ-2] as nat2 - [Application Load Balancer] as alb - - [Bastion Host] as bastion - } - - package "Private App Subnet AZ-1 (10.0.10.0/24)" { - [Identity API Pod 1] as api1 - [Identity API Pod 2] as api2 - [Biometric Processor Pod 1] as bio1 - } - - package "Private App Subnet AZ-2 (10.0.11.0/24)" { - [Identity API Pod 3] as api3 - [Identity API Pod 4] as api4 - [Biometric Processor Pod 2] as bio2 - } - - package "Private Data Subnet AZ-1 (10.0.20.0/24)" { - database "PostgreSQL Primary" as db1 - database "Redis Master" as redis1 - } - - package "Private Data Subnet AZ-2 (10.0.21.0/24)" { - database "PostgreSQL Replica" as db2 - database "Redis Replica" as redis2 - } - - package "Security Groups" { - [ALB Security Group\nAllow: 80, 443 from 0.0.0.0/0] as sg_alb - [App Security Group\nAllow: 8080 from ALB SG] as sg_app - [DB Security Group\nAllow: 5432 from App SG] as sg_db - [Redis Security Group\nAllow: 6379 from App SG] as sg_redis - [Bastion Security Group\nAllow: 22 from Corp IP] as sg_bastion - } - - [VPC Flow Logs] as flow_logs - [Network ACL] as nacl -} - -cloud "Internet" { - actor "Users" as users -} - -cloud "AWS Services" { - [S3 (via VPC Endpoint)] as s3 - [CloudWatch (via VPC Endpoint)] as cloudwatch -} - -' Traffic Flow -users --> igw : HTTPS (443) -igw --> alb : forwards -alb --> api1 : HTTP (8080) -alb --> api2 : HTTP (8080) -alb --> api3 : HTTP (8080) -alb --> api4 : HTTP (8080) - -api1 --> nat1 : outbound internet -api2 --> nat1 : outbound internet -api3 --> nat2 : outbound internet -api4 --> nat2 : outbound internet - -api1 --> bio1 : HTTP (8001) -api2 --> bio1 : HTTP (8001) -api3 --> bio2 : HTTP (8001) -api4 --> bio2 : HTTP (8001) - -api1 --> db1 : PostgreSQL (5432) -api2 --> db1 : PostgreSQL (5432) -api3 --> db1 : PostgreSQL (5432) -api4 --> db1 : PostgreSQL (5432) - -api1 --> redis1 : Redis (6379) -api2 --> redis1 : Redis (6379) -api3 --> redis1 : Redis (6379) -api4 --> redis1 : Redis (6379) - -db1 ..> db2 : replication (5432) -redis1 ..> redis2 : replication (6379) - -api1 --> s3 : store files -api2 --> s3 : store files -api3 --> s3 : store files -api4 --> s3 : store files - -api1 --> cloudwatch : logs/metrics -api2 --> cloudwatch : logs/metrics - -bastion --> api1 : SSH debugging -bastion --> db1 : psql client - -alb -[hidden]-> sg_alb -api1 -[hidden]-> sg_app -db1 -[hidden]-> sg_db - -note right of sg_alb - Security Group Rules: - - ALB SG: - Inbound: 443 (0.0.0.0/0) - Outbound: 8080 (App SG) - - App SG: - Inbound: 8080 (ALB SG), 22 (Bastion SG) - Outbound: 5432 (DB SG), 6379 (Redis SG), 443 (0.0.0.0/0) - - DB SG: - Inbound: 5432 (App SG), 5432 (Bastion SG) - Outbound: None - - Redis SG: - Inbound: 6379 (App SG) - Outbound: None -end note - -note left of flow_logs - Monitoring & Compliance: - - VPC Flow Logs to S3 - - CloudWatch Logs - - GuardDuty threat detection - - AWS Config compliance - - Network ACLs for subnet isolation -end note - -@enduml -``` - -### 9.3 Security Architecture Diagram - -```plantuml -@startuml security_architecture - -skinparam componentStyle rectangle - -rectangle "Layer 1: Perimeter Security" { - [WAF (Web Application Firewall)] as waf - [DDoS Protection\n(AWS Shield)] as shield - [Rate Limiting] as rate_limit -} - -rectangle "Layer 2: Network Security" { - [VPC] as vpc - [Security Groups] as security_groups - [Network ACLs] as nacl - [Private Subnets] as private_subnet - [VPC Flow Logs] as flow_logs -} - -rectangle "Layer 3: Application Security" { - [API Gateway\n(NGINX)] as api_gateway - [JWT Validation] as jwt - [CORS Policy] as cors - [Input Validation] as input_validation - [HTTPS/TLS 1.3] as tls -} - -rectangle "Layer 4: Authentication & Authorization" { - [Spring Security] as spring_security - [Password Hashing\n(BCrypt)] as bcrypt - [JWT Service\n(HS512)] as jwt_service - [Multi-Factor Auth] as mfa - [Role-Based Access Control] as rbac - [Permission System] as permissions -} - -rectangle "Layer 5: Data Security" { - [Encryption at Rest\n(AES-256)] as encryption_rest - [Encryption in Transit\n(TLS 1.3)] as encryption_transit - [Database RLS\n(Row-Level Security)] as rls - [Multi-Tenancy Isolation] as multi_tenancy - [Data Masking] as masking - [Audit Logging] as audit -} - -rectangle "Layer 6: Secrets Management" { - [AWS Secrets Manager] as secrets_manager - [Environment Variables] as env_vars - [Vault Integration] as vault -} - -rectangle "Layer 7: Monitoring & Compliance" { - [CloudWatch Alarms] as alarms - [Security Audit Logs] as security_logs - [Intrusion Detection\n(GuardDuty)] as ids - [Compliance Reports\n(KVKK/GDPR)] as compliance - [Vulnerability Scanning] as vuln_scan -} - -actor "Attacker" as attacker -actor "Legitimate User" as user - -' Attack Flow (Blocked) -attacker --> shield : DDoS Attack -shield -[#red]-> waf : BLOCKED -attacker --> waf : SQL Injection -waf -[#red]-> attacker : BLOCKED -attacker --> rate_limit : Brute Force -rate_limit -[#red]-> attacker : BLOCKED - -' Legitimate Flow -user --> shield : Normal Request -shield --> waf : Allowed -waf --> rate_limit : Pass WAF Rules -rate_limit --> api_gateway : Within Limits - -api_gateway --> tls : HTTPS Only -tls --> jwt : Decrypt -jwt --> spring_security : Validate Token -spring_security --> rbac : Check Roles -rbac --> permissions : Check Permissions - -api_gateway --> input_validation : Sanitize Input -input_validation --> spring_security - -spring_security --> encryption_transit : Access DB -encryption_transit --> rls : Row Filtering -rls --> encryption_rest : Read Data -encryption_rest --> masking : Sensitive Fields -masking --> audit : Log Access - -spring_security --> secrets_manager : Get DB Credentials -jwt_service --> secrets_manager : Get JWT Secret - -security_groups --> private_subnet : Isolate Resources -nacl --> flow_logs : Log Traffic -flow_logs --> security_logs : Centralize - -alarms --> security_logs : Monitor -ids --> security_logs : Detect Threats -vuln_scan --> compliance : Automated Scans - -note right of waf - WAF Rules: - - Block SQL Injection - - Block XSS - - Block common exploits - - Rate limiting per IP - - Geo-blocking (optional) - - Bot detection -end note - -note right of spring_security - Authentication Flow: - 1. User submits credentials - 2. BCrypt verifies password - 3. JWT token generated (HS512) - 4. MFA challenge (if enabled) - 5. Roles & permissions loaded - 6. Access granted -end note - -note right of encryption_rest - Data Encryption: - - Database: AES-256 at rest - - Biometric embeddings: Encrypted column - - Backups: Encrypted with KMS - - File storage: S3 encryption -end note - -note right of multi_tenancy - Tenant Isolation: - - Separate schemas per tenant - - Row-Level Security (RLS) - - Tenant ID in JWT - - No cross-tenant queries - - Audit all tenant access -end note - -note bottom of compliance - Compliance Features: - - KVKK (Turkish GDPR) - - GDPR (EU) - - Data retention policies - - Right to be forgotten - - Consent management - - Audit trail (7 years) - - Encrypted PII -end note - -@enduml -``` - ---- - -## 10. Summary & Usage Guide - -### Diagram Categories - -1. **Entity-Relationship Diagrams** - Database schema visualization -2. **Class Diagrams** - Object-oriented design and relationships -3. **Sequence Diagrams** - Interaction flows over time -4. **State Machine Diagrams** - Lifecycle and transitions -5. **Activity Diagrams** - Business process flows -6. **Component Diagrams** - System structure and dependencies -7. **Deployment Diagrams** - Infrastructure and deployment -8. **Use Case Diagrams** - Functional requirements -9. **Data Flow Diagrams** - Information flow -10. **Network/Security Diagrams** - Infrastructure and security - -### How to Generate Diagrams - -**Option 1: Online PlantUML Editor** -``` -1. Visit: http://www.plantuml.com/plantuml/uml/ -2. Copy diagram code -3. Paste into editor -4. View or download PNG/SVG -``` - -**Option 2: VS Code Extension** -``` -1. Install "PlantUML" extension by jebbs -2. Create .puml file -3. Copy diagram code -4. Press Alt+D to preview -5. Right-click → Export to PNG/SVG -``` - -**Option 3: IntelliJ IDEA Plugin** -``` -1. Install "PlantUML integration" plugin -2. Create .puml file -3. Copy diagram code -4. View in tool window -5. Export as needed -``` - -**Option 4: Command Line** -```bash -# Install PlantUML -brew install plantuml # macOS -sudo apt install plantuml # Ubuntu - -# Generate diagram -plantuml diagram.puml - -# Generate all diagrams in folder -plantuml *.puml -``` - -### Best Practices - -1. **Update diagrams when architecture changes** -2. **Version control diagrams with code** -3. **Include diagrams in pull requests** -4. **Use diagrams in documentation** -5. **Review diagrams in architecture meetings** - ---- - -**Total Diagrams in Collection: 30+** - -All diagrams are ready for generation using PlantUML! diff --git a/archive/2026-04-16/PRESENTATION_COMPLETE_GUIDE.md b/archive/2026-04-16/PRESENTATION_COMPLETE_GUIDE.md deleted file mode 100644 index c1473ea..0000000 --- a/archive/2026-04-16/PRESENTATION_COMPLETE_GUIDE.md +++ /dev/null @@ -1,1661 +0,0 @@ -# FIVUCSAS Complete Presentation Guide - -**Project:** Face and Identity Verification Using Cloud-Based SaaS Models -**Course:** CSE4197 Engineering Project - Fall 2025 -**Date:** January 7, 2026 -**Duration:** 12 minutes presentation + 3 minutes Q&A -**Team:** Ahmet Abdullah Gultekin, Ayse Gulsum Eren, Aysenur Arici -**Advisor:** Assoc. Prof. Dr. Mustafa Agaoglu - ---- - -## Table of Contents - -1. [Presentation Overview](#1-presentation-overview) -2. [Slide-by-Slide Guide](#2-slide-by-slide-guide) -3. [Presenter Assignments](#3-presenter-assignments) -4. [Technical Diagrams](#4-technical-diagrams) -5. [Q&A Preparation](#5-qa-preparation) -6. [Checklist Before Presentation](#6-checklist-before-presentation) -7. [Demo Appendix](#7-demo-appendix-for-live-demonstration) - ---- - -## 1. Presentation Overview - -### Time Budget (12 minutes total) - -| Section | Slides | Time | Presenter | -|---------|--------|------|-----------| -| Opening (Title + Outline) | 1-2 | 0:50 | **Aysenur** | -| Problem & Motivation | 3 | 1:00 | **Aysenur** | -| Related Work & Gap | 4 | 1:10 | **Aysenur** | -| Scope & Constraints | 5 | 0:50 | **Aysenur** | -| *[TRANSITION 1]* | - | 0:10 | Aysenur → Ahmet | -| System Architecture | 6 | 0:50 | **Ahmet** | -| Biometric Puzzle (Liveness) | 7 | 1:00 | **Ahmet** | -| **Biometric Processor Demo** | 8 | 0:50 | **Ahmet** | -| ML Pipeline & Vector Search | 9 | 0:45 | **Ahmet** | -| Card Detection & NFC | 10 | 0:45 | **Ahmet** | -| *[TRANSITION 2]* | - | 0:10 | Ahmet → Gulsum | -| **Document Verification Demo** | 11 | 0:45 | **Gulsum** | -| Tasks Accomplished | 12 | 0:50 | **Gulsum** | -| Challenges & Solutions | 13 | 0:40 | **Gulsum** | -| Future Work & B-Plan | 14 | 0:40 | **Gulsum** | -| Thank You | 15 | 0:25 | **Gulsum** | -| References | 16 | 0:20 | **Gulsum** | -| Q&A | 17 | 3:00 | **All** | -| **TOTAL** | **17** | **~12:00 + 3:00 Q&A** | | - -> **Structure:** Aysenur (Slides 1-5, ~4:00) → Ahmet (Slides 6-10, ~4:10) → Gulsum (Slides 11-16, ~3:40) → All (17) -> **BALANCED: Each presenter ~4 minutes** - -### Slide Count Compliance -- Required: 12-18 slides -- Our count: 17 slides (within limit) - ---- - -## 2. Slide-by-Slide Guide - ---- - -### SLIDE 1: Title Slide - -**Time:** 0:25 -**Presenter:** Aysenur Arici -**Aspect Ratio:** 16:9 - -#### Visual Design -``` -┌───────────────────────────────────────────────────────────────────────────┐ -│ │ -│ [Marmara University Logo] [468 Landmarks │ -│ Demo Screenshot] │ -│ FIVUCSAS │ -│ ───────────────────────────────────────────── │ -│ Face and Identity Verification Using │ -│ Cloud-Based SaaS Models │ -│ │ -│ CSE4197 Engineering Project - Fall 2025 │ -│ │ -│ Team: │ -│ • Ahmet Abdullah Gultekin (150121025) │ -│ • Ayse Gulsum Eren (150120005) │ -│ • Aysenur Arici (150123825) │ -│ │ -│ Supervisor: Assoc. Prof. Dr. Mustafa Agaoglu │ -│ │ -│ Marmara University - Computer Engineering │ -│ 1/17 │ -└───────────────────────────────────────────────────────────────────────────┘ -``` - -#### Content Elements -- **Title:** FIVUCSAS (large, bold) -- **Subtitle:** Face and Identity Verification Using Cloud-Based SaaS Models -- **Course:** CSE4197 Engineering Project - Fall 2025 -- **Team members:** Names with student IDs (text only, no photos) -- **Supervisor:** Full academic title required -- **Institution:** Marmara University - Computer Engineering -- **Visual:** 468 facial landmarks screenshot from demo (right side) -- **Page number:** 1/17 (bottom right) - -#### Image Requirements -- Marmara University official logo (top left) -- **468 Facial Landmarks Screenshot** from your demo - shows MediaPipe face mesh visualization - -#### Speech Script -``` -"Hello everyone. We are presenting FIVUCSAS - Face and Identity Verification -Using Cloud-Based SaaS Models. - -I am Aysenur Arici. My teammates are Ahmet Abdullah Gultekin and Ayse Gulsum -Eren. Our advisor is Associate Professor Doctor Mustafa Agaoglu." -``` - ---- - -### SLIDE 2: Presentation Outline - -**Time:** 0:25 -**Presenter:** Aysenur Arici -**Aspect Ratio:** 16:9 - -#### Visual Design -``` -┌───────────────────────────────────────────────────────────────────────────┐ -│ │ -│ OUTLINE │ -│ ──────── │ -│ │ -│ WHY THIS MATTERS │ -│ ───────────────── │ -│ 1. Problem Statement & Motivation │ -│ 2. Related Work & Gap Analysis │ -│ 3. Scope & Engineering Constraints │ -│ │ -│ HOW WE SOLVE IT │ -│ ──────────────── │ -│ 4. System Architecture │ -│ 5. The Biometric Puzzle (Hybrid Liveness) │ -│ 6. ML Pipeline & Vector Search │ -│ 7. Card Detection & NFC Verification │ -│ │ -│ WHAT WE BUILT │ -│ ────────────── │ -│ 8. Tasks Accomplished │ -│ 9. Technical Challenges & Solutions │ -│ 10. Future Work & Contingency Plan │ -│ │ -│ 2/17 │ -└───────────────────────────────────────────────────────────────────────────┘ -``` - -#### Content Elements -- Structured in 3 parts: WHY / HOW / WHAT -- **Numbered items** (1-10) for clear progression -- Visual grouping makes flow clear -- Page number: 2/17 - -#### Speech Script -``` -"Our presentation has three parts: - -First, WHY - the problem of identity fraud and where existing solutions -fall short. - -Second, HOW - our architecture, liveness detection, and document verification. - -Third, WHAT - our accomplishments, challenges, and semester two plans." -``` - ---- - -### SLIDE 3: Problem Statement & Motivation - -**Time:** 1:00 -**Presenter:** Aysenur Arici -**Aspect Ratio:** 16:9 - -#### Visual Design -``` -┌───────────────────────────────────────────────────────────────────────────┐ -│ WHY THIS MATTERS │ -│ ──────────────── │ -│ │ -│ ┌─────────────────────────────────────────────────────────────────────┐ │ -│ │ "2024: Deepfake CFO video call → $25 Million stolen" │ │ -│ └─────────────────────────────────────────────────────────────────────┘ │ -│ │ -│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ -│ │ │ │ │ │ │ │ -│ │ $23B │ │ +400% │ │ 1/4 │ │ -│ │ │ │ │ │ │ │ -│ │ [Money │ │ [Graph │ │ [Eye │ │ -│ │ Icon] │ │ Icon] │ │ Icon] │ │ -│ │ │ │ │ │ │ │ -│ │ Identity │ │ Deepfake │ │ People │ │ -│ │ Fraud │ │ Attacks │ │ Fooled │ │ -│ │ (2024) │ │ (YoY) │ │ │ │ -│ └─────────────┘ └─────────────┘ └─────────────┘ │ -│ │ -│ OUR GOAL: Prove LIVE + AUTHENTIC + IMPOSSIBLE to spoof │ -│ 3/17 │ -└───────────────────────────────────────────────────────────────────────────┘ -``` - -#### Content Elements -- **Hook:** 2024 Hong Kong deepfake incident ($25M) -- **Three large visual statistics:** - 1. $23B - Identity fraud losses (2024) - 2. +400% - Deepfake attack increase (YoY) - 3. 1/4 - People who cannot detect deepfakes -- **Goal statement:** LIVE + AUTHENTIC + IMPOSSIBLE to spoof -- **Minimal text, maximum visual impact** -- Page number: 3/17 - -#### Speech Script -``` -"Let me start with a real incident from 2024. In Hong Kong, a deepfake video call -impersonated the CFO of a company and convinced employees to transfer 25 million -dollars. This is not science fiction - this happened last year. - -Look at the numbers: 23 billion dollars lost to identity fraud in 2024 alone. -Deepfake attacks have increased 400 percent year over year. And here is the -scary part: one in four people cannot distinguish a deepfake from a real person. - -This is why we built FIVUCSAS. Our goal is simple but critical: prove the person -is LIVE and present, their identity document is AUTHENTIC and untampered, and -spoofing is IMPOSSIBLE through our hybrid detection system." -``` - ---- - -### SLIDE 4: Related Work & Gap Analysis - -**Time:** 1:00 -**Presenter:** Aysenur Arici -**Aspect Ratio:** 16:9 - -#### Visual Design -``` -┌───────────────────────────────────────────────────────────────────────────┐ -│ RELATED WORK & GAP ANALYSIS │ -│ ─────────────────────────── │ -│ │ -│ ┌──────────────────────────────────────────────────────────────────────┐ │ -│ │ Feature │ Azure │ AWS │ Sodec │ BioGATE│ FIVUCSAS │ │ -│ ├────────────────┼───────┼────────┼───────┼────────┼───────────────────┤ │ -│ │ Open Source │ ✗ │ ✗ │ ✗ │ ✗ │ ✓ │ │ -│ │ Liveness │ ✓ │ ✓ │ ✗ │ ✓ │ ✓ │ │ -│ │ Multi-Tenant │ ✓ │ ✓ │ ✗ │ ✗ │ ✓ │ │ -│ │ Multi-Platform │ ✓ │ ✓ │ ✓ │ ✗ │ ✓ │ │ -│ │ NFC ICAO │ ✗ │ ✗ │ ✗ │ ✓ │ ✓ │ │ -│ │ Card Detection │ ✗ │ ✗ │ ✗ │ ✗ │ ✓ │ │ -│ │ Hybrid Liveness│ ✗ │ ✗ │ ✗ │ ✗ │ ✓ │ │ -│ └──────────────────────────────────────────────────────────────────────┘ │ -│ │ -│ GAP: No open-source solution with hybrid liveness + NFC + card detection │ -│ 4/17 │ -└───────────────────────────────────────────────────────────────────────────┘ -``` - -#### Content Elements -- Comparison table with 5 competitors -- Features: Open Source, Liveness, Multi-Tenant, Multi-Platform, NFC, Card Detection, Hybrid Liveness -- **Gap statement:** Clear visual showing the market gap we fill -- Page number: 4/17 - -#### Speech Script -``` -"Let me show you how FIVUCSAS compares to existing solutions in the market. - -Microsoft Azure Face and Amazon Rekognition are powerful, but they are proprietary - -you cannot host them yourself, and they do not support NFC chip reading or automatic -card type detection. For banks and government institutions that need data sovereignty, -this is a serious limitation. - -Sodec and BioGATE are Turkish solutions we studied. Sodec lacks liveness detection -entirely - a critical vulnerability. BioGATE has liveness but is not multi-tenant -and cannot automatically detect card types. - -Here is the gap we identified: no open-source solution combines hybrid liveness -detection, NFC chip verification, and automatic document type recognition. -FIVUCSAS fills exactly this gap." -``` - ---- - -### SLIDE 5: Scope & Engineering Constraints - -**Time:** 0:40 -**Presenter:** Aysenur Arici -**Aspect Ratio:** 16:9 - -#### Visual Design -``` -┌───────────────────────────────────────────────────────────────────────────┐ -│ SCOPE & ENGINEERING CONSTRAINTS │ -│ ─────────────────────────────── │ -│ │ -│ IN SCOPE (MVP) OUT OF SCOPE │ -│ ────────────── ──────────── │ -│ ✓ Cloud-Native SaaS Platform ✗ Hardware Manufacturing │ -│ ✓ Hybrid Liveness Detection │ -│ ✓ Card Detection (ML Model) │ -│ ✓ NFC Document Reading │ -│ ✓ Multi-Tenant Admin Dashboard │ -│ ✓ Cross-Platform Client Apps │ -│ │ -│ ┌───────────────────────────────────────────────────────────────────┐ │ -│ │ ENGINEERING CONSTRAINTS │ │ -│ │ [Camera] [Clock] [Document] │ │ -│ │ > 480p < 200ms ISO 14443 │ │ -│ │ Image Quality API Latency NFC Standard │ │ -│ └───────────────────────────────────────────────────────────────────┘ │ -│ │ -│ 5/17 │ -└───────────────────────────────────────────────────────────────────────────┘ -``` - -#### Content Elements -- **In Scope:** 6 core deliverables -- **Out of Scope:** Only hardware manufacturing (other items moved to Future Work) -- **Constraints:** Image quality, latency, NFC standard -- Page number: 5/17 - -#### Speech Script -``` -"Our MVP scope includes cloud-native SaaS, hybrid liveness, card detection, -NFC reading, multi-tenant dashboard, and cross-platform apps. - -As for out of scope, hardware manufacturing is beyond this project. - -Regarding our constraints: images must exceed 480p, API response under 200ms, -and NFC must comply with ISO 14443. - -Now, Ahmet will show you how we built our solution." -``` - ---- - -### SLIDE 6: System Architecture - -**Time:** 1:10 -**Presenter:** Ahmet Abdullah Gultekin -**Aspect Ratio:** 16:9 - -#### Visual Design -``` -┌───────────────────────────────────────────────────────────────────────────┐ -│ SYSTEM ARCHITECTURE │ -│ ─────────────────── │ -│ │ -│ ┌─────────────────────┐ │ -│ │ NGINX API GATEWAY │ │ -│ │ Rate Limiting │ │ -│ │ Routing & LB │ │ -│ └─────────┬───────────┘ │ -│ │ │ -│ ┌───────────────────────┼───────────────────────┐ │ -│ │ │ │ │ -│ ▼ ▼ ▼ │ -│ ┌─────────────┐ ┌─────────────────┐ ┌───────────────┐ │ -│ │IDENTITY CORE│ │BIOMETRIC PROC. │ │ CLIENT APPS │ │ -│ │Spring Boot │◄─────►│ FastAPI │◄────►│ Kotlin MP │ │ -│ │ Java 21 │ │ Python 3.11 │ │ Android/iOS │ │ -│ │ │ │ │ │ Desktop │ │ -│ │• JWT Auth │ │• Face Detection │ │• Camera/NFC │ │ -│ │• Multi-Tenant│ │• 40+ Endpoints │ │• Card Detect │ │ -│ │• RBAC │ │• Liveness │ │• Liveness │ │ -│ └──────┬──────┘ └────────┬────────┘ └───────────────┘ │ -│ │ │ │ -│ └───────────────────────┼─────────────────────── │ -│ ▼ │ -│ ┌────────────────────────────────────────────────────┐ │ -│ │ PostgreSQL 16 + pgvector │ Redis │ │ -│ │ • Vector Embeddings │ • Cache │ │ -│ │ • IVFFlat Indexing │ • Event Bus │ │ -│ └────────────────────────────────────────────────────┘ │ -│ │ -│ Architecture: Hexagonal (Ports & Adapters) + DDD 6/17 │ -└───────────────────────────────────────────────────────────────────────────┘ -``` - -#### Content Elements -- Three-tier architecture diagram: - 1. API Gateway (NGINX) - rate limiting, routing, load balancing - 2. Microservices: Identity Core, Biometric Processor, Client Apps - 3. Database: PostgreSQL + pgvector, Redis -- Architecture pattern: Hexagonal + DDD -- Page number: 6/17 - -#### Speech Script -``` -"Thank you. Let me walk you through our system architecture. - -We built FIVUCSAS using microservices with Hexagonal Architecture - also known as -Ports and Adapters. This design keeps our business logic independent from external -concerns like databases and APIs. - -At the top, NGINX serves as our API Gateway, handling rate limiting to prevent -abuse, request routing, and load balancing across service instances. - -We have three main components: Identity Core is our Spring Boot service written -in Java 21 - it handles JWT authentication, multi-tenant isolation, and role-based -access control. The Biometric Processor is a FastAPI service in Python 3.11 - this -is where face detection, liveness analysis, and over 40 API endpoints live. - -Our client applications use Kotlin Multiplatform, allowing us to share code -between Android, iOS, and Desktop applications. - -At the data layer, PostgreSQL 16 with pgvector stores face embeddings, and Redis -provides caching and an event bus for service communication." -``` - ---- - -### SLIDE 7: The Biometric Puzzle (Liveness Detection) - -**Time:** 1:30 -**Presenter:** Ahmet Abdullah Gultekin -**Aspect Ratio:** 16:9 - -#### Visual Design -``` -┌─────────────────────────────────────────────────────────────────┐ -│ THE BIOMETRIC PUZZLE - HYBRID LIVENESS DETECTION │ -│ ──────────────────────────────────────────────── │ -│ │ -│ ┌──────────────┐ 1. Generate Challenge ┌──────────────┐ │ -│ │ SERVER │ ─────────────────────────► │ MOBILE │ │ -│ │ │ "Blink Left Eye" │ CLIENT │ │ -│ │ │ │ │ │ -│ │ │ 2. Capture Stream │ │ │ -│ │ │ ◄───────────────────────── │ [Camera] │ │ -│ │ │ │ │ │ -│ │ Calculate │ 3. EAR = 0.18 < 0.2 │ │ │ -│ │ EAR │ ─────────────────────────► │ VERIFY │ │ -│ │ │ ✓ Blink Detected │ │ │ -│ │ │ │ │ │ -│ │ Passive │ 4. LBP Texture Check │ │ │ -│ │ Analysis │ ─────────────────────────► │ PASS │ │ -│ │ │ ✓ Not a Screen │ │ │ -│ └──────────────┘ └──────────────┘ │ -│ │ -│ ACTIVE: EAR (Eye Aspect Ratio), MAR (Mouth), Head Pose │ -│ PASSIVE: LBP Texture, Color Distribution, Frequency Domain │ -│ │ -│ Figure 4: Biometric Puzzle Challenge-Response Protocol 7/17 │ -└─────────────────────────────────────────────────────────────────┘ -``` - -#### Content Elements -- Sequence diagram showing challenge-response flow: - 1. Server generates cryptographic random challenge - 2. Mobile captures video stream - 3. EAR calculation (threshold < 0.2) - 4. Parallel passive texture analysis -- Two categories: - - ACTIVE: EAR, MAR, Head Pose (pitch/yaw/roll) - - PASSIVE: LBP texture, color distribution, frequency domain, moire pattern -- Figure caption required -- Page number: 7/17 - -#### Key Technical Metrics -- Eye Aspect Ratio threshold: EAR < 0.2 (blink detection) -- Mouth Aspect Ratio threshold: MAR > 0.6 (smile/mouth open) -- Head Pose tolerance: pitch ±15°, yaw ±20°, roll ±10° -- 468 facial landmarks via MediaPipe Face Mesh -- On-device processing: ~50ms latency (vs 500ms cloud) -- LBP texture variance threshold: < 100 indicates screen display - -#### Speech Script -``` -"The Biometric Puzzle is our original contribution to active liveness detection. - -Here is how it works: The server generates a cryptographically random challenge - -for example, 'blink your left eye.' The attacker cannot predict which action will -be requested, making replay attacks impossible. - -The mobile client captures a video stream and uses MediaPipe to track 468 facial -landmarks. We calculate the Eye Aspect Ratio - when EAR drops below 0.2, a blink -is detected. - -Simultaneously, we run passive analysis - Local Binary Pattern texture analysis -and frequency domain checks detect if the face is displayed on a screen rather -than being a real person. - -This hybrid approach combines the unpredictability of active challenges with the -spoofing detection of passive analysis, providing robust defense against deepfakes, -printed photos, and video replay attacks." -``` - ---- - -### SLIDE 8: Biometric Processor Demo - -**Time:** 0:45 -**Presenter:** Ahmet Abdullah Gultekin -**Aspect Ratio:** 16:9 - -#### Visual Design -``` -┌───────────────────────────────────────────────────────────────────────────┐ -│ BIOMETRIC PROCESSOR IN ACTION │ -│ ───────────────────────────── │ -│ │ -│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ -│ │ │ │ │ │ │ │ -│ │ [AHMET'S │ │ [AYŞENUR'S │ │ [GÜLSÜM'S │ │ -│ │ FACE with │ │ FACE with │ │ FACE with │ │ -│ │ 468 MESH │ │ 468 MESH │ │ 468 MESH │ │ -│ │ OVERLAY] │ │ OVERLAY] │ │ OVERLAY] │ │ -│ │ │ │ │ │ │ │ -│ │ ┌────────────┐ │ │ ┌────────────┐ │ │ ┌────────────┐ │ │ -│ │ │EAR: 0.28 │ │ │ │EAR: 0.31 │ │ │ │EAR: 0.29 │ │ │ -│ │ │Quality: 94%│ │ │ │Quality: 96%│ │ │ │Quality: 95%│ │ │ -│ │ │✓ LIVE │ │ │ │✓ LIVE │ │ │ │✓ LIVE │ │ │ -│ │ └────────────┘ │ │ └────────────┘ │ │ └────────────┘ │ │ -│ └──────────────────┘ └──────────────────┘ └──────────────────┘ │ -│ │ -│ All team members verified with 468 facial landmarks + liveness detection │ -│ 8/17 │ -└───────────────────────────────────────────────────────────────────────────┘ -``` - -#### Content Elements -- **Three team member photos** with MediaPipe 468-landmark mesh overlay -- **Real-time metrics** for each face: EAR value, quality score, liveness status -- **All showing "LIVE" status** proving Biometric Puzzle works -- Visual proof that the system works on real people -- Page number: 8/17 - -#### Image Requirements -- **Capture screenshots** from web demo showing each team member -- Each photo should display the green face mesh overlay (468 landmarks) -- Include the metrics panel showing EAR, quality, and liveness status - -#### Speech Script -``` -"Here is our Biometric Processor in action with all three team members. - -You can see the 468 facial landmarks being tracked in real-time - that is the -green mesh overlay on each face. Below each photo, you see the Eye Aspect Ratio, -the frame quality score, and the liveness status. - -All three of us passed the Biometric Puzzle challenge and are verified as LIVE. -A photo or deepfake would fail this test because it cannot respond to random -challenges like 'blink your left eye' or 'turn your head right.'" -``` - ---- - -### SLIDE 9: ML Pipeline & Vector Search - -**Time:** 0:45 -**Presenter:** Ahmet Abdullah Gultekin -**Aspect Ratio:** 16:9 - -#### Visual Design -``` -┌───────────────────────────────────────────────────────────────────────────┐ -│ ML PIPELINE & VECTOR SEARCH │ -│ ─────────────────────────── │ -│ │ -│ ┌───────────────────────────────────────────────────────────────────┐ │ -│ │ RECOGNITION PIPELINE │ │ -│ │ │ │ -│ │ [Input] [Detect] [Align] [Extract] [Search] │ │ -│ │ │ │ │ │ │ │ │ -│ │ ▼ ▼ ▼ ▼ ▼ │ │ -│ │ Image → Face Box → Aligned → Embedding → Match │ │ -│ │ MediaPipe 5-Point Vector Cosine │ │ -│ └───────────────────────────────────────────────────────────────────┘ │ -│ │ -│ ┌───────────────────────────────────────────────────────────────────┐ │ -│ │ VECTOR DATABASE │ │ -│ │ PostgreSQL + pgvector + IVFFlat → O(log n) sub-ms queries │ │ -│ │ Threshold: cosine distance < 0.68 = match │ │ -│ └───────────────────────────────────────────────────────────────────┘ │ -│ │ -│ 9/17 │ -└───────────────────────────────────────────────────────────────────────────┘ -``` - -#### Content Elements -- Pipeline diagram: Input → Detection → Alignment → Extraction → Search -- Vector database: PostgreSQL + pgvector + IVFFlat -- Threshold info: cosine distance < 0.68 = match -- Page number: 9/17 - -#### Speech Script -``` -"Our ML pipeline has five stages for face recognition. - -First, the input image comes in. Second, MediaPipe Face Detection locates faces -and returns bounding boxes. Third, we perform 5-point alignment to normalize face -orientation - this is critical for consistent embeddings. - -Fourth, we extract a 2622-dimensional vector embedding using VGG-Face. This -embedding is a mathematical fingerprint of the face that we can compare. - -Fifth and finally, we search for matches using cosine similarity. Here is where -pgvector shines - with IVFFlat indexing, we achieve sub-millisecond query times -even with tens of thousands of enrolled faces. The search complexity is O(log n). - -Our verification threshold is a cosine distance of 0.68. Below this threshold -means a match; above means different people. This threshold balances false -acceptance against false rejection." -``` - ---- - -### SLIDE 10: Card Detection & NFC Verification - -**Time:** 0:50 -**Presenter:** Ahmet Abdullah Gultekin -**Aspect Ratio:** 16:9 - -#### Visual Design -``` -┌─────────────────────────────────────────────────────────────────┐ -│ CARD DETECTION & NFC VERIFICATION │ -│ ───────────────────────────────── │ -│ │ -│ ┌─────────────────────────────────────────────────────────────┐│ -│ │ STEP 1: VISUAL CARD DETECTION (ML MODEL) ││ -│ │ ───────────────────────────────────────────────────────── ││ -│ │ ││ -│ │ [Camera] → [Trained Model] → [Card Type Detected] ││ -│ │ ││ -│ │ • Automatic ID type recognition (Turkish eID, Passport) ││ -│ │ • Real-time detection via on-device ML ││ -│ │ • Guides user for optimal card positioning ││ -│ └─────────────────────────────────────────────────────────────┘│ -│ │ -│ ┌─────────────────────────────────────────────────────────────┐│ -│ │ STEP 2: NFC CHIP VERIFICATION (ICAO) ││ -│ │ ───────────────────────────────────────────────────────── ││ -│ │ ││ -│ │ [Mobile NFC] → [BAC Handshake] → [Read DG1/DG2] → [SOD ✓] ││ -│ │ ││ -│ │ • MRZ-derived session keys (3DES secure messaging) ││ -│ │ • DG1: Personal data, DG2: High-res JPEG2000 photo ││ -│ │ • Digital signature proves document authenticity ││ -│ └─────────────────────────────────────────────────────────────┘│ -│ │ -│ STANDARDS: ICAO Doc 9303, ISO/IEC 14443, ISO 7816-4 │ -│ CARDS: Turkish eID, e-Passport, MIFARE, NDEF, 10+ types │ -│ │ -│ Figure 6: Two-Stage Document Verification Pipeline 10/17 │ -└─────────────────────────────────────────────────────────────────┘ -``` - -#### Content Elements -- Two-stage pipeline: - 1. **Visual Card Detection** (ML Model): - - Trained model detects card type from camera feed - - Real-time on-device inference - - Automatic recognition of Turkish eID, Passport, etc. - 2. **NFC Chip Verification** (ICAO): - - BAC handshake with MRZ-derived keys - - Read DG1 (personal data) and DG2 (photo) - - SOD verification for authenticity -- Standards: ICAO Doc 9303, ISO/IEC 14443, ISO 7816-4 -- Supported cards: Turkish eID, e-Passport, MIFARE, NDEF, 10+ types -- Figure caption required -- Page number: 10/17 - -#### Speech Script -``` -"Document verification in FIVUCSAS is a two-stage pipeline. - -First, our trained Card Detection model analyzes the camera feed to -automatically identify the document type - Turkish ID, passport, driver's -license - without manual user selection. This runs on-device for real-time -feedback and guides the user for optimal positioning. - -Second, once the card is positioned, our NFC Reader establishes a secure -connection using Basic Access Control. The session keys are derived from the -Machine Readable Zone, ensuring physical possession. - -We then read Data Group 1 for personal information and Data Group 2 for a -high-resolution photograph - significantly better than the printed image. - -Finally, we verify the Security Object Document - a digital signature proving -the data has not been modified since issuance. - -This combination of visual detection and cryptographic verification makes -document spoofing extremely difficult." -``` - ---- - -### SLIDE 11: Document Verification Demo - -**Time:** 0:45 -**Presenter:** Ayse Gulsum Eren -**Aspect Ratio:** 16:9 - -#### Visual Design -``` -┌───────────────────────────────────────────────────────────────────────────┐ -│ DOCUMENT VERIFICATION IN ACTION │ -│ ─────────────────────────────── │ -│ │ -│ ┌─────────────────────────────────┐ ┌─────────────────────────────────┐ │ -│ │ CARD DETECTION │ │ NFC CHIP READING │ │ -│ │ ─────────────── │ │ ───────────────── │ │ -│ │ │ │ │ │ -│ │ [TURKISH eID PHOTO] │ │ [NFC SCAN SCREEN] │ │ -│ │ │ │ │ │ -│ │ ┌─────────────────────────┐ │ │ ┌─────────────────────────┐ │ │ -│ │ │ 🔍 Type: TURKISH_EID │ │ │ │ ✓ BAC Authenticated │ │ │ -│ │ │ 📊 Confidence: 97.3% │ │ │ │ ✓ DG1 Personal Data │ │ │ -│ │ │ ✓ Ready for NFC │ │ │ │ ✓ DG2 Photo Loaded │ │ │ -│ │ └─────────────────────────┘ │ │ │ ✓ SOD Signature Valid │ │ │ -│ │ │ │ └─────────────────────────┘ │ │ -│ │ [E-PASSPORT PHOTO] │ │ │ │ -│ │ │ │ ┌─────────────────────────┐ │ │ -│ │ ┌─────────────────────────┐ │ │ │ [HIGH-RES PHOTO │ │ │ -│ │ │ 🔍 Type: E_PASSPORT │ │ │ │ FROM DG2 CHIP] │ │ │ -│ │ │ 📊 Confidence: 98.1% │ │ │ │ │ │ │ -│ │ │ ✓ Ready for NFC │ │ │ │ JPEG2000 Quality │ │ │ -│ │ └─────────────────────────┘ │ │ └─────────────────────────┘ │ │ -│ └─────────────────────────────────┘ └─────────────────────────────────┘ │ -│ │ -│ Left: ML model auto-detects card type | Right: NFC reads chip securely │ -│ 11/17 │ -└───────────────────────────────────────────────────────────────────────────┘ -``` - -#### Content Elements -- **Left side: Card Detection results** - - Turkish eID detected with 97.3% confidence - - e-Passport detected with 98.1% confidence - - Shows automatic type recognition without user input -- **Right side: NFC verification results** - - BAC authentication success - - DG1 (personal data) and DG2 (photo) read - - SOD signature verified - - High-resolution photo extracted from chip -- Page number: 11/17 - -#### Image Requirements -- **Card Detection screenshots**: Capture from mobile app showing detected cards -- **NFC scan screen**: Mobile app showing "Hold card to phone" instruction -- **Verification results**: Success checkmarks for BAC, DG1, DG2, SOD -- **DG2 photo**: High-res photo extracted from NFC chip (team member's ID) - -#### Speech Script -``` -"Here you can see our document verification system working with real documents. - -On the left, our Card Detection model automatically recognizes the document type. -Turkish eID detected with 97% confidence, e-Passport with 98%. No manual selection - -the user just points the camera and the system identifies the card type instantly. - -On the right, the NFC reading results. After placing the card on the phone, we -successfully authenticate using Basic Access Control, read the personal data from -DG1, extract the high-resolution JPEG2000 photo from DG2, and verify the digital -signature in the Security Object Document. - -That green checkmark on SOD means this document is cryptographically proven to be -authentic and unmodified since issuance. - -Now Gulsum will present what we accomplished this semester." -``` - ---- - -### SLIDE 12: Tasks Accomplished - -**Time:** 1:00 -**Presenter:** Ayse Gulsum Eren -**Aspect Ratio:** 16:9 - -#### Visual Design -``` -┌───────────────────────────────────────────────────────────────────────────┐ -│ WHAT WE BUILT - FALL 2025 │ -│ ───────────────────────── │ -│ │ -│ BIOMETRIC FEATURES DOCUMENT VERIFICATION │ -│ ────────────────── ───────────────────── │ -│ 1. Face Detection (MediaPipe) 9. Visual Card Detection (ML) │ -│ 2. Face Enrollment 10. NFC Document Reading │ -│ 3. Face Verification (1:1) 11. BAC Authentication │ -│ 4. Face Search (1:N) 12. SOD Validation │ -│ 5. Biometric Puzzle (Liveness) 13. MRZ Parsing │ -│ 6. Frame Quality Analysis 14. 10+ Card Types Support │ -│ 7. Demographic Analysis │ -│ 8. Similarity Scoring INFRASTRUCTURE │ -│ ────────────── │ -│ WEB DEMO GUI 15. JWT Authentication │ -│ ────────────── 16. Multi-Tenant Architecture │ -│ • Dashboard 17. 40+ REST API Endpoints │ -│ • Enrollment Page 18. PostgreSQL + pgvector │ -│ • Verification Page 19. IVFFlat Vector Indexing │ -│ • Search Page 20. Redis Caching │ -│ • Liveness Testing 21. Flyway Migrations │ -│ • Quality Analysis 22. Kotlin Multiplatform Apps │ -│ │ -│ 12/17 │ -└───────────────────────────────────────────────────────────────────────────┘ -``` - -#### Content Elements -- **22 implemented features** organized by category: - - Biometric Features (8): Detection, Enrollment, Verification, Search, Liveness, Quality, Demographics, Similarity - - Document Verification (6): Card Detection, NFC, BAC, SOD, MRZ, Card Types - - Infrastructure (8): Auth, Multi-tenant, API, Database, Indexing, Cache, Migrations, Apps - - Web Demo GUI: 6 interactive pages -- Clear numbered list for easy reading -- Page number: 12/17 - -#### Speech Script -``` -"Here is everything we built this semester - 22 implemented features. - -[Read the list by sections] - -Biometric: face detection, enrollment, verification, search, the Biometric -Puzzle for liveness, quality analysis, demographics, and similarity scoring. - -Document verification: our trained card detection model, NFC reading, BAC -authentication, SOD validation, MRZ parsing, supporting 10+ card types. - -Infrastructure: JWT auth, multi-tenant architecture, 40+ API endpoints, -PostgreSQL with pgvector, IVFFlat indexing, Redis, and Kotlin Multiplatform. - -Plus a complete web demo with 6 interactive pages." -``` - ---- - -### SLIDE 13: Technical Challenges & Solutions - -**Time:** 0:50 -**Presenter:** Ayse Gulsum Eren -**Aspect Ratio:** 16:9 - -#### Visual Design -``` -┌───────────────────────────────────────────────────────────────────────────┐ -│ TECHNICAL CHALLENGES │ -│ ──────────────────── │ -│ │ -│ ┌─────────────────────────────────────────────────────────────────────┐ │ -│ │ 1. NFC PASSPORT INTEGRATION │ │ -│ │ ───────────────────────── │ │ -│ │ Challenge: Complex ICAO protocols, BAC handshake, SOD parsing │ │ -│ │ Solution: Modular reader architecture with 7 specialized readers│ │ -│ └─────────────────────────────────────────────────────────────────────┘ │ -│ │ -│ ┌─────────────────────────────────────────────────────────────────────┐ │ -│ │ 2. CARD DETECTION MODEL TRAINING │ │ -│ │ ──────────────────────────── │ │ -│ │ Challenge: Dataset collection, model accuracy, real-time speed │ │ -│ │ Solution: Custom dataset + optimized on-device inference │ │ -│ └─────────────────────────────────────────────────────────────────────┘ │ -│ │ -│ ┌─────────────────────────────────────────────────────────────────────┐ │ -│ │ 3. CROSS-LANGUAGE MICROSERVICE COMMUNICATION │ │ -│ │ ──────────────────────────────────────── │ │ -│ │ Challenge: Java ↔ Python service integration, type safety │ │ -│ │ Solution: REST APIs with OpenAPI contracts + Redis event bus │ │ -│ └─────────────────────────────────────────────────────────────────────┘ │ -│ │ -│ 13/17 │ -└───────────────────────────────────────────────────────────────────────────┘ -``` - -#### Content Elements -- **3 key challenges** with solutions: - 1. NFC Passport Integration - ICAO protocols, modular readers - 2. Card Detection Model Training - dataset + on-device inference - 3. Cross-Language Microservice - Java ↔ Python, REST + Redis -- Clean visual layout with boxed sections -- Page number: 13/17 - -#### Speech Script -``` -"We faced three major challenges. - -First, NFC passport integration. ICAO protocols are complex - BAC handshake, -SOD parsing. We built 7 specialized readers for different card types. - -Second, card detection training. We collected a custom dataset and optimized -the model for real-time on-device inference. - -Third, cross-language communication. Java and Python services needed to talk. -We used REST APIs with OpenAPI contracts and Redis for events." -``` - ---- - -### SLIDE 14: Future Work & Contingency Plan - -**Time:** 0:50 -**Presenter:** Ayse Gulsum Eren -**Aspect Ratio:** 16:9 - -#### Visual Design -``` -┌───────────────────────────────────────────────────────────────────────────┐ -│ SEMESTER 2 PLANS & B-PLAN │ -│ ───────────────────────── │ -│ │ -│ SEMESTER 2 TIMELINE (Spring 2026) │ -│ ───────────────────────────────── │ -│ │ -│ FEB ─────► Service Integration + OCR Module │ -│ MAR ─────► Real-Time Proctoring Module │ -│ APR ─────► Security Testing + Mobile Polish │ -│ MAY ─────► Production Deployment │ -│ │ -│ ┌───────────────────────────────────────────────────────────────────┐ │ -│ │ CONTINGENCY PLAN (B-PLAN) │ │ -│ │ │ │ -│ │ IF NFC edge cases fail → Focus on Turkish eID + e-Passport │ │ -│ │ IF Integration delayed → Web demo as primary deliverable │ │ -│ └───────────────────────────────────────────────────────────────────┘ │ -│ │ -│ ┌───────────────────────────────────────────────────────────────────┐ │ -│ │ FUTURE RESEARCH (Beyond Project) │ │ -│ │ • Offline mode with on-device ML │ │ -│ │ • Fingerprint & iris biometrics │ │ -│ │ • Embedded devices (Raspberry Pi) │ │ -│ └───────────────────────────────────────────────────────────────────┘ │ -│ 14/17 │ -└───────────────────────────────────────────────────────────────────────────┘ -``` - -#### Content Elements -- **Semester 2 Timeline:** Feb-May 2026 with clear deliverables -- **B-Plan:** 2 realistic contingency options -- **Future Research:** 3 directions beyond project scope -- Page number: 14/17 - -#### Speech Script -``` -"Semester two: February for service integration and OCR. March for proctoring. -April for security testing. May for deployment. - -Our B-Plan: if NFC edge cases fail, we focus on Turkish eID and e-Passport. -If integration is delayed, the web demo becomes our primary deliverable. - -Future research beyond this project: offline mode, fingerprint and iris -biometrics, and embedded device deployment." -``` - ---- - -### SLIDE 15: Thank You - -**Time:** 0:20 -**Presenter:** Ayse Gulsum Eren -**Aspect Ratio:** 16:9 - -#### Visual Design -``` -┌───────────────────────────────────────────────────────────────────────────┐ -│ │ -│ │ -│ THANK YOU │ -│ ───────── │ -│ │ -│ │ -│ We thank our advisor, Assoc. Prof. Dr. Mustafa Agaoglu, │ -│ for his guidance throughout this project. │ -│ │ -│ │ -│ │ -│ GitHub: github.com/Rollingcat-Software/FIVUCSAS │ -│ │ -│ (Will be released as open-source) │ -│ │ -│ │ -│ 15/17 │ -└───────────────────────────────────────────────────────────────────────────┘ -``` - -#### Content Elements -- Thank you message -- Advisor acknowledgment -- GitHub link -- **Open-source release announcement** -- Page number: 15/17 - -#### Speech Script -``` -"We thank our advisor, Associate Professor Doctor Mustafa Agaoglu, for his -guidance. - -Our code is on GitHub. Currently it is closed-source, but we plan to release -it as open-source after graduation." -``` - ---- - -### SLIDE 16: References - -**Time:** 0:20 -**Presenter:** Ayse Gulsum Eren -**Aspect Ratio:** 16:9 - -#### Visual Design -``` -┌───────────────────────────────────────────────────────────────────────────┐ -│ REFERENCES │ -│ ────────── │ -│ │ -│ [1] Taigman et al. (2014). DeepFace: Closing the Gap to Human-Level │ -│ Performance in Face Verification. CVPR. │ -│ │ -│ [2] Schroff et al. (2015). FaceNet: A Unified Embedding for Face │ -│ Recognition and Clustering. IEEE CVPR. │ -│ │ -│ [3] Deng et al. (2019). ArcFace: Additive Angular Margin Loss for │ -│ Deep Face Recognition. CVPR. │ -│ │ -│ [4] Lugaresi et al. (2019). MediaPipe: A Framework for Building │ -│ Perception Pipelines. Google Research. │ -│ │ -│ [5] ICAO Doc 9303: Machine Readable Travel Documents. │ -│ │ -│ [6] ISO/IEC 14443 & ISO 7816-4: NFC Standards. │ -│ │ -│ 16/17 │ -└───────────────────────────────────────────────────────────────────────────┘ -``` - -#### Content Elements -- 6 key academic references -- Clean, readable format -- **LAST CONTENT SLIDE (per professor requirement)** -- Page number: 16/17 - -#### Speech Script -``` -"Our key references: DeepFace and FaceNet for face recognition foundations, -ArcFace for embedding quality, MediaPipe for landmarks, and ICAO/ISO for -NFC standards." -``` - ---- - -### SLIDE 17: Q&A - -**Time:** 3:00 -**Presenter:** All Team Members -**Aspect Ratio:** 16:9 - -#### Visual Design -``` -┌───────────────────────────────────────────────────────────────────────────┐ -│ │ -│ │ -│ │ -│ QUESTIONS & ANSWERS │ -│ ─────────────────── │ -│ │ -│ │ -│ │ -│ │ -│ [Q&A Icon] │ -│ │ -│ │ -│ │ -│ │ -│ 17/17 │ -└───────────────────────────────────────────────────────────────────────────┘ -``` - -#### Content Elements -- Simple Q&A slide -- Clean design -- Page number: 17/17 - -#### Speech Script -``` -"We welcome your questions." -``` - ---- - -## 3. Presenter Assignments - -### Flow with 2 Main Transitions - -| Presenter | Slides | Total Time | Role | -|-----------|--------|------------|------| -| **Aysenur Arici** | 1-5 | ~4:00 | **Opening & Problem Context** | -| **Ahmet Abdullah** | 6-10 | ~4:10 | **Technical Innovation + Biometric Demo** | -| **Ayse Gulsum** | 11-16 | ~3:40 | **Doc Demo + Implementation + References** | -| **All Together** | 17 | ~3:00 | **Q&A** | - -> **Flow:** Aysenur (problem) → Ahmet (solution + biometric demo) → Gulsum (doc demo + results + refs) → All (Q&A) -> **BALANCED: 5 slides / 5 slides / 6 slides** - -### Two Transition Scripts - -**TRANSITION 1: Aysenur → Ahmet (after Slide 5)** -``` -[Aysenur:] -"Now, Ahmet will show you how we built our solution." - -[Ahmet:] -"Thank you. Let me show you our architecture." -``` - -**TRANSITION 2: Ahmet → Gulsum (after Slide 10)** -``` -[Ahmet:] -"Now Gulsum will show our document verification and what we accomplished." - -[Gulsum:] -"Thank you. Let me show you our document verification in action." -``` - -### Why This Structure Works - -1. **Aysenur (Slides 1-5):** Problem context (~4:00) -2. **Ahmet (Slides 6-10):** Technical solution + Biometric Demo (~4:10) -3. **Gulsum (Slides 11-16):** Doc Demo + Implementation + References (~3:40) -4. **All (Slide 17):** Q&A - -**BALANCED:** Each presenter has ~4 minutes and 5-6 slides. - ---- - -### Complete Flowing Scripts (For Practice) - -Short, natural scripts for each presenter. Practice speaking naturally, not reading. - ---- - -#### AYSENUR'S SCRIPT (Slides 1-5, ~3:30) - -``` -[SLIDE 1] -"Hello everyone. We are presenting FIVUCSAS - Face and Identity Verification -Using Cloud-Based SaaS Models. - -I am Aysenur Arici. My teammates are Ahmet Abdullah Gultekin and Ayse Gulsum -Eren. Our advisor is Associate Professor Doctor Mustafa Agaoglu." - -[SLIDE 2] -"Our presentation has three parts. - -First, WHY - we will explain the problem of identity fraud and where existing -solutions fall short. - -Second, HOW - our architecture, liveness detection, and document verification. - -Third, WHAT - our accomplishments, challenges we faced, and plans for semester two." - -[SLIDE 3] -"Let me start with a real incident from 2024. In Hong Kong, a deepfake video call -impersonated the CFO of a company and convinced employees to transfer 25 million -dollars. This is not science fiction - this happened last year. - -Look at the numbers: 23 billion dollars lost to identity fraud in 2024 alone. -Deepfake attacks have increased 400 percent year over year. And here is the -scary part: one in four people cannot distinguish a deepfake from a real person. - -This is why we built FIVUCSAS. Our goal is simple but critical: prove the person -is LIVE and present, their identity document is AUTHENTIC and untampered, and -spoofing is IMPOSSIBLE through our hybrid detection system." - -[SLIDE 4] -"Let me show you how FIVUCSAS compares to existing solutions in the market. - -Microsoft Azure Face and Amazon Rekognition are powerful, but they are proprietary - -you cannot host them yourself, and they do not support NFC chip reading or automatic -card type detection. For banks and government institutions that need data sovereignty, -this is a serious limitation. - -Sodec and BioGATE are Turkish solutions we studied. Sodec lacks liveness detection -entirely - a critical vulnerability. BioGATE has liveness but is not multi-tenant -and cannot automatically detect card types. - -Here is the gap we identified: no open-source solution combines hybrid liveness -detection, NFC chip verification, and automatic document type recognition. -FIVUCSAS fills exactly this gap." - -[SLIDE 5] -"Our MVP scope includes six core deliverables: cloud-native SaaS platform, hybrid -liveness detection, trained card detection model, NFC document reading, multi-tenant -admin dashboard, and cross-platform client applications. - -As for out of scope: hardware manufacturing is beyond this project. We focus purely -on software. - -Our engineering constraints: images must exceed 480p resolution for reliable face -detection, API response must be under 200 milliseconds for good user experience, -and NFC must comply with ISO 14443 standards. - -Now, Ahmet will show you how we built our solution." -``` - ---- - -#### AHMET'S SCRIPT (Slides 6-10, ~4:10) - -``` -[SLIDE 6] -"Thank you. Let me walk you through our system architecture. - -We built FIVUCSAS using microservices with Hexagonal Architecture. NGINX serves -as our API Gateway. Identity Core handles authentication and multi-tenancy in -Java 21. The Biometric Processor runs face detection and liveness in Python 3.11. - -Client applications use Kotlin Multiplatform for Android, iOS, and Desktop. -PostgreSQL with pgvector stores embeddings, and Redis handles caching." - -[SLIDE 7] -"The Biometric Puzzle is our key innovation - hybrid liveness detection. - -The server generates a random challenge - 'blink your left eye.' The attacker -cannot predict it. The client tracks 468 landmarks via MediaPipe and detects -blinks when EAR drops below 0.2. - -Simultaneously, passive analysis checks for screen artifacts. This hybrid approach -defeats deepfakes, photos, and video replays." - -[SLIDE 8 - DEMO] -"Here is our Biometric Processor in action with all three team members. - -You can see the 468 facial landmarks being tracked - the green mesh overlay. -Below each photo: Eye Aspect Ratio, quality score, and liveness status. - -All three of us passed the Biometric Puzzle and are verified as LIVE. A photo -or deepfake would fail because it cannot respond to random challenges." - -[SLIDE 9] -"Our ML pipeline: detection, alignment, embedding extraction, similarity search. - -MediaPipe detects faces. We align using 5 points, extract 2622-D embeddings with -VGG-Face, and search using pgvector with IVFFlat indexing for sub-millisecond queries. - -Verification threshold: cosine distance below 0.68 means a match." - -[SLIDE 10] -"Document verification is a two-stage pipeline. - -First, our Card Detection model automatically identifies the document type - -Turkish ID, passport - without manual selection. Runs on-device in real-time. - -Second, NFC reads the chip using Basic Access Control. We verify the digital -signature proving the document is authentic. - -Now Gulsum will show our document verification and what we accomplished." -``` - ---- - -#### GULSUM'S SCRIPT (Slides 11-16, ~3:40) - -``` -[SLIDE 11 - DEMO] -"Thank you. Let me show you our document verification in action. - -On the left, Card Detection: Turkish eID detected at 97% confidence, e-Passport -at 98%. No manual selection - just point and detect. - -On the right, NFC results: BAC authenticated, DG1 and DG2 read successfully, -SOD signature verified. That green checkmark proves document authenticity." - -[SLIDE 12] -"Here is everything we built this semester - 22 implemented features. - -Biometric: face detection, enrollment, verification, search, Biometric Puzzle -liveness, quality analysis, demographics, and similarity scoring. - -Document verification: card detection model, NFC reading, BAC authentication, -SOD validation, MRZ parsing, supporting 10+ card types. - -Infrastructure: JWT auth, multi-tenant architecture, 40+ API endpoints, -PostgreSQL with pgvector, Redis caching, and Kotlin Multiplatform apps." - -[SLIDE 13] -"We faced three major challenges. - -First, NFC passport integration - we built 7 specialized readers. -Second, card detection training - custom dataset, on-device optimization. -Third, cross-language communication - REST APIs with OpenAPI and Redis." - -[SLIDE 14] -"Semester two: February for integration and OCR. March for proctoring. -April for security testing. May for deployment. - -B-Plan: if NFC fails, focus on Turkish eID and e-Passport. -Future research: offline mode, fingerprint/iris, embedded devices." - -[SLIDE 15] -"We thank our advisor, Associate Professor Doctor Mustafa Agaoglu, for his guidance. - -Our code is on GitHub at Rollingcat-Software slash FIVUCSAS. We plan to release -it as open-source after graduation." - -[SLIDE 16] -"Our key references: DeepFace and FaceNet for face recognition, ArcFace for -embeddings, MediaPipe for landmarks, and ICAO/ISO for NFC standards." - -[SLIDE 17] -"We welcome your questions." -``` - ---- - -## 4. Technical Diagrams - -### Diagrams to Create Manually - -**CRITICAL:** Do NOT let Gamma.app generate these diagrams. Create them manually using Draw.io, Excalidraw, or PowerPoint. - -#### 4.1 Hexagonal Architecture Diagram (Slide 6) - -``` - ┌─────────────────┐ - │ REST API │ - │ (Adapter) │ - └────────┬────────┘ - │ - ┌────────────────────┼────────────────────┐ - │ │ │ - │ ┌───────────────▼───────────────┐ │ - │ │ │ │ - ┌────┴────┤ DOMAIN CORE ├────┴────┐ - │ Port │ (Entities, Use Cases) │ Port │ - └────┬────┤ ├────┬────┘ - │ └───────────────┬───────────────┘ │ - │ │ │ - └────────────────────┼────────────────────┘ - │ - ┌────────┴────────┐ - │ PostgreSQL │ - │ (Adapter) │ - └─────────────────┘ -``` - -#### 4.2 Biometric Puzzle Flow (Slide 7) - -``` -┌──────────┐ 1. Generate Challenge ┌──────────┐ -│ SERVER │ ─────────────────────────▶ │ MOBILE │ -│ │ "Blink Left Eye" │ CLIENT │ -│ │ │ │ -│ │ 2. Capture Frame Stream │ │ -│ │ ◀───────────────────────── │ Camera │ -│ │ │ │ -│ Calculate│ 3. EAR = 0.18 < 0.2 │ │ -│ EAR │ ─────────────────────────▶ │ VERIFY │ -│ │ ✓ Blink Detected │ │ -│ │ │ │ -│ Parallel:│ 4. LBP Texture Check │ │ -│ Passive │ ─────────────────────────▶ │ PASS │ -│ Analysis │ ✓ Not a Screen │ │ -└──────────┘ └──────────┘ -``` - -#### 4.3 NFC Handshake (Slide 9) - -``` -┌──────────────┐ ┌──────────────┐ -│ MOBILE │ │ ID CARD │ -│ (NFC) │ │ (CHIP) │ -└──────┬───────┘ └──────┬───────┘ - │ │ - │ 1. SELECT AID (A00000016745) │ - │ ─────────────────────────────────▶│ - │ │ - │ 2. GET CHALLENGE │ - │ ─────────────────────────────────▶│ - │ │ - │ 3. BAC: MRZ-derived Keys │ - │ ◀────────────────────────────────▶│ - │ (3DES Session Established) │ - │ │ - │ 4. READ DG1 (Personal Data) │ - │ ─────────────────────────────────▶│ - │ │ - │ 5. READ DG2 (JPEG2000 Photo) │ - │ ─────────────────────────────────▶│ - │ │ - │ 6. VERIFY SOD (Digital Sig) │ - │ ◀─────────────────────────────────│ - │ ✓ Document Authentic │ - ▼ ▼ -``` - -### Screenshots to Capture - -| Screenshot | Purpose | Where to Get | -|------------|---------|--------------| -| FastAPI Swagger UI | Proves 40+ endpoints exist | `http://localhost:8001/docs` | -| Web Dashboard | Shows working admin interface | Run Next.js app | -| NFC Scan Screen | Demonstrates NFC functionality | Mobile app or photo | -| Database Tables | Shows schema implementation | pgAdmin | - ---- - -## 5. Q&A Preparation - -### Likely Questions and Answers - -#### Q1: "How does the Biometric Puzzle prevent deepfake attacks?" - -**Answer:** -``` -"This is a critical question for our system. The key insight is that deepfakes -are pre-generated content. Our Biometric Puzzle generates random challenges in -real-time - the attacker cannot know in advance whether we will ask for a blink, -a smile, or a head turn. By the time they generate the correct response, the -challenge has already expired. Additionally, our passive analysis checks for -screen artifacts like moire patterns and unnatural color distribution that -deepfakes displayed on screens inevitably exhibit." -``` - -#### Q2: "What is your verification accuracy?" - -**Answer:** -``` -"We benchmarked our system using the LFW dataset, which is the standard for -face verification research. Using VGG-Face embeddings with a cosine distance -threshold of 0.68, we achieve a False Acceptance Rate below 1% and a False -Rejection Rate below 3%. This gives us an Equal Error Rate of approximately 3%, -which is comparable to commercial solutions like Azure Face API." -``` - -#### Q3: "Why did you choose PostgreSQL with pgvector over dedicated vector databases?" - -**Answer:** -``` -"We evaluated dedicated vector databases like Pinecone and Milvus, but chose -pgvector primarily for unified data management - user profiles and their face -embeddings stay together with full referential integrity. This also gives us -transaction support, meaning enrollment is atomic and consistent. And from an -operational perspective, maintaining one database instead of two significantly -reduces complexity. With IVFFlat indexing, query performance is more than -sufficient for our target scale." -``` - -#### Q4: "How do you handle multi-tenancy security?" - -**Answer:** -``` -"We implement row-level security in PostgreSQL. Every user-scoped table has -a tenant_id column, and database policies ensure queries only return data -for the authenticated tenant. This is enforced at the database level, not -just application logic, providing defense in depth." -``` - -#### Q5: "What happens if the NFC chip reading fails?" - -**Answer:** -``` -"We anticipated this risk during our planning phase. Our contingency plan is -straightforward: if universal NFC parsing proves unreliable across different -card types, we limit support to Turkish National ID cards only, which we have -thoroughly tested and validated. The modular architecture we designed allows -us to disable specific card type readers without affecting the rest of the -system, so this fallback is seamless." -``` - -#### Q6: "How do you ensure KVKK/GDPR compliance?" - -**Answer:** -``` -"Privacy was a core design principle from the beginning. We practice data -minimization by storing only mathematical embeddings, never the original face -images. We fully support the right to be forgotten through our deletion API. -All biometric data is encrypted at rest using AES-256, and every transmission -uses TLS 1.3. Most importantly, we require explicit user consent before any -biometric processing begins - no silent data collection." -``` - -#### Q7: "What is your test coverage?" - -**Answer:** -``` -"We have comprehensive coverage at multiple levels. Unit tests validate our -domain entities and use cases in isolation. Integration tests verify that our -API endpoints behave correctly with real database connections. And end-to-end -tests exercise complete workflows from enrollment through verification. Our CI -pipeline runs all tests automatically on every pull request, using pytest for -Python and JUnit 5 for Java, with coverage reporting to track our progress." -``` - -#### Q8: "What happens if the user's appearance changes (beard, glasses, aging)?" - -**Answer:** -``` -"Our multi-image enrollment using template fusion addresses this. We recommend -enrolling 3-5 images with variations in lighting, angle, and expression. The -quality-weighted average creates a robust template. VGG-Face embeddings are -trained on diverse datasets including these variations, and our verification -threshold of 0.68 allows for natural appearance changes while maintaining security." -``` - -#### Q9: "Why Python + Java instead of a single language?" - -**Answer:** -``` -"Each language serves its optimal purpose. Python with FastAPI handles ML -workloads because the entire machine learning ecosystem - DeepFace, MediaPipe, -NumPy, OpenCV - is Python-native. Java with Spring Boot handles enterprise -concerns like authentication, multi-tenancy, and RBAC where it excels. This -separation also enables independent scaling and deployment." -``` - -#### Q10: "How does your system scale? What's the max concurrent users?" - -**Answer:** -``` -"Our architecture was designed for horizontal scaling from the start. The -Biometric Processor can be replicated behind a load balancer, with each -instance handling ML inference independently. With IVFFlat indexing in -pgvector, similarity search remains O(log n) even with large enrollment -databases. Redis provides session caching to reduce database load. Based on -our benchmarks, a single instance handles over 100 concurrent verification -requests, and we can scale linearly by adding more instances." -``` - -#### Q11: "What's the false positive rate for your liveness detection?" - -**Answer:** -``` -"Our hybrid approach targets a false positive rate below 2% for spoof detection. -The combination of active challenges - which are unpredictable - with passive -texture analysis creates two independent barriers. In our testing with printed -photos and screen replays, detection accuracy exceeded 98%. However, we -acknowledge that sophisticated 3D masks would require additional countermeasures -planned for future versions." -``` - -#### Q12: "Why not use a dedicated vector database like Pinecone or Milvus?" - -**Answer:** -``` -"We did evaluate dedicated vector databases during our architecture design. -The primary reason we chose pgvector is unified transactions - enrollment -becomes atomic with user data, maintaining full referential integrity. -Additionally, operational simplicity matters greatly; having one database to -backup, monitor, and maintain reduces our operational burden significantly. -And frankly, the performance is sufficient - IVFFlat handles over 100,000 -embeddings with sub-10ms query times. For enterprise scale beyond one million -enrollments, we would certainly consider Milvus or Pinecone as a future -enhancement." -``` - ---- - -## 6. Checklist Before Presentation - -### One Week Before - -- [ ] Create all technical diagrams manually (Draw.io/Excalidraw) -- [ ] Capture required screenshots (Swagger, Dashboard, NFC) -- [ ] Upload Marmara University logo -- [ ] Replace team photos (use real photos or remove) -- [ ] Practice full presentation (target: under 12 minutes) -- [ ] Test all transition scripts with actual presenters -- [ ] Verify GitHub repository is accessible (public or shared with jury) - -### Day Before - -- [ ] Verify slide count: 15 slides -- [ ] Check page numbers on ALL slides (1/15 through 15/15) -- [ ] Verify figure captions on ALL diagrams -- [ ] Confirm advisor name: "Assoc. Prof. Dr. Mustafa Agaoglu" -- [ ] Remove any fake contact information -- [ ] Test presentation on projector/large screen -- [ ] Check font readability from back of room -- [ ] Prepare backup slides for common Q&A topics -- [ ] Have offline PDF version ready -- [ ] Do a full run-through with timer - -### Morning Of - -- [ ] Arrive 15 minutes early -- [ ] Test laptop-projector connection -- [ ] Have backup on USB drive -- [ ] Bring printed notes for each presenter -- [ ] Water bottles for presenters -- [ ] Load demo API in browser tab (Swagger UI at localhost:8001/docs) -- [ ] Disable screen notifications/popups on presenting laptop -- [ ] Have timer visible to all presenters - -### During Presentation - -- [ ] **Aysenur presents slides 1-5** (Opening & Problem Context) - ~4:00 -- [ ] *TRANSITION 1: Aysenur hands off to Ahmet* -- [ ] **Ahmet presents slides 6-10** (Technical Innovation + Biometric Demo) - ~4:10 -- [ ] *TRANSITION 2: Ahmet hands off to Gulsum* -- [ ] **Gulsum presents slides 11-16** (Doc Demo + Implementation + References) - ~3:40 -- [ ] **All together for slide 17** (Q&A) - ~3:00 -- [ ] Watch the clock - 12:00 target for presentation -- [ ] Smooth transitions - keep them brief -- [ ] **BALANCED: 5 slides / 5 slides / 6 slides per presenter** - ---- - -## Key Numbers to Memorize - -| Metric | Value | Context | -|--------|-------|---------| -| Total Slides | 17 | 16:9 aspect ratio | -| Implemented Features | 22 | All categories | -| API Endpoints | 40+ | Biometric Processor | -| Embedding Dimensions | 2622-D | VGG-Face default | -| EAR Threshold | < 0.2 | Blink detection | -| Cosine Threshold | 0.68 | Verification match | -| Facial Landmarks | 468 | MediaPipe Face Mesh | -| Card Types | 10+ | Turkish eID, e-Passport, MIFARE | -| Specialized NFC Readers | 7 | Factory pattern | -| Web Demo Pages | 6 | Interactive interfaces | -| Target FAR | < 1% | False Acceptance Rate | -| Spoof Detection | > 98% | Liveness accuracy | - ---- - -## 7. Image Preparation Checklist for Demo Slides - -The demo slides (8 and 11) require real screenshots from your system. Capture these before the presentation: - -### For SLIDE 8: Biometric Processor Demo - -| Image | Description | How to Capture | -|-------|-------------|----------------| -| **Ahmet's face + 468 mesh** | Face with MediaPipe landmarks overlay | Run web demo, capture with mesh visible | -| **Ayşenur's face + 468 mesh** | Face with MediaPipe landmarks overlay | Same process | -| **Gülsüm's face + 468 mesh** | Face with MediaPipe landmarks overlay | Same process | -| **All 3 LIVE status** | EAR values and "LIVE" checkmarks | Complete liveness test for each | - -### For SLIDE 11: Document Verification Demo - -| Image | Description | How to Capture | -|-------|-------------|----------------| -| **Turkish eID detection** | Card with bounding box + confidence | Point camera at Turkish ID | -| **e-Passport detection** | Passport with bounding box + confidence | Point camera at passport | -| **NFC scan screen** | "Hold card to phone" UI | Mobile app NFC screen | -| **Verification success** | BAC, DG1, DG2, SOD checkmarks | After successful NFC read | -| **DG2 photo** | High-res photo from chip | Extracted from NFC read | - -### Capture Tips - -1. **Good lighting** - Ensure faces are well-lit for clear mesh visualization -2. **Clean background** - Use simple background for cleaner screenshots -3. **Redact personal data** - Blur/redact any real personal information on IDs -4. **Consistent style** - Use same screenshot tool for uniform appearance - ---- - -**Document Created:** December 30, 2025 -**Last Updated:** January 1, 2026 (v6 - 17 slides, BALANCED: 5/5/6 slides per presenter, ~4 min each) -**Author:** Generated for FIVUCSAS Team -**Purpose:** Complete Presentation Guide for January 7, 2026 Defense diff --git a/archive/2026-04-16/PRESENTATION_SPEECHES.md b/archive/2026-04-16/PRESENTATION_SPEECHES.md deleted file mode 100644 index 558e247..0000000 --- a/archive/2026-04-16/PRESENTATION_SPEECHES.md +++ /dev/null @@ -1,442 +0,0 @@ -# FIVUCSAS Presentation Speeches - -**Date:** January 7, 2026 -**Duration:** 12 minutes + 3 minutes Q&A -**Total Slides:** 18 - ---- - -## Presenter Distribution - -| Presenter | Slides | Time | Content | -|-----------|--------|------|---------| -| **Aysenur Arici** | 1-6 | ~4:00 | Title, Outline, Problem, Related Work, Related Works Table, Scope | -| **Ahmet Abdullah Gultekin** | 7-13 | ~4:00 | Architecture, Biometric Puzzle, NFC, ML Pipeline, Demos | -| **Ayse Gulsum Eren** | 14-18 | ~4:00 | Tasks, Semester Plan, Challenges, References, Q&A | - ---- - -# AYSENUR ARICI (Slides 1-6) — ~4 minutes - ---- - -## SLIDE 1: Title Slide (25 sec) - -``` -Good morning everyone. We are presenting FIVUCSAS — Face and Identity -Verification Using Cloud-Based SaaS Models. - -I am Aysenur Arici. With me are my teammates Ahmet Abdullah Gultekin and -Ayse Gulsum Eren. Our project supervisor is Associate Professor Doctor -Mustafa Agaoglu. -``` - ---- - -## SLIDE 2: Outline — WHY / HOW / WHAT (25 sec) - -``` -Our presentation follows three parts. - -WHY — the problem, related work, and project scope. - -HOW — system architecture, Biometric Puzzle, card and NFC verification, -machine learning pipeline, and live demos. - -WHAT — tasks completed, semester two plan, challenges, and references. -``` - ---- - -## SLIDE 3: The Threat is Real (50 sec) - -``` -Identity fraud is exploding. - -23 billion dollars lost to identity fraud in 2024. 400 percent increase -in deepfake attacks year over year. And 1 in 4 people cannot detect a -deepfake from a real person. - -Deepfakes are the new weapon for fraudsters. - -Our goal with FIVUCSAS is un-spoofable verification — proving the person -is live, present, and holding an authentic document. -``` - ---- - -## SLIDE 4: Related Work — Categories (40 sec) - -``` -We studied three areas of related work. - -First, Deep Face Recognition — DeepFace, FaceNet, and ArcFace provide -embedding-based verification with high accuracy. - -Second, Liveness Detection — existing solutions offer passive and active -methods for anti-spoofing, but they remain isolated. - -Third, the Integration Gap — no solution offers multi-tenant support, -cloud-native deployment, and end-to-end verification in one system. - -This gap leads us to FIVUCSAS. -``` - ---- - -## SLIDE 5: Related Works — Comparison Table (50 sec) - -``` -This table compares Azure Face Liveness, AWS Rekognition, Sodec -Technologies, FaceAuth Vision, BioGATE Pass, and FIVUCSAS. - -For Open Source — only FaceAuth and FIVUCSAS provide it. - -For Liveness Detection — Sodec and FaceAuth lack it entirely. - -For Multi-Tenant SaaS — Sodec, FaceAuth, and BioGATE do not support it. - -For PAD Compliance — Sodec and FaceAuth are missing. - -The gap: Most solutions lack physical document verification through NFC -and rely on singular, predictable liveness checks. - -Our advantage: We bridge the physical-digital gap with our unpredictable -Biometric Puzzle. -``` - ---- - -## SLIDE 6: Scope (40 sec) - -``` -Our project scope has three parts. - -In scope — six core deliverables: face recognition, cloud database, NFC -reading, server infrastructure, mobile applications, and software platform. - -Out of scope — hardware manufacturing. We focus purely on software. - -Engineering constraints: Image quality over 100 kilobytes, API latency -under 200 milliseconds, and NFC following ICAO Document 9303 standards. - -Now, Ahmet will explain how we built the solution. -``` - ---- - -# AHMET ABDULLAH GULTEKIN (Slides 7-13) — ~4 minutes - ---- - -## SLIDE 7: System Architecture (45 sec) - -``` -Thank you Aysenur. - -Client applications use Kotlin Multiplatform for Android, iOS, and Desktop. - -Requests flow through NGINX as our API Gateway for load balancing and -rate limiting. - -Identity Core — a Spring Boot application with 130 Java files handling -authentication, multi-tenancy, and role-based access control. - -Biometric Processor — a FastAPI service with 254 Python files handling -face detection, liveness analysis, and embedding extraction. - -PostgreSQL with pgvector provides vector similarity search using IVFFlat -indexing with O log n performance. Redis handles caching and event bus. - -Architecture follows Hexagonal pattern with Domain-Driven Design. -``` - ---- - -## SLIDE 8: The Biometric Puzzle (45 sec) - -``` -The Biometric Puzzle is our key innovation — hybrid liveness detection. - -The challenge-response protocol works in four steps: - -Step 1 — Server generates a random challenge like "Blink Left Eye" or -"Turn Head Right." Unpredictable. - -Step 2 — Client captures video and tracks 468 facial landmarks using -MediaPipe. - -Step 3 — We calculate Eye Aspect Ratio. When EAR drops below 0.2, a -blink is detected. - -Step 4 — Parallel passive texture analysis detects screens or printed -photos. - -We detect four actions: neutral, blink, smile, and head turn. This -defeats deepfakes and replay attacks. -``` - ---- - -## SLIDE 9: Card Detection & NFC Verification (35 sec) - -``` -Document verification has two stages. - -On-Device Card Detection — our trained model recognizes over 10 card -types including Turkish eID and passports. Automatic identification. - -NFC Chip Verification — we perform BAC handshake using MRZ-derived keys, -read DG1 for personal data and DG2 for high-resolution photo, then verify -the SOD digital signature proving authenticity. -``` - ---- - -## SLIDE 10: ML Pipeline & Vector Search (35 sec) - -``` -Our machine learning pipeline has five stages. - -Input — raw user image exceeding 480p resolution. - -Detect — identify face region with bounding box. - -Align — normalize orientation using facial landmarks. - -Extract — convert to high-dimensional embedding vector. - -Search — compare against database using vector search. With pgvector -and IVFFlat indexing, we achieve sub-millisecond queries. -``` - ---- - -## SLIDE 11: Live Demo — Team Recognition (25 sec) - -``` -Here is our system recognizing all three team members simultaneously. - -The system tracks 468 facial landmarks per face with real-time metrics: -quality scores ranging from 75 to 100 percent, age estimation, mood -detection, and liveness percentage. - -Each person is matched to their enrolled profile with confidence scores -from 64 to 84 percent at 13.4 frames per second. -``` - ---- - -## SLIDE 12: Live Demo — Passport Verification (25 sec) - -``` -This demo shows passport-to-face verification. - -The passport photo shows Quality 100% but Liveness N — correctly -identifying it as a document photo. - -The live person shows Liveness Y at 61%. Both faces match the same -enrolled person with 80% confidence. - -This verifies a live person matches their identity document. -``` - ---- - -## SLIDE 13: Live Demo — Biometric Puzzle & Card Detection (25 sec) - -``` -Multiple features working together. - -Biometric Puzzle challenge "Smile Wide, Show Teeth" with 97% hold progress. - -Card detection recognizing a passport at 93% confidence. - -Another challenge "Turn Head Left" — challenge 3 of 3 with 92% hold -progress. - -Now Gulsum will present what we accomplished this semester. -``` - ---- - -# AYSE GULSUM EREN (Slides 14-18) — ~4 minutes - ---- - -## SLIDE 14: Tasks Completed (55 sec) - -``` -Thank you Ahmet. Here is everything we built this semester. - -Biometrics — Face Detection, Liveness Check with our Biometric Puzzle, -Face Mesh tracking 468 landmarks, Quality Score assessment, and -Anti-Spoofing detection. - -Document Verification — ID Card recognition, NFC Read, Passport support, -and OCR Scan. - -Infrastructure — Security with JWT authentication, Servers, Database with -PostgreSQL and pgvector, REST API, Cloud deployment, and Monitoring. - -Summary: Full-stack system developed. Robust SaaS infrastructure built. -Core biometric pipeline complete. NFC reader module completed. Demo UI -completed. -``` - ---- - -## SLIDE 15: Second Semester Plan (45 sec) - -``` -For Spring 2026: - -February to March — Complete Application Development. - -March to April — Finalize Service-to-Service Integration. - -April to May — Conduct End-to-End Security Testing and Penetration Testing. - -May — Prepare for Production Deployment and Documentation. - -Contingency Plans: - -NFC Failure — scope narrows to Turkish eID only initially. - -High WebSocket Latency — fallback to REST polling. - -Mobile App Delayed — prioritize Desktop-first deployment. -``` - ---- - -## SLIDE 16: Technical Challenges (45 sec) - -``` -We faced two major technical challenges. - -First — Training a performant on-device Card Detection Model. Our YOLO -model confused Marmara University student cards versus staff cards due -to minimal visual differences in color and layout. We collected more -training data and fine-tuned the model. - -Second — Cross-Language Microservice Communication. Our Java Spring -service needed to communicate with Python FastAPI. We designed a robust -contract using REST APIs and implemented a shared Redis cache for state -management. -``` - ---- - -## SLIDE 17: References (20 sec) - -``` -Our key references: - -DeepFace, FaceNet, and ArcFace for face recognition. -MediaPipe for facial landmark detection. -ISO standards for NFC implementation. -Azure Face Liveness and Amazon Rekognition for commercial benchmarking. -Sodec Technologies and BioGATE for Turkish market analysis. -``` - ---- - -## SLIDE 18: Thank You & Questions (10 sec + Q&A) - -``` -Thank you for your attention. - -We welcome your questions. -``` - ---- - -# TRANSITIONS - -**After Slide 6 (Aysenur → Ahmet):** -``` -Aysenur: "Now, Ahmet will explain how we built the solution." -Ahmet: "Thank you Aysenur." -``` - -**After Slide 13 (Ahmet → Gulsum):** -``` -Ahmet: "Now Gulsum will present what we accomplished this semester." -Gulsum: "Thank you Ahmet. Here is everything we built this semester." -``` - ---- - -# TIMING SUMMARY - -| Presenter | Slides | Content | Target | -|-----------|--------|---------|--------| -| Aysenur | 1-6 | Title, Outline, Problem, Related Work x2, Scope | 4:00 | -| Ahmet | 7-13 | Architecture, Puzzle, NFC, ML, Demos x3 | 4:00 | -| Gulsum | 14-18 | Tasks, Plan, Challenges, Refs, Q&A | 4:00 | -| **TOTAL** | **18** | | **12:00** | - ---- - -# KEY NUMBERS TO REMEMBER - -| Metric | Value | -|--------|-------| -| Identity Fraud Losses | $23 Billion | -| Deepfake Attack Increase | +400% | -| Cannot Detect Deepfakes | 1 in 4 people | -| Facial Landmarks | 468 points | -| EAR Blink Threshold | < 0.2 | -| Java Files | 130 | -| Python Files | 254 | -| Supported Card Types | 10+ | -| Image Quality Requirement | > 100kb | -| Latency Requirement | < 200ms | - ---- - -# Q&A PREPARATION - -**Q: How does the Biometric Puzzle prevent deepfakes?** -``` -Deepfakes are pre-generated. Our challenges are random and unpredictable — -the attacker cannot know if we will ask for a blink, smile, or head turn. -By the time they generate a response, the challenge expires. Plus, passive -texture analysis detects screen artifacts. -``` - -**Q: Why two programming languages (Java + Python)?** -``` -Each language serves its optimal purpose. Python handles ML workloads -because MediaPipe, DeepFace, and OpenCV are Python-native. Java with -Spring Boot handles enterprise concerns — authentication, multi-tenancy, -RBAC. This enables independent scaling. -``` - -**Q: What is your verification accuracy?** -``` -Using cosine similarity, we target False Acceptance Rate below 1% and -False Rejection Rate below 3%. Demo showed match confidences between -64% and 84% for enrolled users. -``` - -**Q: What happens if NFC reading fails?** -``` -Our Plan B: If NFC proves unreliable across card types, we narrow scope -to Turkish eID only — which we have thoroughly tested. -``` - -**Q: What is PAD Compliance?** -``` -PAD stands for Presentation Attack Detection — the ISO 30107 standard -for liveness detection. Our Biometric Puzzle provides PAD compliance -through unpredictable challenge-response testing. -``` - ---- - -**Document Updated:** January 3, 2026 -**Based on:** FIVUCSAS-Pre.pdf — 18 slides -**Purpose:** January 7, 2026 Presentation Defense - diff --git a/archive/2026-04-16/QUICK_START_PGVECTOR.md b/archive/2026-04-16/QUICK_START_PGVECTOR.md deleted file mode 100644 index 6bfe6d8..0000000 --- a/archive/2026-04-16/QUICK_START_PGVECTOR.md +++ /dev/null @@ -1,262 +0,0 @@ -# Quick Start: Enable pgvector for Face Embeddings - -This guide shows you how to enable PostgreSQL with pgvector for persistent face embedding storage in FIVUCSAS. - -## Prerequisites - -- Docker and Docker Compose installed -- FIVUCSAS project cloned -- Basic understanding of environment variables - -## Steps - -### 1. Enable pgvector in Biometric Processor - -Edit `docker-compose.yml` and set: - -```yaml -biometric-processor: - environment: - USE_PGVECTOR: "True" # Change from "False" to "True" - EMBEDDING_DIMENSION: 512 # Match your FACE_MODEL -``` - -Or create/edit `biometric-processor/.env`: - -```bash -USE_PGVECTOR=True -EMBEDDING_DIMENSION=512 -DATABASE_URL=postgresql://postgres:postgres_dev_password@postgres:5432/identity_core_db -``` - -### 2. Match Embedding Dimension to Face Model - -| Face Model | Embedding Dimension | Configuration | -|------------|---------------------|---------------| -| Facenet512 | 512 | `FACE_MODEL=Facenet512`
`EMBEDDING_DIMENSION=512` | -| VGG-Face | 2622 | `FACE_MODEL=VGG-Face`
`EMBEDDING_DIMENSION=2622` | -| ArcFace | 512 | `FACE_MODEL=ArcFace`
`EMBEDDING_DIMENSION=512` | -| OpenFace | 128 | `FACE_MODEL=OpenFace`
`EMBEDDING_DIMENSION=128` | - -**Example for FaceNet (Recommended)**: - -```yaml -FACE_MODEL: Facenet512 -EMBEDDING_DIMENSION: 512 -USE_PGVECTOR: "True" -``` - -### 3. Restart Services - -```bash -# Stop all services -docker-compose down - -# Start services (database will auto-initialize) -docker-compose up -d - -# Check logs -docker-compose logs biometric-processor | grep -i pgvector -# Should see: "Creating embedding repository (pgvector)" -``` - -### 4. Verify Setup - -Check if pgvector is working: - -```bash -# Connect to database -docker-compose exec postgres psql -U postgres -d identity_core_db - -# Verify pgvector extension -\dx -# Should show "vector" extension - -# Check biometric_data table -\d biometric_data -# Should show "embedding" column of type "vector" - -# Exit -\q -``` - -### 5. Test Face Enrollment - -Enroll a face via API: - -```bash -curl -X POST http://localhost:8001/api/v1/enroll \ - -F "user_id=test-user-123" \ - -F "tenant_id=test-tenant" \ - -F "image=@/path/to/face.jpg" -``` - -Verify in database: - -```bash -docker-compose exec postgres psql -U postgres -d identity_core_db -c \ - "SELECT user_id, embedding_model, embedding_dimension, quality_score FROM biometric_data WHERE user_id = 'test-user-123';" -``` - -## Switching from In-Memory to pgvector - -### What Happens - -- **Before**: Face embeddings stored in RAM, lost on restart -- **After**: Face embeddings stored in PostgreSQL, persistent across restarts - -### Important Notes - -1. **Data Migration**: Existing in-memory embeddings are NOT automatically migrated - - Users must re-enroll their faces after enabling pgvector - -2. **Database Initialization**: - - First startup creates necessary tables and indexes - - This is handled automatically by Flyway migrations - -3. **Performance**: - - In-memory: Faster (no network/disk overhead) - - pgvector: Slightly slower but scales to millions of faces - -## Configuration Options - -### Connection Pool Tuning - -For high-concurrency systems: - -```yaml -DATABASE_POOL_MIN_SIZE: 20 -DATABASE_POOL_MAX_SIZE: 50 -``` - -For low-concurrency systems (save resources): - -```yaml -DATABASE_POOL_MIN_SIZE: 5 -DATABASE_POOL_MAX_SIZE: 10 -``` - -### Production Configuration - -```yaml -# Production settings -ENVIRONMENT: production -USE_PGVECTOR: "True" -DATABASE_URL: postgresql://biometric_user:STRONG_PASSWORD@db.example.com:5432/fivucsas_prod -DATABASE_POOL_MIN_SIZE: 20 -DATABASE_POOL_MAX_SIZE: 50 - -# Use FaceNet for production (good balance of accuracy and speed) -FACE_MODEL: Facenet512 -EMBEDDING_DIMENSION: 512 -SIMILARITY_THRESHOLD: 0.4 -``` - -## Troubleshooting - -### "pgvector extension not found" - -**Symptom**: Error during startup about missing pgvector - -**Solution**: -```bash -docker-compose down -docker-compose pull postgres # Pull latest pgvector/pgvector:pg16 image -docker-compose up -d -``` - -### "Embedding dimension mismatch" - -**Symptom**: Error like "expected 512, got 2622" - -**Cause**: `EMBEDDING_DIMENSION` doesn't match `FACE_MODEL` - -**Solution**: Check the table above and ensure they match - -### "Connection refused" or "Pool exhausted" - -**Symptom**: Cannot connect to database or pool is full - -**Solutions**: -1. Check if PostgreSQL is running: `docker-compose ps postgres` -2. Increase pool size: `DATABASE_POOL_MAX_SIZE=50` -3. Check database logs: `docker-compose logs postgres` - -### Slow similarity search - -**Symptom**: Face search takes >1 second - -**Solutions**: - -1. Check if vector index exists: - ```sql - SELECT indexname FROM pg_indexes - WHERE tablename = 'biometric_data' AND indexname LIKE '%embedding%'; - ``` - -2. If missing, create index: - ```sql - CREATE INDEX idx_biometric_embedding_ivfflat - ON biometric_data - USING ivfflat (embedding vector_cosine_ops) - WITH (lists = 100) - WHERE deleted_at IS NULL AND is_active = TRUE; - ``` - -3. Analyze table: - ```sql - ANALYZE biometric_data; - ``` - -## Monitoring - -### Check Embedding Count - -```bash -docker-compose exec postgres psql -U postgres -d identity_core_db -c \ - "SELECT COUNT(*) FROM biometric_data WHERE is_active = TRUE AND deleted_at IS NULL;" -``` - -### Check Average Quality - -```bash -docker-compose exec postgres psql -U postgres -d identity_core_db -c \ - "SELECT embedding_model, AVG(quality_score) as avg_quality, COUNT(*) as total FROM biometric_data WHERE is_active = TRUE GROUP BY embedding_model;" -``` - -### View Statistics - -```bash -docker-compose exec postgres psql -U postgres -d identity_core_db -c \ - "SELECT * FROM biometric_statistics;" -``` - -## Rollback to In-Memory - -If you need to revert to in-memory storage: - -1. Edit `docker-compose.yml`: - ```yaml - USE_PGVECTOR: "False" - ``` - -2. Restart: - ```bash - docker-compose restart biometric-processor - ``` - -**Note**: Database data remains intact; you can switch back anytime. - -## Next Steps - -- Read full documentation: `docs/PGVECTOR_SETUP.md` -- Configure face recognition model: `docs/FACE_RECOGNITION_MODELS.md` -- Production deployment guide: `docs/PRODUCTION_DEPLOYMENT.md` -- Performance tuning: `docs/PERFORMANCE_TUNING.md` - -## Support - -For issues or questions: -1. Check application logs: `docker-compose logs biometric-processor` -2. Check database logs: `docker-compose logs postgres` -3. Review full documentation: `docs/PGVECTOR_SETUP.md` diff --git a/archive/2026-04-16/SYSTEM_DESIGN_ANALYSIS_AND_DECISION.md b/archive/2026-04-16/SYSTEM_DESIGN_ANALYSIS_AND_DECISION.md deleted file mode 100644 index 87d0cd0..0000000 --- a/archive/2026-04-16/SYSTEM_DESIGN_ANALYSIS_AND_DECISION.md +++ /dev/null @@ -1,604 +0,0 @@ -# 🔍 FIVUCSAS - System Design Analysis & Critical Decision - -**Date:** November 3, 2025 -**Status:** ⚠️ CRITICAL DECISION POINT -**Scope:** Complete System Design Review Before Moving Forward - ---- - -## 📊 EXECUTIVE SUMMARY - -### Current Situation - -**✅ EXCELLENT:** -- Desktop UI is production-ready (94/100 quality score) -- Perfect SOLID principles implementation -- 53 reusable components -- Clean MVVM architecture - -**❌ CRITICAL GAPS:** -- ViewModels are in `desktopApp/` (should be in `shared/`) -- No Repository Pattern (violates Clean Architecture) -- No Dependency Injection (not testable) -- No API integration layer -- No error handling strategy -- Zero tests - -**VERDICT: Architecture needs refactoring BEFORE adding features** - ---- - -## 🎯 THE CORE PROBLEM - -### You Asked: "mobile-app folder includes mobile AND desktop - what to do?" - -**ANSWER: Keep the folder name BUT refactor the internal architecture!** - -### Why "mobile-app" Name is Fine ✅ - -1. **It's a Kotlin Multiplatform project** - supports mobile (Android/iOS) AND desktop (Windows/Mac/Linux) -2. **Industry standard** - Many KMP projects use generic names -3. **Not worth the disruption** - Renaming causes Git history issues - -### What's Actually Wrong ❌ - -**The problem is NOT the folder name.** - -**The problem is the ARCHITECTURE inside:** - -``` -mobile-app/ -├── desktopApp/ ← Has ViewModels (WRONG!) -│ └── viewmodel/ ← Business logic should NOT be here! -├── androidApp/ ← Empty (will duplicate ViewModels!) -├── shared/ ← EMPTY! (should contain ViewModels!) -└── iosApp/ ← Empty (will duplicate ViewModels!) -``` - -**This violates Kotlin Multiplatform principles!** - ---- - -## 🏗️ CORRECT vs INCORRECT Architecture - -### ❌ CURRENT (INCORRECT) - -``` -mobile-app/ -├── desktopApp/ -│ └── src/desktopMain/kotlin/ -│ ├── Main.kt -│ ├── viewmodel/ ❌ ViewModels here = WRONG! -│ │ ├── AppStateManager.kt ❌ Desktop-only -│ │ ├── KioskViewModel.kt ❌ Desktop-only -│ │ └── AdminViewModel.kt ❌ Desktop-only -│ ├── data/ ❌ Models here = WRONG! -│ │ ├── User.kt -│ │ └── EnrollmentData.kt -│ └── ui/ -│ ├── kiosk/KioskMode.kt ✅ UI only = CORRECT -│ └── admin/AdminDashboard.kt ✅ UI only = CORRECT -│ -├── androidApp/ -│ └── src/main/kotlin/ -│ └── MainActivity.kt ⚠️ Will need to duplicate ViewModels! -│ -└── shared/ - └── src/commonMain/kotlin/ ❌ EMPTY! -``` - -**PROBLEMS:** -1. 🔴 ViewModels are desktop-specific → Android/iOS will duplicate them -2. 🔴 Models are desktop-specific → Can't share with Android/iOS -3. 🔴 No repository pattern → Data access mixed with UI -4. 🔴 No DI → Can't inject dependencies -5. 🔴 Not multiplatform → Defeats the purpose of KMP! - ---- - -### ✅ CORRECT (AFTER REFACTORING) - -``` -mobile-app/ -├── shared/ ✅ All business logic here! -│ └── src/commonMain/kotlin/ -│ ├── domain/ ✅ Business Rules -│ │ ├── model/ -│ │ │ ├── User.kt ✅ Shared everywhere -│ │ │ ├── EnrollmentData.kt -│ │ │ └── BiometricData.kt -│ │ ├── repository/ ✅ Interfaces -│ │ │ ├── UserRepository.kt -│ │ │ ├── BiometricRepository.kt -│ │ │ └── AuthRepository.kt -│ │ └── usecase/ ✅ Business Logic -│ │ ├── EnrollUserUseCase.kt -│ │ ├── VerifyUserUseCase.kt -│ │ └── GetUsersUseCase.kt -│ │ -│ ├── data/ ✅ Data Access -│ │ ├── repository/ ✅ Implementations -│ │ │ ├── UserRepositoryImpl.kt -│ │ │ └── BiometricRepositoryImpl.kt -│ │ ├── remote/ ✅ API Calls -│ │ │ ├── api/ -│ │ │ │ ├── IdentityApi.kt -│ │ │ │ └── BiometricApi.kt -│ │ │ ├── dto/ -│ │ │ └── KtorClient.kt -│ │ └── local/ ✅ Caching -│ │ └── cache/ -│ │ -│ └── presentation/ ✅ UI Logic -│ ├── viewmodel/ ✅ SHARED ViewModels! -│ │ ├── AppStateManager.kt -│ │ ├── KioskViewModel.kt -│ │ └── AdminViewModel.kt -│ └── state/ ✅ UI States -│ ├── UiState.kt -│ ├── EnrollmentState.kt -│ └── VerificationState.kt -│ -├── desktopApp/ ✅ Desktop UI ONLY -│ └── src/desktopMain/kotlin/ -│ ├── Main.kt ✅ Desktop entry point -│ ├── di/ -│ │ └── DesktopModule.kt ✅ Desktop DI config -│ └── ui/ ✅ Desktop-specific UI -│ ├── kiosk/ -│ │ └── KioskMode.kt ✅ Uses shared ViewModel -│ └── admin/ -│ └── AdminDashboard.kt ✅ Uses shared ViewModel -│ -├── androidApp/ ✅ Android UI ONLY -│ └── src/main/kotlin/ -│ ├── MainActivity.kt ✅ Android entry point -│ ├── di/ -│ │ └── AndroidModule.kt ✅ Android DI config -│ └── ui/ ✅ Android-specific UI -│ ├── kiosk/ -│ │ └── KioskScreen.kt ✅ Uses SAME shared ViewModel! -│ └── admin/ -│ └── AdminScreen.kt ✅ Uses SAME shared ViewModel! -│ -└── iosApp/ ✅ iOS UI ONLY - └── iosApp/ - └── ContentView.swift ✅ iOS UI (SwiftUI) - ✅ Uses SAME shared ViewModel! -``` - -**BENEFITS:** -1. ✅ ViewModels written ONCE, used everywhere -2. ✅ Business logic shared 100% -3. ✅ Easy to test (test shared module) -4. ✅ Easy to maintain (fix once, works everywhere) -5. ✅ True multiplatform (KMP done right!) - ---- - -## 📋 CRITICAL DECISION: What to Do NOW? - -### Option 1: "Start Day 1" - Begin Refactoring ⭐ RECOMMENDED - -**What this means:** -- Spend 3-4 days refactoring architecture -- Move ViewModels to `shared/` -- Implement Clean Architecture -- Add Repository Pattern -- Setup Dependency Injection -- Add error handling -- Write tests - -**Why do this:** -- ✅ Prevents months of technical debt -- ✅ Makes future features MUCH easier -- ✅ Enables true code sharing (90%+) -- ✅ Makes testing possible -- ✅ Production-ready architecture - -**Timeline:** -- Day 1: Move to shared module, create layers -- Day 2: Implement Repository Pattern -- Day 3: Setup Dependency Injection -- Day 4: Add error handling & validation -- Day 5: Write tests - ---- - -### Option 2: Keep "mobile-app" - Continue to Day 2 ✅ - -**What this means:** -- Keep folder name as "mobile-app" -- BUT still do the refactoring (Option 1) -- Folder name is fine, internal structure needs work - -**Why do this:** -- ✅ Folder name is not the problem -- ✅ Avoids Git history issues -- ✅ Industry standard name for KMP projects - -**My Recommendation: YES to this option!** - ---- - -### Option 3: Continue to Day 3 - Use Cases & Validation - -**What this means:** -- Skip refactoring -- Add use cases directly -- Add validation - -**Problems:** -- ❌ Still have ViewModels in wrong place -- ❌ Still no repository pattern -- ❌ Adding features on broken foundation -- ⚠️ Will need to refactor later (much harder) - -**My Recommendation: NO - Refactor first!** - ---- - -### Option 4: Continue to Day 4 - Testing ⚠️ - -**What this means:** -- Skip refactoring -- Start writing tests - -**Problems:** -- ❌ Can't test properly without DI -- ❌ Can't mock repositories (don't exist) -- ❌ Tests will need rewriting after refactoring - -**My Recommendation: NO - Refactor first, then test!** - ---- - -## 🎯 MY STRONG RECOMMENDATION - -### ✅ DO THIS: "Start Day 1" Refactoring (Option 1) - -**Why?** - -1. **Desktop app is already excellent** - We just need to move things to `shared/` -2. **3-4 days now saves MONTHS later** - Technical debt compounds -3. **You'll implement Android/iOS faster** - 90% code reuse -4. **Testing becomes possible** - Can't test without DI -5. **Production-ready architecture** - Industry best practices - -**What exactly will we do?** - -### Day 1: Shared Module Architecture (6-8 hours) - -```bash -# Create Clean Architecture layers -mobile-app/shared/src/commonMain/kotlin/ -├── domain/ -│ ├── model/ -│ ├── repository/ -│ └── usecase/ -├── data/ -│ ├── repository/ -│ ├── remote/ -│ └── local/ -└── presentation/ - ├── viewmodel/ - └── state/ - -# Move existing code: -1. Move User.kt, EnrollmentData.kt → domain/model/ -2. Move ViewModels → presentation/viewmodel/ -3. Create repository interfaces → domain/repository/ -4. Create repository implementations → data/repository/ -``` - -### Day 2: Repository Pattern (6-8 hours) - -```kotlin -// Create repository interfaces -interface UserRepository { - suspend fun getUsers(): Result> - suspend fun createUser(user: User): Result -} - -interface BiometricRepository { - suspend fun enrollFace(userId: String, image: ByteArray): Result - suspend fun verifyFace(image: ByteArray): Result -} - -// Create use cases -class EnrollUserUseCase( - private val userRepo: UserRepository, - private val biometricRepo: BiometricRepository -) { - suspend operator fun invoke( - userData: EnrollmentData, - faceImage: ByteArray - ): Result { - // Business logic here - } -} - -// Refactor ViewModels to use use cases -class KioskViewModel( - private val enrollUserUseCase: EnrollUserUseCase -) : ViewModel() { - fun enrollUser(data: EnrollmentData, image: ByteArray) { - viewModelScope.launch { - enrollUserUseCase(data, image) - .onSuccess { /* ... */ } - .onFailure { /* ... */ } - } - } -} -``` - -### Day 3: Dependency Injection (4-6 hours) - -```kotlin -// Setup Koin -val dataModule = module { - single { UserRepositoryImpl(get()) } - single { BiometricRepositoryImpl(get()) } -} - -val domainModule = module { - factory { EnrollUserUseCase(get(), get()) } -} - -val presentationModule = module { - viewModel { KioskViewModel(get()) } - viewModel { AdminViewModel(get()) } -} - -// In composables -@Composable -fun KioskMode( - viewModel: KioskViewModel = koinViewModel() // ✅ Injected! -) { - // ... -} -``` - -### Day 4: Error Handling & Validation (4-6 hours) - -```kotlin -// Create UiState sealed class -sealed class UiState { - object Idle : UiState() - object Loading : UiState() - data class Success(val data: T) : UiState() - data class Error(val message: String) : UiState() -} - -// Add validation -object ValidationRules { - fun validateEmail(email: String): ValidationResult { /* ... */ } - fun validateNationalId(id: String): ValidationResult { /* ... */ } -} - -// Use in ViewModels -private val _state = MutableStateFlow>(UiState.Idle) -val state: StateFlow> = _state.asStateFlow() -``` - -### Day 5: Testing (Optional - can be done later) - -```kotlin -class KioskViewModelTest { - @Test - fun `enrollUser with valid data should emit Success state`() = runTest { - // Test implementation - } -} -``` - ---- - -## 📊 COMPARISON: Refactor Now vs Later - -| Aspect | Refactor NOW (Day 1) | Refactor LATER (After features) | -|--------|---------------------|----------------------------------| -| **Time Investment** | 3-4 days | 2-3 WEEKS | -| **Risk** | Low (nothing built yet) | HIGH (break existing features) | -| **Code Quality** | Excellent from start | Poor, then refactored | -| **Testing** | Easy to add | Hard (need to refactor first) | -| **Feature Development** | Fast (clean architecture) | Slow (fighting tech debt) | -| **Team Morale** | High (clean code) | Low (constant refactoring) | -| **Production Readiness** | Yes | No (until refactored) | - -**VERDICT: Refactor NOW is 5-10x cheaper than refactoring later!** - ---- - -## 🎯 FINAL RECOMMENDATION - -### ✅ PLAN: "Option 1 + Option 2 Combined" - -**Folder Structure:** -- ✅ Keep "mobile-app" folder name (it's fine!) -- ✅ Keep desktopApp, androidApp, shared structure - -**Architecture:** -- ✅ Start Day 1 refactoring (3-4 days) -- ✅ Move ViewModels to shared/ -- ✅ Implement Clean Architecture -- ✅ Add Repository Pattern -- ✅ Setup Dependency Injection -- ✅ Add error handling - -**After Refactoring (Day 5+):** -- ✅ THEN add new features -- ✅ THEN implement Android app -- ✅ THEN implement iOS app -- ✅ THEN connect to backend - ---- - -## 🚀 NEXT STEPS - START NOW - -### Step 1: Confirm the Plan - -**Do you approve starting Day 1 refactoring?** - -- YES → I'll start creating the shared module architecture -- NO → Tell me what concerns you, we'll address them - -### Step 2: I'll Create (if you say YES) - -1. **Shared module architecture** - - domain/ layer - - data/ layer - - presentation/ layer - -2. **Move existing code** - - ViewModels → shared/presentation/ - - Models → shared/domain/model/ - -3. **Create repositories** - - Interfaces in domain/ - - Implementations in data/ - -4. **Setup Koin DI** - - DI modules - - Update composables - -5. **Add error handling** - - UiState sealed class - - Error handling in ViewModels - -**Estimated Time: 3-4 days of focused work** - -**Result: Production-ready, testable, maintainable architecture that will save you MONTHS of work!** - ---- - -## 💡 WHY THIS MATTERS - -### Current Desktop App Quality - -**Before Refactoring (Oct 2025):** -- Quality: 58/100 ❌ -- SOLID: 28/100 ❌ -- Magic values: 35 ❌ - -**After UI Refactoring (Nov 2025):** -- Quality: 94/100 ✅ -- SOLID: 95/100 ✅ -- Magic values: 0 ✅ - -**We proved refactoring WORKS and is WORTH IT!** - -### What This Refactoring Will Give Us - -**Before Architecture Refactoring:** -- Code sharing: 0% (each platform duplicates code) -- Testability: 20/100 (can't test properly) -- Maintainability: 40/100 (change in 3 places) - -**After Architecture Refactoring:** -- Code sharing: 90% (write once, use everywhere) ✅ -- Testability: 85/100 (full DI, mockable) ✅ -- Maintainability: 90/100 (change once, works everywhere) ✅ - ---- - -## 🎓 LESSONS FROM DESKTOP APP REFACTORING - -### What We Learned - -1. **Refactoring early is MUCH easier than refactoring late** - - Desktop UI refactoring took 8 hours - - If we'd waited until after features: would take 3-4 weeks - -2. **SOLID principles actually work** - - Quality jumped from 58 → 94 - - Maintainability dramatically improved - -3. **Component extraction makes code reusable** - - Created 53 reusable components - - Same components work in different contexts - -4. **Configuration management eliminates magic values** - - Easy to change behavior - - No hunting for hardcoded values - -### Apply Same Principles Now - -1. **Clean Architecture** (like SOLID for project structure) -2. **Repository Pattern** (like component extraction for data access) -3. **Dependency Injection** (like configuration management for dependencies) -4. **Error Handling** (like input validation for operations) - -**Same methodology, same excellent results!** - ---- - -## 📝 CONCLUSION - -### The Question -> "Do we need to refactor mobile-app repo/folder because it includes mobile and desktop, what to do now?" - -### The Answer - -**NO - Don't rename folder!** -**YES - DO refactor architecture inside!** - -### The Problem - -- ❌ NOT the folder name -- ✅ The architecture inside (ViewModels in wrong place) - -### The Solution - -1. ✅ Keep "mobile-app" folder name -2. ✅ Refactor to Clean Architecture (3-4 days) -3. ✅ Move ViewModels to shared/ -4. ✅ Implement Repository Pattern -5. ✅ Setup Dependency Injection -6. ✅ THEN build features - -### The Verdict - -**START DAY 1 REFACTORING NOW!** - -**Benefits:** -- ✅ 3-4 days investment -- ✅ Saves MONTHS of technical debt -- ✅ Enables 90% code sharing -- ✅ Makes testing possible -- ✅ Production-ready architecture - -**Alternative (Skip Refactoring):** -- ❌ Faster start (by 3 days) -- ❌ 2-3 WEEKS of refactoring later -- ❌ Broken features during refactor -- ❌ Low code sharing -- ❌ Can't test properly - ---- - -## ❓ YOUR DECISION - -**I recommend: Start Day 1 Refactoring NOW** - -**Your options:** - -### A) ✅ YES - Start Day 1 Refactoring -→ I'll begin creating shared module architecture immediately - -### B) ⚠️ MAYBE - I have concerns -→ Tell me your concerns, we'll address them - -### C) ❌ NO - Skip refactoring -→ I'll document why this will cause problems later - -**What's your decision?** 🎯 - ---- - -**Prepared by:** System Architecture Team -**Recommendation:** **REFACTOR NOW, SAVE MONTHS LATER** -**Confidence Level:** 99% -**Based on:** Industry best practices + Our successful desktop refactoring experience - -🚀 **Let's build it right from the start!** diff --git a/archive/2026-04-16/TASK_LOG_TEMPLATE.md b/archive/2026-04-16/TASK_LOG_TEMPLATE.md deleted file mode 100644 index c28dc85..0000000 --- a/archive/2026-04-16/TASK_LOG_TEMPLATE.md +++ /dev/null @@ -1,217 +0,0 @@ -# Task Log Template for ADD Section 6.2 - -**TEAM ACTION REQUIRED:** Please fill in this template with actual meeting information and replace the placeholder data in the ADD document. - ---- - -## Instructions - -1. For each meeting held with your advisor or team, create an entry below -2. Include all dates from September 2025 through January 2026 -3. Be specific about decisions made and action items assigned -4. Estimate hours spent in meetings and working sessions -5. Copy the completed log into ADD_FIVUCSAS.md Section 6.2 - ---- - -## Template Format - -### Meeting #X: [Meeting Title] -- **Date:** YYYY-MM-DD -- **Location:** [Office/Online/Lab/Building Name] -- **Duration:** [X minutes/hours] -- **Attendees:** [List names] -- **Objectives:** - - [Primary objective 1] - - [Primary objective 2] -- **Decisions and Notes:** - - [Decision 1] - - [Decision 2] - - [Action item 1 - assigned to ...] - - [Action item 2 - assigned to ...] - ---- - -## Sample Meetings to Document - -Below are likely meetings based on the project timeline. Replace with your actual meetings: - ---- - -### Meeting #1: Project Initiation and Scope Definition -- **Date:** 2025-09-15 -- **Location:** Faculty of Engineering, Office 302 -- **Duration:** 90 minutes -- **Attendees:** Ahmet Abdullah Gültekin, Ayşe Gülsüm Eren, Ayşenur Arıcı, Dr. Mustafa Ağaoğlu -- **Objectives:** - - Define project scope and goals - - Select technology stack - - Establish team roles and responsibilities - - Agree on meeting cadence -- **Decisions and Notes:** - - **DECISION:** Approved multi-tenant SaaS architecture for FIVUCSAS - - **DECISION:** Selected Kotlin Multiplatform for cross-platform mobile/desktop development - - **DECISION:** Chose FastAPI for biometric processor (Python ML ecosystem) + Spring Boot for identity core (enterprise Java patterns) - - **DECISION:** Bi-weekly advisor meetings on Tuesdays 14:00-15:00 - - **ACTION:** Ahmet to set up repository structure and Docker Compose environment (Week 1) - - **ACTION:** Ayşenur to research DeepFace library and liveness detection algorithms (Week 1-2) - - **ACTION:** Ayşe to prototype Kotlin Multiplatform setup with basic navigation (Week 1-2) - ---- - -### Meeting #2: Literature Review and Architecture Discussion -- **Date:** 2025-09-29 -- **Location:** Online (Zoom) -- **Duration:** 60 minutes -- **Attendees:** [Fill in] -- **Objectives:** - - Review literature survey findings - - Discuss proposed system architecture - - Finalize database schema approach -- **Decisions and Notes:** - - [Fill in your actual meeting content] - ---- - -### Meeting #3: Requirements Validation -- **Date:** 2025-10-13 -- **Location:** [Fill in] -- **Duration:** [Fill in] -- **Attendees:** [Fill in] -- **Objectives:** - - Present functional and non-functional requirements - - Validate requirement completeness - - Discuss testing strategy -- **Decisions and Notes:** - - [Fill in your actual meeting content] - ---- - -### Meeting #4: Design Review - Identity Core API -- **Date:** 2025-10-27 -- **Location:** [Fill in] -- **Duration:** [Fill in] -- **Attendees:** [Fill in] -- **Objectives:** - - Review hexagonal architecture implementation - - Discuss JWT authentication flow - - Validate database migration strategy -- **Decisions and Notes:** - - [Fill in your actual meeting content] - ---- - -### Meeting #5: Design Review - Biometric Processor -- **Date:** 2025-11-10 -- **Location:** [Fill in] -- **Duration:** [Fill in] -- **Attendees:** [Fill in] -- **Objectives:** - - Review face recognition pipeline - - Demonstrate liveness detection algorithm - - Discuss pgvector integration -- **Decisions and Notes:** - - [Fill in your actual meeting content] - ---- - -### Meeting #6: Mid-Semester Progress Review -- **Date:** 2025-11-24 -- **Location:** [Fill in] -- **Duration:** [Fill in] -- **Attendees:** [Fill in] -- **Objectives:** - - Review implementation progress - - Address technical challenges - - Plan remaining work for semester -- **Decisions and Notes:** - - [Fill in your actual meeting content] - ---- - -### Meeting #7: Mobile Application Demo -- **Date:** 2025-12-08 -- **Location:** [Fill in] -- **Duration:** [Fill in] -- **Attendees:** [Fill in] -- **Objectives:** - - Demonstrate Kotlin Multiplatform app - - Review UI/UX design - - Discuss backend integration approach -- **Decisions and Notes:** - - [Fill in your actual meeting content] - ---- - -### Meeting #8: ADD Document Review -- **Date:** 2025-12-22 -- **Location:** [Fill in] -- **Duration:** [Fill in] -- **Attendees:** [Fill in] -- **Objectives:** - - Review draft ADD document - - Address documentation gaps - - Prepare for presentation -- **Decisions and Notes:** - - [Fill in your actual meeting content] - ---- - -### Meeting #9: Presentation Preparation -- **Date:** 2026-01-05 -- **Location:** [Fill in] -- **Duration:** [Fill in] -- **Attendees:** [Fill in] -- **Objectives:** - - Finalize presentation slides - - Rehearse demonstration - - Address last-minute questions -- **Decisions and Notes:** - - [Fill in your actual meeting content] - ---- - -## Additional Working Sessions - -Document significant team working sessions (optional but recommended): - -### Working Session #1: [Description] -- **Date:** YYYY-MM-DD -- **Location:** [Location] -- **Duration:** [Hours] -- **Participants:** [Names] -- **Work Completed:** - - [Task 1] - - [Task 2] -- **Hours Logged:** [Individual hours - AAG: X hrs, AGE: X hrs, AA: X hrs] - ---- - -## Summary Statistics - -Once complete, calculate: -- Total advisor meetings: [X] -- Total meeting hours: [X] -- Total team working sessions: [X] -- Total development hours: [X] -- Total project hours: [X] - ---- - -## Notes - -- **Be honest:** Document actual meetings, not fictional ones -- **Be specific:** Include technical decisions made -- **Be concise:** 5-10 bullet points per meeting is sufficient -- **Include conflicts/challenges:** Shows real project dynamics -- **If you don't have historical data:** Create a retrospective log based on: - - Git commit history (shows work periods) - - Email exchanges with advisor - - Team chat logs - - Calendar appointments - ---- - -**Template Created:** January 20, 2026 -**Purpose:** Fulfill CSE4197 ADD Section 6.2 requirement -**To Use:** Fill in actual data and copy to ADD_FIVUCSAS.md diff --git a/archive/README.md b/archive/README.md deleted file mode 100644 index 72fbccc..0000000 --- a/archive/README.md +++ /dev/null @@ -1,22 +0,0 @@ -# Documentation Archive - -Historical docs preserved for git history. Content here is **not current** — see top-level `README.md` and the numbered module folders (`01-getting-started/` … `09-auth-flows/`) for authoritative docs. - -> **Cleanup note (2026-06):** A tracking-doc sweep hard-removed the disposable report/analysis/status/critique/fix-plan/progress/test-report files from this archive — their content is superseded by current code, the numbered reference sections, and GitHub issues. The genuine design specs, ADR-like decision records, diagram sources, research investigations, content artifacts, and templates listed below were **kept**. - -## 2026-04-16 (kept after the sweep) - -Durable artifacts that remain in `archive/2026-04-16/`: - -- **Architecture Design Document** — `ADD_FIVUCSAS.md` (full ADD), `ADD_LANDING_WEBSITE.md` (landing-site Analysis & Design Document). -- **Decision records** — `SYSTEM_DESIGN_ANALYSIS_AND_DECISION.md`, `IDENTITY_CORE_API_ANALYSIS.md` (keep-both-services verdict), `DOCS_MODULE_PROFESSIONAL_DESIGN.md`. -- **Diagram sources** — `PLANTUML_DIAGRAMS.md`, `PLANTUML_DIAGRAMS_PART2.md`. -- **Research** — `BIOMETRIC_FLOW_RESEARCH.md` (end-to-end flow trace). -- **Setup guides** — `PGVECTOR_SETUP.md`, `QUICK_START_PGVECTOR.md`. -- **Content artifacts / templates** — `PRESENTATION_COMPLETE_GUIDE.md`, `PRESENTATION_SPEECHES.md`, `TASK_LOG_TEMPLATE.md`, `ANALYTICS_PLAN.md` (live copy at `docs/plans/ANALYTICS_PLAN.md`). - -Removed in the sweep: the disposable `ADD_*` critiques/fix-plans/progress/gap-analyses, the `DOCS_MODULE_*` analysis/plan/summary/completion reports, the dated status reports (`FINAL_COMPLETION_REPORT`, `IMPLEMENTATION_STATUS_REPORT` ×2, `KMP_IMPLEMENTATION_STATUS`, `MOBILE_APP_STATUS`, `MOBILE_APP_INVESTIGATION_2026`, `PROJECT_PROGRESS_PRESENTATION`), the pgvector checklist/summary, the one-shot review/analysis drafts (`API_CONTRACT_*`, `AUTH_METHOD_AUDIT`, `AUTH_TEST_VS_WEBAPP_ANALYSIS`, `BACKEND_REVIEW`, `BACKEND_TEST_REPORT`, `CODE_ANALYSIS`, `IMPROVEMENT_RECOMMENDATIONS`, `MOBILE_APP_REFACTORING_PLAN`, `BACKEND_DAY_1_PLAN`, `BACKEND_NEXT_STEPS`), and the `SCREENSHOTS_NEEDED` checklist. - -## 2026-05-28 (removed in the sweep) - -The 7 dated per-service planning/status snapshots were removed — all contradicted current repo state and are superseded by `02-architecture/MODULE_STRUCTURE.md` and the live numbered reference sections: `SERVICES_OVERVIEW.md` (Nov-2025 snapshot), `test-report.md` (Jan-2025 synthetic static-analysis report), and the per-module implementation plans `biometric-processor.md`, `identity-core-api.md`, `client-apps.md`, `web-app.md`, `documentation.md`. diff --git a/plans/ANALYTICS_PLAN.md b/plans/ANALYTICS_PLAN.md deleted file mode 100644 index 0afa17e..0000000 --- a/plans/ANALYTICS_PLAN.md +++ /dev/null @@ -1,57 +0,0 @@ -# Analytics & Tracking Plan — FIVUCSAS - -## What to Set Up - -### 1. Google Analytics 4 (Free) -- **Where**: fivucsas.com (landing) + demo.fivucsas.com -- **NOT on**: app.fivucsas.com (dashboard — privacy, GDPR/KVKK) -- **Setup**: analytics.google.com → Create Account → Web Property -- **Metrics to track**: page views, demo clicks, "Get Started" clicks, time on page -- **Code location**: landing-website/index.html (placeholder already added, uncomment after setup and replace G-XXXXXXXXXX) - -### 2. Google Search Console (Free — Highest Priority) -- **Where**: fivucsas.com -- **Setup**: search.google.com/search-console → Add property → verify -- **DNS TXT already exists**: google-site-verification=RTnOyspxMve8PKsFb3cUAmPpEz-PMTUEwb8vKwh3L44 -- **Action**: Just add fivucsas.com in Search Console — it will auto-verify via the existing TXT record -- **Time to set up**: ~10 minutes - -### 3. Uptime Kuma (Already running) -- **URL**: https://status.fivucsas.com -- **Monitors**: All services already configured, no action needed - -### 4. NOT recommended (for now) -- Google Ads: Too early, no revenue model yet -- Hotjar/FullStory: Overkill for current stage -- Facebook Pixel: Not needed - -## Priority Order -1. **Google Search Console** — 10 min setup, immediate SEO benefit (indexing status, keywords, crawl errors) -2. **Google Analytics 4** — 15 min setup, understand landing page traffic (requires GA4 property first) -3. **Cookie consent banner** — Required before enabling GA4 for KVKK/GDPR compliance -4. **Google Ads** — Only after GA shows organic traffic bottleneck - -## Implementation Steps - -### Step 1: Google Search Console (do this now) -1. Go to https://search.google.com/search-console -2. Click "Add property" → choose "Domain" → enter `fivucsas.com` -3. It will ask for DNS TXT verification — the record already exists, so it should auto-verify -4. Submit sitemap: `https://fivucsas.com/sitemap.xml` (if one exists) - -### Step 2: Google Analytics 4 -1. Go to https://analytics.google.com -2. Create Account → Property → Web Stream → enter `https://fivucsas.com` -3. Copy the Measurement ID (format: G-XXXXXXXXXX) -4. In `landing-website/index.html`, uncomment the GA4 block and replace `G-XXXXXXXXXX` -5. Build and deploy: `npm run build` then SCP to Hostinger - -### Step 3: Cookie Consent (KVKK/GDPR) -Add a simple banner before enabling GA4. Options: -- Simple HTML/CSS banner (store consent in localStorage) -- `react-cookie-consent` npm package if converting to React -- Only activate GA4 if user accepts - -## GDPR/KVKK Note -GA4 collects IP addresses and sets cookies — this requires user consent under KVKK (Turkish law). -Add a cookie consent banner to fivucsas.com BEFORE enabling GA4 in production. diff --git a/plans/BAAS_RENTAL_MODEL.md b/plans/BAAS_RENTAL_MODEL.md deleted file mode 100644 index 142a07b..0000000 --- a/plans/BAAS_RENTAL_MODEL.md +++ /dev/null @@ -1,652 +0,0 @@ -# BaaS Per-Feature API Rental Model - -**Version:** 1.0 -**Date:** 2026-04-05 -**Status:** Design Document (Pre-Implementation) -**Author:** Ahmet Abdullah Gultekin -**Project:** FIVUCSAS - Face and Identity Verification Using Cloud-Based SaaS -**Organization:** Marmara University - Computer Engineering Department -**Feature ID:** W19 - ---- - -## Table of Contents - -1. [Executive Summary](#1-executive-summary) -2. [Business Model](#2-business-model) -3. [Competitor Analysis](#3-competitor-analysis) -4. [API Gateway Architecture](#4-api-gateway-architecture) -5. [Feature Isolation and Packaging](#5-feature-isolation-and-packaging) -6. [Usage Metering and Billing](#6-usage-metering-and-billing) -7. [SDK Distribution](#7-sdk-distribution) -8. [Developer Experience](#8-developer-experience) -9. [Implementation Phases](#9-implementation-phases) -10. [Risk Assessment](#10-risk-assessment) -11. [Dependencies and Prerequisites](#11-dependencies-and-prerequisites) - ---- - -## 1. Executive Summary - -FIVUCSAS, a university capstone biometric platform with 10 authentication methods, identity verification, and an embeddable auth widget, could be extended commercially by offering individual biometric capabilities as rentable APIs -- Biometrics as a Service (BaaS). Developers should be able to sign up, get an API key, and call `POST /v1/face/verify` without deploying any infrastructure. This document defines the pricing tiers (Free/Developer/Enterprise), API gateway architecture with per-key rate limiting, feature isolation model, usage metering pipeline, SDK distribution strategy (npm, Maven Central, CocoaPods), and developer portal experience. The target is to make FIVUCSAS as easy to integrate as Stripe is for payments. - ---- - -## 2. Business Model - -### Pricing Tiers - -``` -+------------------------------------------------------------------+ -| FIVUCSAS BaaS Pricing | -+------------------------------------------------------------------+ -| | -| FREE DEVELOPER ENTERPRISE | -| $0/month $29/month Custom | -| | -| 100 API calls 10,000 API calls Unlimited | -| Face only All features All features | -| 1 API key 5 API keys Unlimited keys | -| Community support Email support Dedicated support | -| No SLA 99.5% uptime SLA 99.9% uptime SLA | -| 48h data retention 90d data retention Custom retention | -| Watermarked No watermark White-label | -| 5 req/min 60 req/min Custom rate limit | -| BYOD option | -| On-premise deployment | -| SSO/SAML integration | -| | -+------------------------------------------------------------------+ -``` - -### Feature Pricing (a la carte, Developer tier and above) - -| Feature | Per-Call Cost | Included in Developer | Description | -|---------|-------------|----------------------|-------------| -| Face Detect | $0.001 | 10,000 | Bounding box + landmarks | -| Face Verify (1:1) | $0.003 | 3,333 | Compare two faces | -| Face Search (1:N) | $0.005 | 2,000 | Find in gallery | -| Face Enroll | $0.002 | 5,000 | Add to gallery | -| Voice Verify | $0.004 | 2,500 | Speaker verification | -| Voice STT Verify | $0.006 | 1,666 | Speaker + content | -| Card Detect | $0.003 | 3,333 | Document detection + crop | -| OCR Extract | $0.005 | 2,000 | TC Kimlik field extraction | -| Liveness Check | $0.004 | 2,500 | Anti-spoofing | -| NFC Verify | $0.005 | 2,000 | Chip authentication | -| Full Verification Flow | $0.05 | 200 | Multi-step identity verification | - -### Revenue Projections (Conservative) - -| Month | Free Users | Dev Users | Enterprise | MRR | -|-------|-----------|-----------|------------|-----| -| 1 | 50 | 5 | 0 | $145 | -| 3 | 200 | 20 | 1 | $1,580 | -| 6 | 500 | 50 | 3 | $4,450+ | -| 12 | 1,000 | 100 | 10 | $12,900+ | - ---- - -## 3. Competitor Analysis - -### Market Positioning - -``` - High Accuracy - | - | - AWS Rekognition o o Azure Face API - | - | - FIVUCSAS o----------+---------------------------o Auth0 - (multi-modal, | (auth only, - affordable) | no biometrics) - | - Onfido o | - | - Low Accuracy - - <-- Low Cost High Cost --> -``` - -### Detailed Comparison - -| Feature | FIVUCSAS BaaS | AWS Rekognition | Azure Face | Auth0 | Onfido | -|---------|-------------|-----------------|-----------|-------|--------| -| Face verify | Yes | Yes | Yes | No | Yes | -| Voice biometrics | Yes | No | Speaker Recognition | No | No | -| NFC document | Yes | No | No | No | Yes | -| Card OCR | Yes | No (use Textract) | No (use Form Recognizer) | No | Yes | -| Identity verification | Yes | No | No | No | Yes | -| Auth flows | Yes | No | No | Yes | No | -| Embeddable widget | Yes | No | No | Yes (Lock) | Yes | -| Multi-modal fusion | Yes | No | No | No | Partial | -| On-premise option | Yes (BYOD) | No | No | No | No | -| Free tier | 100 calls | 5,000/mo (12 months) | 30,000/mo | 7,000 users | None | -| Face verify cost | $0.003 | $0.001 | $0.001 | N/A | $0.10+ | -| Turkish ID support | Native | No | No | No | Yes | -| KVKK compliance | Native | No | No | No | Partial | - -### Unique Value Proposition - -1. **Multi-modal in one API**: Face + Voice + NFC + Card + Liveness -- competitors require multiple services -2. **Turkish-first**: Native TC Kimlik support, Turkish voice STT, KVKK compliance -3. **Full stack**: From biometric capture to identity verification to auth flows -- one vendor -4. **Affordable**: 3x cheaper than Onfido for full verification flows -5. **On-premise option**: BYOD for enterprise, impossible with pure SaaS competitors - ---- - -## 4. API Gateway Architecture - -### System Architecture - -``` -+------------------------------------------------------------------+ -| INTERNET | -+------------------------------------------------------------------+ - | - v -+----------+---------------------------------------------------+ -| API Gateway (Traefik + Custom Middleware) | -| | -| +------------------+ +------------------+ +--------------+ | -| | API Key | | Rate Limiter | | Usage | | -| | Validator | | (per-key, | | Meter | | -| | (Redis lookup) | | sliding window) | | (Redis -> PG)| | -| +--------+---------+ +--------+---------+ +------+-------+ | -| | | | | -| +--------v---------+ +-------v--------+ +--------v-------+ | -| | Feature Gate | | Quota Check | | Response | | -| | (allowed APIs | | (calls left | | Transformer | | -| | per plan) | | this period) | | (watermark) | | -| +------------------+ +----------------+ +----------------+ | -| | -+---+---------------------------+---------------------------+---+ - | | | - v v v -+---+-------+ +------+------+ +--------+----+ -| Identity | | Biometric | | Biometric | -| Core API | | Processor | | Processor | -| (auth, | | (face, | | (voice, | -| flows) | | liveness) | | card, NFC) | -+-----------+ +-------------+ +-------------+ -``` - -### API Key Schema - -```sql --- V30 migration: BaaS API keys -CREATE TABLE api_keys ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - tenant_id UUID NOT NULL REFERENCES tenants(id), - key_hash VARCHAR(64) NOT NULL UNIQUE, -- SHA-256 of API key - key_prefix VARCHAR(12) NOT NULL, -- "fvcs_live_" or "fvcs_test_" - name VARCHAR(255) NOT NULL, - plan VARCHAR(20) NOT NULL DEFAULT 'FREE', - status VARCHAR(20) NOT NULL DEFAULT 'ACTIVE', - - -- Permissions - allowed_features TEXT[] NOT NULL DEFAULT '{"face_detect"}', - rate_limit_rpm INTEGER NOT NULL DEFAULT 5, - - -- Quota - monthly_quota INTEGER NOT NULL DEFAULT 100, - current_usage INTEGER NOT NULL DEFAULT 0, - quota_reset_at TIMESTAMP NOT NULL, - - -- Metadata - last_used_at TIMESTAMP, - created_at TIMESTAMP NOT NULL DEFAULT now(), - expires_at TIMESTAMP -); - -CREATE TABLE api_usage_log ( - id BIGSERIAL PRIMARY KEY, - api_key_id UUID NOT NULL REFERENCES api_keys(id), - endpoint VARCHAR(255) NOT NULL, - feature VARCHAR(50) NOT NULL, - status_code INTEGER NOT NULL, - latency_ms INTEGER NOT NULL, - request_size INTEGER, - response_size INTEGER, - ip_address INET, - created_at TIMESTAMP NOT NULL DEFAULT now() -); - --- Partitioned by month for efficient cleanup -CREATE INDEX idx_usage_log_key_date ON api_usage_log (api_key_id, created_at); -``` - -### API Key Format - -``` -fvcs_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6 -fvcs_test_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6 -| | | -| | +-- 36 random hex chars (144-bit entropy) -| +-- environment (live = production, test = sandbox) -+-- prefix (always "fvcs") -``` - -### Rate Limiting Implementation - -``` -Algorithm: Sliding Window (Redis sorted set) - -Key: rate:{api_key_id}:{minute} -Value: Sorted set of request timestamps - -For each request: - 1. ZREMRANGEBYSCORE key 0 (now - 60s) // Remove old entries - 2. count = ZCARD key // Count in window - 3. If count >= rate_limit_rpm: return 429 - 4. ZADD key now now // Add this request - 5. EXPIRE key 120 // Cleanup safety net -``` - ---- - -## 5. Feature Isolation and Packaging - -### Feature Bundles - -``` -+------------------------------------------------------------------+ -| FEATURE BUNDLES | -+------------------------------------------------------------------+ -| | -| FACE BUNDLE VOICE BUNDLE IDENTITY BUNDLE | -| +-----------------+ +-----------------+ +-----------------+ | -| | face/detect | | voice/enroll | | verify/start | | -| | face/enroll | | voice/verify | | verify/status | | -| | face/verify | | voice/search | | verify/document | | -| | face/search | | voice/stt | | verify/nfc | | -| | face/liveness | | voice/challenge | | verify/face | | -| | face/quality | +-----------------+ | verify/liveness | | -| +-----------------+ +-----------------+ | -| | -| CARD BUNDLE AUTH BUNDLE FULL STACK | -| +-----------------+ +-----------------+ +-----------------+ | -| | card/detect | | auth/flow | | All features | | -| | card/ocr | | auth/session | | (face + voice | | -| | card/mrz | | auth/widget | | + card + auth | | -| +-----------------+ | auth/oauth | | + verify) | | -| +-----------------+ +-----------------+ | -+------------------------------------------------------------------+ -``` - -### API Namespace - -All BaaS endpoints under `/baas/v1/`: - -``` -POST /baas/v1/face/detect { image: base64 } -POST /baas/v1/face/verify { image1: base64, image2: base64 } -POST /baas/v1/face/enroll { image: base64, gallery_id: "...", person_id: "..." } -POST /baas/v1/face/search { image: base64, gallery_id: "...", top_k: 5 } -POST /baas/v1/face/liveness { image: base64 } -POST /baas/v1/face/quality { image: base64 } - -POST /baas/v1/voice/enroll { audio: base64, person_id: "..." } -POST /baas/v1/voice/verify { audio: base64, person_id: "..." } -POST /baas/v1/voice/challenge { language: "tr" } -POST /baas/v1/voice/verify-stt { audio: base64, passphrase_id: "...", person_id: "..." } - -POST /baas/v1/card/detect { image: base64 } -POST /baas/v1/card/ocr { image: base64, document_type: "tc_kimlik" } -POST /baas/v1/card/mrz { image: base64 } - -POST /baas/v1/verify/start { template: "banking_kyc", person_id: "..." } -GET /baas/v1/verify/{session_id} -POST /baas/v1/verify/{session_id}/step -``` - -### Gallery Management (Face/Voice) - -``` -POST /baas/v1/galleries -- Create gallery -GET /baas/v1/galleries -- List galleries -DELETE /baas/v1/galleries/{id} -- Delete gallery -GET /baas/v1/galleries/{id}/persons -- List persons -DELETE /baas/v1/galleries/{id}/persons/{pid} -- Remove person -``` - ---- - -## 6. Usage Metering and Billing - -### Metering Pipeline - -``` -API Request - | - v -+------------------+ +------------------+ +-------------------+ -| Redis Counter | --> | Flush to PG | --> | Monthly | -| (real-time, | | (every 5 min, | | Aggregation | -| per-key atomic | | batch insert) | | (cron job, | -| increment) | | | | invoice gen) | -+------------------+ +------------------+ +-------------------+ - | - v - +-------------------+ - | Billing Provider | - | (Stripe/Iyzico) | - +-------------------+ -``` - -### Usage Tracking - -```python -# Redis keys for real-time metering -usage:{api_key_id}:2026-04:total -> atomic counter (monthly total) -usage:{api_key_id}:2026-04:face_verify -> atomic counter (per-feature) -usage:{api_key_id}:2026-04:voice_verify -> atomic counter (per-feature) -quota:{api_key_id}:remaining -> monthly quota remaining (decrement) -``` - -### Invoice Schema - -```json -{ - "invoice_id": "inv_2026_04_abc123", - "tenant_id": "...", - "period": "2026-04", - "plan": "DEVELOPER", - "base_price": 29.00, - "usage": { - "face_verify": { "count": 8500, "included": 3333, "overage": 5167, "cost": 15.50 }, - "voice_verify": { "count": 1200, "included": 2500, "overage": 0, "cost": 0.00 }, - "card_ocr": { "count": 500, "included": 2000, "overage": 0, "cost": 0.00 } - }, - "overage_total": 15.50, - "total": 44.50, - "currency": "USD" -} -``` - ---- - -## 7. SDK Distribution - -### SDK Matrix - -| Platform | Package | Repository | Language | -|----------|---------|-----------|----------| -| JavaScript/TypeScript | `@fivucsas/sdk` | npm | TypeScript | -| Java/Kotlin (Android) | `com.fivucsas:sdk` | Maven Central | Kotlin | -| Swift (iOS) | `FivucsasSDK` | CocoaPods / SPM | Swift | -| Python | `fivucsas` | PyPI | Python | -| cURL/REST | N/A (docs only) | N/A | Any | - -### JavaScript SDK Example - -```typescript -import { FivucsasClient } from '@fivucsas/sdk'; - -const client = new FivucsasClient({ - apiKey: 'fvcs_live_...', - region: 'eu', // or 'tr' for Turkey -}); - -// Face verification -const result = await client.face.verify({ - image1: file1, // File, Blob, or base64 - image2: file2, -}); -console.log(result.match, result.confidence); // true, 0.92 - -// Voice verification with STT -const challenge = await client.voice.challenge({ language: 'tr' }); -console.log('Say:', challenge.text); // "yedi kirmizi balon uctu" - -const voiceResult = await client.voice.verifyStt({ - audio: audioBlob, - passphraseId: challenge.id, - personId: 'user_123', -}); - -// Identity verification flow -const session = await client.verify.start({ - template: 'banking_kyc', - personId: 'user_123', -}); -// Returns step-by-step instructions... -``` - -### Android SDK Example - -```kotlin -val client = FivucsasClient.Builder() - .apiKey("fvcs_live_...") - .region("eu") - .build() - -// Face verification -val result = client.face.verify( - image1 = bitmap1, - image2 = bitmap2 -) -Log.d("FIVUCSAS", "Match: ${result.match}, Score: ${result.confidence}") -``` - -### SDK Architecture (shared core) - -``` -+------------------------------------------------------------------+ -| @fivucsas/sdk-core (TypeScript, platform-agnostic) | -| | -| +------------------+ +------------------+ +------------------+ | -| | HTTP Client | | Auth (API key) | | Retry + Circuit | | -| | (fetch/axios) | | | | Breaker | | -| +------------------+ +------------------+ +------------------+ | -| +------------------+ +------------------+ +------------------+ | -| | Face Module | | Voice Module | | Card Module | | -| +------------------+ +------------------+ +------------------+ | -| +------------------+ +------------------+ | -| | Verify Module | | Auth Module | | -| +------------------+ +------------------+ | -+------------------------------------------------------------------+ - | | | - v v v - @fivucsas/sdk com.fivucsas:sdk FivucsasSDK - (npm) (Maven Central) (CocoaPods) -``` - ---- - -## 8. Developer Experience - -### Developer Portal Features - -``` -+------------------------------------------------------------------+ -| DEVELOPER PORTAL (already scaffolded at /developer-portal) | -+------------------------------------------------------------------+ -| | -| Dashboard | -| +------------------+ +------------------+ +------------------+ | -| | API Keys | | Usage Graph | | Quick Start | | -| | [Create] [Revoke]| | (daily/monthly) | | (copy-paste code)| | -| +------------------+ +------------------+ +------------------+ | -| | -| Documentation | -| +------------------+ +------------------+ +------------------+ | -| | API Reference | | SDK Guides | | Code Examples | | -| | (OpenAPI/Swagger)| | (JS/Android/iOS) | | (by use case) | | -| +------------------+ +------------------+ +------------------+ | -| | -| Testing | -| +------------------+ +------------------+ +------------------+ | -| | API Playground | | Test API Keys | | Webhook Tester | | -| | (try it live) | | (sandbox env) | | (event inspector)| | -| +------------------+ +------------------+ +------------------+ | -| | -| Account | -| +------------------+ +------------------+ +------------------+ | -| | Billing | | Team Members | | Webhooks Config | | -| | (invoices, plan) | | (RBAC) | | (event URLs) | | -| +------------------+ +------------------+ +------------------+ | -+------------------------------------------------------------------+ -``` - -### Onboarding Flow (Time to First API Call: <5 minutes) - -``` -1. Sign up (email + password or GitHub OAuth) - | -2. Get test API key (instant, no credit card) - | -3. Copy code snippet from Quick Start - | -4. Make first API call (sandbox, watermarked) - | -5. See result in dashboard - | -6. Upgrade to Developer ($29/mo) for production key -``` - -### API Playground - -Interactive API tester in the browser: - -``` -+----------------------------------------------+ -| POST /baas/v1/face/verify | -+----------------------------------------------+ -| | -| API Key: [fvcs_test_... ] [Auto-fill] | -| | -| Image 1: [Upload] or [Webcam] | -| Image 2: [Upload] or [Webcam] | -| | -| [ Try It ] | -| | -| Response (243ms): | -| { | -| "match": true, | -| "confidence": 0.924, | -| "model": "arcface-512d", | -| "processing_time_ms": 243 | -| } | -+----------------------------------------------+ -``` - ---- - -## 9. Implementation Phases - -### Phase 1 — API Gateway + Keys (3 weeks) - -| Task | Effort | Details | -|------|--------|---------| -| V30 migration (api_keys, api_usage_log) | 1 day | Schema as defined | -| API key generation + management service | 2 days | Create, revoke, rotate | -| API key validation middleware | 2 days | Redis-cached key lookup, feature gate | -| Rate limiter (sliding window) | 2 days | Redis sorted set implementation | -| /baas/v1/ endpoint namespace | 3 days | Proxy to existing biometric-processor + identity-core | -| Usage counter (Redis + flush to PG) | 2 days | Atomic increment, batch flush | -| Admin UI: API key management | 2 days | Extend DeveloperPortalPage | -| Tests | 1 day | Rate limiting, quota, key validation | - -### Phase 2 — Feature Isolation + Metering (2 weeks) - -| Task | Effort | Details | -|------|--------|---------| -| Feature bundles configuration | 2 days | Plan -> allowed features mapping | -| Per-feature usage tracking | 2 days | Breakdown by endpoint | -| Quota enforcement + 429 responses | 1 day | Reject when quota exhausted | -| Gallery management endpoints | 3 days | Per-tenant face/voice galleries | -| Usage dashboard (React) | 2 days | Charts, daily/monthly breakdown | - -### Phase 3 — SDKs (3 weeks) - -| Task | Effort | Details | -|------|--------|---------| -| @fivucsas/sdk-core (TypeScript) | 3 days | HTTP client, auth, retry, modules | -| @fivucsas/sdk (npm package) | 2 days | Browser + Node.js wrapper | -| com.fivucsas:sdk (Kotlin) | 3 days | OkHttp client, Kotlin coroutines | -| FivucsasSDK (Swift) | 3 days | URLSession, async/await | -| fivucsas (Python) | 2 days | requests/httpx, typed responses | -| SDK documentation + examples | 2 days | Per-platform quick start | - -### Phase 4 — Billing + Developer Portal (2 weeks) - -| Task | Effort | Details | -|------|--------|---------| -| Stripe/Iyzico integration | 3 days | Subscription + overage billing | -| Invoice generation | 2 days | Monthly aggregation + PDF | -| Developer portal enhancement | 3 days | API playground, usage graphs, team management | -| API reference (OpenAPI 3.0) | 2 days | Auto-generated from endpoint definitions | - -### Phase 5 — Launch Preparation (1 week) - -| Task | Effort | Details | -|------|--------|---------| -| Sandbox environment | 2 days | Test keys with mock data | -| Onboarding email sequence | 1 day | Welcome, quick start, upgrade prompt | -| Landing page update | 1 day | Pricing page, "Get Started" CTA | -| Load testing | 1 day | 1000 concurrent API keys, rate limiting under load | - -### Total Effort: ~11 weeks - -``` -Week 1-3: Phase 1 (API Gateway, keys, rate limiting) -Week 4-5: Phase 2 (Feature isolation, metering, dashboard) -Week 6-8: Phase 3 (SDKs: JS, Kotlin, Swift, Python) -Week 9-10: Phase 4 (Billing integration, developer portal) -Week 11: Phase 5 (Launch preparation) -``` - ---- - -## 10. Risk Assessment - -| Risk | Probability | Impact | Mitigation | -|------|------------|--------|------------| -| Low initial adoption (chicken-and-egg) | High | Medium | Generous free tier; target university/hackathon communities first | -| API abuse (scraping, DDoS via free tier) | High | High | Rate limiting, CAPTCHA on signup, IP reputation, anomaly detection | -| Cost of compute exceeds revenue (free tier) | Medium | High | Free tier limited to face-only (lightest compute); monitor cost/call | -| SDK maintenance burden (4 platforms) | Medium | Medium | TypeScript core with thin platform wrappers; auto-generate from OpenAPI | -| Billing integration complexity | Medium | Medium | Start with Stripe (global) + Iyzico (Turkey); defer custom invoicing | -| Competitor price war | Low | Medium | Compete on features (multi-modal), not price; Turkish market lock-in | -| Security: API key leaked in client code | High | High | Docs emphasize server-side only; test keys clearly marked; key rotation API | -| Scaling beyond single Hetzner server | Medium | High | Horizontal scaling plan (Phase 5+); BYOD offloads enterprise tenants | - ---- - -## 11. Dependencies and Prerequisites - -### Technical Prerequisites - -| Prerequisite | Status | Notes | -|-------------|--------|-------| -| OAuth2 endpoints | Implemented | V24 migration, OAuth2Controller | -| DeveloperPortalPage | Scaffolded | Needs enhancement for BaaS | -| Traefik API gateway | Running | Add middleware for API key validation | -| Redis | Running | Rate limiting + usage counters | -| Biometric endpoints | All operational | 46+ endpoints in biometric-processor | -| Auth widget | Deployed | Embeddable widget for auth flows | - -### Business Prerequisites - -| Prerequisite | Status | Notes | -|-------------|--------|-------| -| Legal: Terms of Service for API | Not created | Required before public launch | -| Legal: Data Processing Agreement | Not created | Required for KVKK/GDPR | -| Payment processor account | Not created | Stripe (international) + Iyzico (Turkey) | -| Support system | Not created | Zendesk/Freshdesk or email-based initially | -| Marketing website | Exists (landing page) | Needs pricing page + developer docs section | - -### Infrastructure Scaling Plan - -| Users | Current (CX43) | Needed | Action | -|-------|----------------|--------|--------| -| 0-100 | 8 CPU, 16 GB | Sufficient | No change | -| 100-500 | Stretched | CX43 + dedicated biometric worker | Add second VPS | -| 500-2000 | Insufficient | Kubernetes cluster | Migrate to k3s or managed k8s | -| 2000+ | N/A | Multi-region | Hetzner EU + US East | - ---- - -*The BaaS model transforms FIVUCSAS from a deployed product into a platform. Start with the API gateway and free tier to validate demand before investing in billing and SDKs. The existing DeveloperPortalPage and auth widget provide a head start on developer experience.* diff --git a/plans/BYOD_ARCHITECTURE.md b/plans/BYOD_ARCHITECTURE.md deleted file mode 100644 index 2660a72..0000000 --- a/plans/BYOD_ARCHITECTURE.md +++ /dev/null @@ -1,513 +0,0 @@ -# Bring Your Own Database (BYOD) Architecture - -**Version:** 1.0 -**Date:** 2026-04-05 -**Status:** Design Document (Pre-Implementation) -**Author:** Ahmet Abdullah Gultekin -**Project:** FIVUCSAS - Face and Identity Verification Using Cloud-Based SaaS -**Organization:** Marmara University - Computer Engineering Department -**Feature ID:** W18 - ---- - -## Table of Contents - -1. [Executive Summary](#1-executive-summary) -2. [Business Context](#2-business-context) -3. [Architecture Overview](#3-architecture-overview) -4. [Tenant Configuration Model](#4-tenant-configuration-model) -5. [Dynamic DataSource Routing](#5-dynamic-datasource-routing) -6. [Connection Pool Management](#6-connection-pool-management) -7. [Security Architecture](#7-security-architecture) -8. [Migration Strategy](#8-migration-strategy) -9. [Implementation Phases](#9-implementation-phases) -10. [Risk Assessment](#10-risk-assessment) -11. [Dependencies and Prerequisites](#11-dependencies-and-prerequisites) - ---- - -## 1. Executive Summary - -FIVUCSAS currently stores all tenant biometric data in a shared PostgreSQL instance with row-level security (RLS) for isolation. While sufficient for SaaS customers, enterprise and government tenants — especially under KVKK (Turkey's data protection law) and GDPR — require that biometric data never leave their infrastructure. BYOD (Bring Your Own Database) allows tenants to provide their own PostgreSQL instance with pgvector for biometric storage, while FIVUCSAS manages the application logic, authentication flows, and admin interface. This is analogous to Zimbra (self-hosted email), Bitbucket Server (self-hosted git), or Jira Data Center — the software runs centrally but data resides where the tenant chooses. - ---- - -## 2. Business Context - -### Why BYOD - -| Stakeholder | Need | BYOD Solution | -|-------------|------|---------------| -| Government agencies | KVKK Article 9: biometric data cannot leave Turkey | Tenant DB in government data center | -| Banks | BDDK regulation: customer data on-premise | Tenant DB in bank's private cloud | -| Hospitals | HIPAA / Saglik Bakanligi: patient data sovereignty | Tenant DB in hospital network | -| Universities | Budget constraints, existing infrastructure | Use existing PostgreSQL cluster | -| Startups (SaaS) | No special requirements | Shared DB (default, unchanged) | - -### Competitive Landscape - -| Product | Model | BYOD Support | -|---------|-------|-------------| -| Auth0 | SaaS only | No (Enterprise: dedicated tenant, not BYOD) | -| Keycloak | Self-hosted | Full self-host only, no hybrid | -| AWS Rekognition | SaaS only | No | -| **FIVUCSAS** | **Hybrid** | **SaaS default + BYOD option** | - -### Revenue Impact - -- BYOD is an enterprise upsell: estimated 3-5x price multiplier over standard SaaS -- Enables government and banking contracts that are currently impossible -- Reduces data liability for FIVUCSAS (tenant owns their data) - ---- - -## 3. Architecture Overview - -### High-Level Architecture - -``` -+------------------------------------------------------------------+ -| FIVUCSAS CENTRAL (Hetzner) | -| | -| +------------------+ +------------------+ +-------------------+| -| | Identity Core | | Web Dashboard | | Auth Widget || -| | API (Spring Boot)| | (React) | | (verify-app) || -| +--------+---------+ +------------------+ +-------------------+| -| | | -| +--------v---------+ | -| | DataSource Router| | -| | (TenantAware) | | -| +--------+---------+ | -| | | -| +-----+------+ | -| | | | -+-----|------------|------------------------------------------------+ - | | - v v -+----------+ +-----------+ +-----------+ +-----------+ -| Shared | | Tenant A | | Tenant B | | Tenant C | -| DB | | DB | | DB | | DB | -| (Default)| | (Bank | | (Gov't | | (Hospital | -| Hetzner | | Private) | | DC) | | AWS) | -+----------+ +-----------+ +-----------+ +-----------+ - pgvector pgvector pgvector pgvector -``` - -### Data Partitioning - -``` -+----------------------------------+----------------------------------+ -| CENTRAL DB (always) | TENANT DB (BYOD only) | -+----------------------------------+----------------------------------+ -| tenants | face_embeddings | -| users (metadata only) | voice_enrollments | -| roles, permissions | nfc_card_enrollments | -| auth_flows, auth_flow_steps | biometric_enrollments | -| auth_sessions (metadata) | verification_documents | -| audit_logs (non-biometric) | verification_sessions | -| oauth2_clients | verification_step_results | -| tenant_config | audit_logs (biometric events) | -| byod_connections | webauthn_credentials | -+----------------------------------+----------------------------------+ - -Rule: Raw biometric data (embeddings, images, documents) goes to - tenant DB. Configuration and non-biometric metadata stays central. -``` - -### Key Design Decisions - -| Decision | Rationale | -|----------|-----------| -| Central DB always holds config | Tenant DB unavailability must not break admin UI | -| Biometric data only in tenant DB | Minimizes what must be routed; config queries stay fast | -| pgvector required on tenant DB | HNSW indexes for face/voice search are non-negotiable | -| Connection per-tenant, not per-request | HikariCP pool per tenant avoids connection storm | -| Tenant provides connection string | FIVUCSAS does not manage tenant infrastructure | - ---- - -## 4. Tenant Configuration Model - -### Database Schema Extension - -```sql --- V29 migration: BYOD support -CREATE TABLE byod_connections ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - tenant_id UUID NOT NULL REFERENCES tenants(id) UNIQUE, - display_name VARCHAR(255) NOT NULL, - - -- Connection details (encrypted at rest) - host VARCHAR(255) NOT NULL, - port INTEGER NOT NULL DEFAULT 5432, - database_name VARCHAR(255) NOT NULL, - username VARCHAR(255) NOT NULL, - password_enc TEXT NOT NULL, -- AES-256-GCM encrypted - - -- Connection pool settings - max_pool_size INTEGER NOT NULL DEFAULT 10, - min_idle INTEGER NOT NULL DEFAULT 2, - conn_timeout_ms INTEGER NOT NULL DEFAULT 30000, - - -- SSL/TLS - ssl_mode VARCHAR(20) NOT NULL DEFAULT 'require', - ssl_ca_cert TEXT, -- PEM-encoded CA certificate - ssl_client_cert TEXT, -- mutual TLS (optional) - ssl_client_key TEXT, -- mutual TLS (optional) - - -- Health - status VARCHAR(20) NOT NULL DEFAULT 'PENDING', - last_health_at TIMESTAMP, - last_error TEXT, - - -- Metadata - created_at TIMESTAMP NOT NULL DEFAULT now(), - updated_at TIMESTAMP NOT NULL DEFAULT now() -); - --- Status enum: PENDING, VALIDATING, ACTIVE, DEGRADED, DISCONNECTED, MIGRATING -``` - -### Tenant Configuration API - -``` -POST /api/v1/tenants/{id}/byod -- Configure BYOD connection -GET /api/v1/tenants/{id}/byod -- Get BYOD config (password masked) -PUT /api/v1/tenants/{id}/byod -- Update connection details -DELETE /api/v1/tenants/{id}/byod -- Revert to shared DB -POST /api/v1/tenants/{id}/byod/test -- Test connection + validate schema -POST /api/v1/tenants/{id}/byod/migrate -- Migrate existing data to BYOD DB -GET /api/v1/tenants/{id}/byod/health -- Connection pool + query latency -``` - ---- - -## 5. Dynamic DataSource Routing - -### Spring Boot Integration - -``` -+------------------+ +--------------------+ +------------------+ -| HTTP Request | --> | TenantContext | --> | DataSource | -| (JWT has | | Filter | | Router | -| tenant_id) | | (sets ThreadLocal) | | (AbstractRouting| -+------------------+ +--------------------+ | DataSource) | - +--------+--------+ - | - +---------+---------+ - | | - +----v----+ +----v----+ - | Shared | | Tenant | - | Hikari | | Hikari | - | Pool | | Pool | - +---------+ +---------+ -``` - -### Implementation - -```java -// Hexagonal: Port -public interface BiometricDataSourcePort { - DataSource resolveForTenant(UUID tenantId); - void registerTenantDataSource(UUID tenantId, ByodConnection config); - void removeTenantDataSource(UUID tenantId); - HealthStatus checkHealth(UUID tenantId); -} - -// Hexagonal: Adapter -@Component -public class DynamicDataSourceRouter extends AbstractRoutingDataSource - implements BiometricDataSourcePort { - - private final ConcurrentMap tenantPools = - new ConcurrentHashMap<>(); - private final HikariDataSource sharedPool; - - @Override - protected Object determineCurrentLookupKey() { - return TenantContext.getCurrentTenantId(); - } - - @Override - protected DataSource determineTargetDataSource() { - UUID tenantId = TenantContext.getCurrentTenantId(); - if (tenantId == null) return sharedPool; - - HikariDataSource tenantDs = tenantPools.get(tenantId); - return (tenantDs != null) ? tenantDs : sharedPool; - } -} -``` - -### Biometric Repository Split - -```java -// Before BYOD: single repository -@Repository -public class FaceEmbeddingRepository { - private final JdbcTemplate jdbc; // always shared DB -} - -// After BYOD: tenant-aware repository -@Repository -public class FaceEmbeddingRepository { - private final BiometricDataSourcePort dataSourcePort; - - public List findByUserId(UUID tenantId, UUID userId) { - DataSource ds = dataSourcePort.resolveForTenant(tenantId); - JdbcTemplate jdbc = new JdbcTemplate(ds); - return jdbc.query("SELECT * FROM face_embeddings WHERE user_id = ?", - faceEmbeddingMapper, userId); - } -} -``` - ---- - -## 6. Connection Pool Management - -### HikariCP Per-Tenant Strategy - -``` -Central Pool (shared DB): - - maxPoolSize: 20 (serves config queries for ALL tenants) - - minIdle: 5 - - connectionTimeout: 10s - -Per-Tenant Pool (BYOD DB): - - maxPoolSize: tenant.max_pool_size (default 10) - - minIdle: tenant.min_idle (default 2) - - connectionTimeout: tenant.conn_timeout_ms (default 30s) - - maxLifetime: 1800000 (30 min) - - idleTimeout: 600000 (10 min) -``` - -### Pool Lifecycle - -``` -Tenant activates BYOD - | - v - [Validate connection] - | - v - [Run schema check: pgvector + required tables] - | - v - [Create HikariDataSource with tenant config] - | - v - [Warm up: min_idle connections] - | - v - [Set status = ACTIVE] - | - v - [Health check every 60s] ----> [DEGRADED if >50% timeout] - | | - v v - [Evict pool after 24h idle] [Alert admin, retry with backoff] -``` - -### Resource Limits - -| Scenario | Max Tenants | Max Connections | RAM Estimate | -|----------|-------------|-----------------|-------------| -| Small (MVP) | 10 BYOD tenants | 100 (10 x 10) | ~200 MB | -| Medium | 50 BYOD tenants | 500 (50 x 10) | ~1 GB | -| Large | 200 BYOD tenants | 1000 (200 x 5) | ~2 GB | - -Current server: CX43 with 16 GB RAM. Biometric-api uses 4 GB. Identity-core-api has ~8 GB headroom, sufficient for medium scale. - ---- - -## 7. Security Architecture - -### Credential Management - -``` -+------------------+ +------------------+ +------------------+ -| Admin enters | --> | AES-256-GCM | --> | Encrypted in | -| DB credentials | | Encryption | | byod_connections| -| via HTTPS UI | | (per-tenant key)| | table | -+------------------+ +------------------+ +------------------+ - -Decryption key hierarchy: - Master Key (env var JWT_SECRET or dedicated BYOD_MASTER_KEY) - └── Per-tenant key = HKDF(master_key, tenant_id, "byod-v1") - └── Encrypts: password, ssl_client_key -``` - -### Tenant Isolation Guarantees - -| Threat | Mitigation | -|--------|------------| -| Tenant A queries Tenant B's DB | DataSource routing is per-tenant; no cross-tenant connection possible | -| SQL injection via tenant-provided host | Validate host format (FQDN/IP only), no semicolons, parameterized config | -| Tenant DB compromised | Only biometric data exposed; auth config stays in central DB | -| Man-in-the-middle | SSL mode = "require" minimum; mTLS available | -| Credential leak in logs | Passwords never logged; masked in API responses | -| Central DB compromise | Tenant biometric data not in central DB (BYOD benefit) | - -### Schema Validation - -Before activating a BYOD connection, the system validates: - -1. PostgreSQL version >= 15 -2. pgvector extension installed (`CREATE EXTENSION IF NOT EXISTS vector`) -3. Required tables exist (auto-create if missing via Flyway target migration) -4. HNSW indexes present on embedding columns -5. Connection latency < 500ms (P95) -6. SSL certificate valid and trusted - ---- - -## 8. Migration Strategy - -### Migrating Existing Tenant from Shared DB to BYOD - -``` -Phase 1: Setup (admin action) - | - +--> Admin configures BYOD connection - +--> System validates connection + schema - +--> System creates tables in tenant DB (Flyway subset) - +--> Status: PENDING -> VALIDATING -> VALIDATED - -Phase 2: Data Copy (background job) - | - +--> Copy face_embeddings WHERE tenant_id = X - +--> Copy voice_enrollments WHERE tenant_id = X - +--> Copy nfc_card_enrollments WHERE tenant_id = X - +--> Copy verification_documents WHERE tenant_id = X - +--> Copy webauthn_credentials WHERE tenant_id = X - +--> Verify row counts match - +--> Status: VALIDATED -> MIGRATING - -Phase 3: Cutover (zero-downtime) - | - +--> Enable dual-write: writes go to BOTH shared + tenant DB - +--> Verify dual-write consistency (5 min observation) - +--> Switch reads to tenant DB - +--> Disable writes to shared DB for this tenant - +--> Status: MIGRATING -> ACTIVE - -Phase 4: Cleanup (deferred, admin-triggered) - | - +--> Delete tenant's biometric data from shared DB - +--> Shrink shared DB (VACUUM FULL on affected tables) - +--> Status: ACTIVE (cleanup complete) -``` - -### Rollback Plan - -At any point before Phase 4 cleanup, the admin can revert: - -1. Switch reads back to shared DB -2. Replay any writes that went to tenant DB during dual-write -3. Remove tenant pool -4. Set status = DISCONNECTED - ---- - -## 9. Implementation Phases - -### Phase 1 — Foundation (3 weeks) - -| Task | Effort | Details | -|------|--------|---------| -| V29 Flyway migration (byod_connections table) | 1 day | Schema as defined above | -| ByodConnection entity + repository | 1 day | JPA entity with encrypted fields | -| BiometricDataSourcePort interface | 1 day | Hexagonal port definition | -| DynamicDataSourceRouter | 3 days | AbstractRoutingDataSource + HikariCP pool management | -| TenantContext ThreadLocal filter | 1 day | Extract tenant_id from JWT, set ThreadLocal | -| BYOD admin API (6 endpoints) | 2 days | CRUD + test + health | -| Credential encryption service | 2 days | AES-256-GCM with per-tenant key derivation | -| Schema validation service | 2 days | pgvector check, table creation, index verification | -| Unit tests | 2 days | Pool lifecycle, routing, encryption | - -### Phase 2 — Repository Refactor (2 weeks) - -| Task | Effort | Details | -|------|--------|---------| -| Split biometric repositories | 3 days | Face, voice, NFC, verification, WebAuthn repositories become tenant-aware | -| Biometric-processor BYOD proxy | 3 days | Python service queries correct DB based on tenant header | -| Integration tests | 2 days | TestContainers with 2 PostgreSQL instances | -| Admin UI: BYOD configuration page | 2 days | Connection form, health dashboard, migration trigger | - -### Phase 3 — Migration Engine (2 weeks) - -| Task | Effort | Details | -|------|--------|---------| -| Background migration job | 3 days | Spring Batch or custom with progress tracking | -| Dual-write interceptor | 2 days | Write to both DBs during cutover | -| Consistency verifier | 2 days | Row count + checksum comparison | -| Rollback mechanism | 1 day | Revert to shared DB | -| Migration admin UI | 2 days | Progress bar, logs, rollback button | - -### Phase 4 — Hardening (1 week) - -| Task | Effort | Details | -|------|--------|---------| -| Connection health monitor | 1 day | 60s health check, alert on DEGRADED | -| Pool eviction policy | 1 day | Remove idle pools after 24h | -| Load testing | 2 days | 50 concurrent BYOD tenants | -| Documentation | 1 day | Tenant setup guide, requirements checklist | - -### Total Effort: ~8 weeks - -``` -Week 1-3: Phase 1 (Foundation — routing, pools, encryption) -Week 4-5: Phase 2 (Repository refactor, biometric-processor proxy) -Week 6-7: Phase 3 (Migration engine, dual-write, cutover) -Week 8: Phase 4 (Hardening, monitoring, documentation) -``` - ---- - -## 10. Risk Assessment - -| Risk | Probability | Impact | Mitigation | -|------|------------|--------|------------| -| Tenant DB latency spikes (remote DC) | High | Medium | Connection timeout limits + circuit breaker pattern | -| Tenant DB goes offline | Medium | High | Graceful degradation: queue writes, serve cached reads | -| Pool exhaustion under load | Medium | High | Per-tenant pool limits + global connection ceiling | -| Schema drift (tenant modifies tables) | Low | High | Schema version check on health probe; alert + block if incompatible | -| Credential rotation coordination | Medium | Medium | API for credential update; connection pool refresh without restart | -| Migration data loss | Low | Critical | Checksum verification + dual-write before cutover + rollback | -| Cross-tenant data leak via routing bug | Low | Critical | Integration tests with 2 DBs; audit logs on every biometric query | -| Increased operational complexity | High | Medium | Comprehensive monitoring dashboard; tenant self-service where possible | - ---- - -## 11. Dependencies and Prerequisites - -### Technical Prerequisites - -| Prerequisite | Status | Notes | -|-------------|--------|-------| -| Row-level security (RLS) | Implemented | Currently provides isolation in shared DB | -| pgvector extension | Deployed | Required on every tenant DB | -| AES-256 encryption utility | Exists | Used for JWT; extend for BYOD credentials | -| Flyway migrations | V1-V28 | BYOD requires subset migration runner for tenant DBs | -| Spring AbstractRoutingDataSource | Available | Spring Boot built-in | -| HikariCP | In use | Already the connection pool; extend for multi-pool | - -### Infrastructure Prerequisites - -| Prerequisite | Status | Notes | -|-------------|--------|-------| -| Tenant DB must be reachable from Hetzner | Tenant responsibility | Public IP or VPN tunnel | -| PostgreSQL >= 15 on tenant DB | Tenant responsibility | Required for pgvector 0.5+ | -| SSL certificate on tenant DB | Tenant responsibility | Self-signed OK if CA cert provided | -| Network bandwidth: Hetzner <-> tenant DB | Variable | Should be <50ms latency for acceptable UX | - -### Organizational Prerequisites - -- Legal: BYOD contract template (data processing agreement) -- Support: Tenant onboarding runbook for BYOD setup -- Pricing: Enterprise tier pricing model that includes BYOD - ---- - -*This document defines the target architecture. Implementation should begin only after at least one enterprise customer confirms BYOD as a requirement. The shared-DB model with RLS is sufficient for all current tenants.* diff --git a/plans/MULTI_METHOD_2FA_DESIGN.md b/plans/MULTI_METHOD_2FA_DESIGN.md deleted file mode 100644 index f9bc619..0000000 --- a/plans/MULTI_METHOD_2FA_DESIGN.md +++ /dev/null @@ -1,689 +0,0 @@ -# Adaptive Multi-Factor Authentication Engine - -**Author:** FIVUCSAS Engineering -**Date:** 2026-04-05 -**Version:** 2.0 -**Status:** Final Design -**Scope:** Backend (identity-core-api), Frontend (web-app), Widget SDK, Admin UI - ---- - -## 1. Problem Statement - -### 1.1 Current Limitations - -The authentication system has three fundamental rigidity issues: - -**A) Password is hardcoded as step 1.** The backend assumes `stepOrder == 1` is always PASSWORD. Tenants cannot configure passwordless flows (e.g., Face-only access for a smart building) or biometric-first flows. - -**B) Only one 2FA method per flow.** The system extracts a single `twoFactorMethod` from `stepOrder == 2`. Users get no choice. Tenant admins must create separate flows for each method. - -**C) Maximum 2 steps.** The architecture assumes `Password → One 2FA`. There's no support for 3FA (e.g., Password → TOTP → Face for high-security operations like financial transactions). - -### 1.2 Target State - -A fully flexible **Multi-Factor Authentication Engine** where: - -- Tenant admins configure **1 to N stages** (not limited to 2) -- Each stage is either **SEQUENTIAL** (one fixed method) or **CHOICE** (user picks from multiple methods) -- **No method is hardcoded** — PASSWORD is just another auth method, not special -- A 3FA flow is possible: `Face → Fingerprint → Voice` (no password at all) -- Users see only methods they've **enrolled in** and can set a **preferred method** per stage - -### 1.3 Real-World Flow Examples - -| Scenario | Flow Configuration | MFA Level | -|----------|-------------------|-----------| -| Simple login | `PASSWORD` | 1FA | -| Standard 2FA | `PASSWORD → CHOICE[EMAIL_OTP, TOTP]` | 2FA | -| Biometric-first | `FACE → PASSWORD` | 2FA | -| Passwordless | `CHOICE[FACE, FINGERPRINT, HARDWARE_KEY]` | 1FA | -| High security | `PASSWORD → CHOICE[TOTP, EMAIL_OTP] → FACE` | 3FA | -| Exam proctoring | `FACE → VOICE → NFC_DOCUMENT` | 3FA | -| Smart building | `FINGERPRINT` | 1FA | -| Financial txn | `PASSWORD → TOTP → CHOICE[FACE, VOICE]` | 3FA | - ---- - -## 2. Architecture - -### 2.1 Core Concept: Steps and Choices - -``` -AuthFlow - └─ Step 1 (order=1, type=SEQUENTIAL|CHOICE) - │ ├─ [SEQUENTIAL] → exactly one AuthMethod - │ └─ [CHOICE] → multiple AuthMethods, user picks one - │ - └─ Step 2 (order=2, type=SEQUENTIAL|CHOICE) - │ └─ ... - │ - └─ Step N (order=N, max 5) - └─ ... -``` - -**Rules:** -1. A flow has 1–5 steps (configurable max, default 3) -2. Each step has a `step_type`: `SEQUENTIAL` or `CHOICE` -3. `SEQUENTIAL` step → one required method -4. `CHOICE` step → multiple methods, user picks one they've enrolled in -5. Each step has an optional `fallback_method_id` for when the user has no enrollment -6. Steps execute in order; all must pass for authentication to succeed - -### 2.2 No Hardcoded PASSWORD - -PASSWORD becomes a regular auth method in the `auth_methods` table. It has: -- `requires_enrollment: false` (everyone has a password by default) -- `category: BASIC` -- `platforms: [WEB, ANDROID, IOS, DESKTOP]` - -A tenant that wants passwordless login simply doesn't include PASSWORD in any step. - -### 2.3 Login Flow (New) - -``` -CLIENT: POST /auth/login - body: { email: "user@example.com" } ← Note: NO password in initial request - -SERVER: - 1. Look up user by email - 2. Find default APP_LOGIN flow for tenant - 3. Build step chain: - - For each step (ordered by step_order): - if SEQUENTIAL: - method = step.authMethod - check user enrollment → add to required steps - if CHOICE: - methods = step.alternativeMethods - filter by user enrollments → add available methods per step - - 4. Return step chain to client: - { - "sessionToken": "temp-session-abc", - "steps": [ - { - "stepNumber": 1, - "stepType": "SEQUENTIAL", - "method": { "type": "PASSWORD", "name": "Password" }, - "status": "PENDING" - }, - { - "stepNumber": 2, - "stepType": "CHOICE", - "availableMethods": [ - { "type": "TOTP", "name": "Authenticator App", "enrolled": true, "preferred": true }, - { "type": "EMAIL_OTP", "name": "Email OTP", "enrolled": true }, - { "type": "FACE", "name": "Face Recognition", "enrolled": false } - ], - "status": "PENDING" - }, - { - "stepNumber": 3, - "stepType": "SEQUENTIAL", - "method": { "type": "FACE", "name": "Face Verification" }, - "status": "PENDING" - } - ], - "totalSteps": 3, - "currentStep": 1 - } - -CLIENT: Steps through each one: - Step 1 → POST /auth/step/verify { sessionToken, step: 1, method: "PASSWORD", data: { password: "..." } } - Step 2 → POST /auth/step/verify { sessionToken, step: 2, method: "TOTP", data: { code: "123456" } } - Step 3 → POST /auth/step/verify { sessionToken, step: 3, method: "FACE", data: { image: "base64..." } } - -SERVER: After all steps pass → issue JWT tokens - { accessToken, refreshToken, expiresIn, user } -``` - -### 2.4 Session-Based Step Verification - -Instead of verifying everything in one request, use a **session-based step chain**: - -``` -AuthSession (Redis, TTL 10 minutes) - ├── sessionToken: "temp-abc-123" - ├── userId: UUID - ├── flowId: UUID - ├── steps: [ - │ { order: 1, method: "PASSWORD", status: "COMPLETED", verifiedAt: "..." }, - │ { order: 2, method: null, status: "PENDING" }, ← CHOICE, not yet selected - │ { order: 3, method: "FACE", status: "PENDING" } - │ ] - ├── currentStep: 2 - ├── createdAt: timestamp - └── expiresAt: timestamp (createdAt + 10min) -``` - -**Security:** The session token is short-lived (10 min), bound to the user+flow, and stored in Redis. Each step verification updates the session. Tokens are only issued when ALL steps are COMPLETED. - ---- - -## 3. Database Changes - -### 3.1 Migration V30: Adaptive MFA - -```sql --- 1. Add step_type to auth_flow_steps -ALTER TABLE auth_flow_steps - ADD COLUMN step_type VARCHAR(20) NOT NULL DEFAULT 'SEQUENTIAL'; - -ALTER TABLE auth_flow_steps - ADD CONSTRAINT chk_step_type CHECK (step_type IN ('SEQUENTIAL', 'CHOICE')); - --- 2. Join table for CHOICE step methods -CREATE TABLE auth_flow_step_methods ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - step_id UUID NOT NULL REFERENCES auth_flow_steps(id) ON DELETE CASCADE, - auth_method_id UUID NOT NULL REFERENCES auth_methods(id) ON DELETE CASCADE, - display_order INTEGER NOT NULL DEFAULT 0, - UNIQUE(step_id, auth_method_id) -); - -CREATE INDEX idx_step_methods_step ON auth_flow_step_methods(step_id); - --- 3. User preferred method per step position -ALTER TABLE users ADD COLUMN preferred_2fa_method VARCHAR(30); - --- 4. Increase max steps (relax any 2-step assumptions) --- The unique constraint (auth_flow_id, step_order) already supports N steps. --- Just ensure step_order allows 1-5: -ALTER TABLE auth_flow_steps DROP CONSTRAINT IF EXISTS chk_step_order; -ALTER TABLE auth_flow_steps - ADD CONSTRAINT chk_step_order CHECK (step_order >= 1 AND step_order <= 5); - --- 5. Auth session tracking (for step-by-step verification) -CREATE TABLE auth_sessions_mfa ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - session_token VARCHAR(128) NOT NULL UNIQUE, - user_id UUID NOT NULL REFERENCES users(id), - tenant_id UUID NOT NULL REFERENCES tenants(id), - flow_id UUID NOT NULL REFERENCES auth_flows(id), - current_step INTEGER NOT NULL DEFAULT 1, - total_steps INTEGER NOT NULL, - steps_data JSONB NOT NULL DEFAULT '[]', - ip_address VARCHAR(45), - user_agent TEXT, - created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(), - expires_at TIMESTAMP WITH TIME ZONE NOT NULL, - completed_at TIMESTAMP WITH TIME ZONE -); - -CREATE INDEX idx_mfa_session_token ON auth_sessions_mfa(session_token); -CREATE INDEX idx_mfa_session_expiry ON auth_sessions_mfa(expires_at) - WHERE completed_at IS NULL; - --- 6. Seed a CHOICE flow for Marmara tenant -INSERT INTO auth_flows (id, tenant_id, name, description, flow_type, operation_type, is_default, is_active) -VALUES ( - 'f0000002-0000-0000-0000-000000000001', - '11111111-1111-1111-1111-111111111111', - 'Marmara Adaptive Login', - 'Password + user-selectable 2FA from multiple options', - 'AUTHENTICATION', 'APP_LOGIN', false, true -); - --- Step 1: Password (SEQUENTIAL) -INSERT INTO auth_flow_steps (id, auth_flow_id, auth_method_id, step_order, step_type, is_required) -SELECT gen_random_uuid(), 'f0000002-0000-0000-0000-000000000001', id, 1, 'SEQUENTIAL', true -FROM auth_methods WHERE type = 'PASSWORD'; - --- Step 2: CHOICE of multiple 2FA methods -INSERT INTO auth_flow_steps (id, auth_flow_id, auth_method_id, step_order, step_type, is_required) -VALUES ('a0000002-0000-0000-0000-000000000001', - 'f0000002-0000-0000-0000-000000000001', - (SELECT id FROM auth_methods WHERE type = 'EMAIL_OTP'), -- primary/fallback - 2, 'CHOICE', true); - --- Populate CHOICE alternatives -INSERT INTO auth_flow_step_methods (step_id, auth_method_id, display_order) -SELECT 'a0000002-0000-0000-0000-000000000001', id, - CASE type - WHEN 'TOTP' THEN 1 - WHEN 'EMAIL_OTP' THEN 2 - WHEN 'FACE' THEN 3 - WHEN 'SMS_OTP' THEN 4 - WHEN 'FINGERPRINT' THEN 5 - WHEN 'HARDWARE_KEY' THEN 6 - WHEN 'VOICE' THEN 7 - WHEN 'QR_CODE' THEN 8 - WHEN 'NFC_DOCUMENT' THEN 9 - END -FROM auth_methods -WHERE type IN ('TOTP','EMAIL_OTP','FACE','SMS_OTP','FINGERPRINT','HARDWARE_KEY','VOICE','QR_CODE','NFC_DOCUMENT'); -``` - -### 3.2 Data Model - -``` -AuthFlow - ├── id, tenant_id, name, operation_type - ├── is_default, is_active - └── steps: List (ordered by step_order) - -AuthFlowStep - ├── id, auth_flow_id - ├── step_order: 1..5 - ├── step_type: SEQUENTIAL | CHOICE - ├── auth_method_id (primary method / fallback for CHOICE) - ├── is_required: boolean - ├── timeout_seconds: 120 - ├── max_attempts: 3 - ├── fallback_method_id (optional) - └── alternativeMethods: List ← via auth_flow_step_methods - ↓ only populated when step_type = CHOICE - -AuthMethod - ├── id, type, name, description - ├── category: BASIC | STANDARD | PREMIUM | ENTERPRISE - ├── platforms: [WEB, ANDROID, IOS, DESKTOP] - ├── requires_enrollment: boolean - └── is_active: boolean - -User - ├── ...existing fields... - └── preferred_2fa_method: VARCHAR(30) ← NEW - -UserEnrollment - ├── user_id, auth_method_type, status (ENROLLED/PENDING/...) - └── enrollment_data (JSONB) -``` - ---- - -## 4. API Design - -### 4.1 Login Initiation (Changed) - -**POST /api/v1/auth/login** - -Request: -```json -{ "email": "user@example.com" } -``` - -Response (MFA required): -```json -{ - "mfaRequired": true, - "sessionToken": "mfa_abc123def456", - "expiresIn": 600, - "steps": [ - { - "stepNumber": 1, - "stepType": "SEQUENTIAL", - "status": "PENDING", - "method": { - "type": "PASSWORD", - "name": "Password", - "enrolled": true - } - }, - { - "stepNumber": 2, - "stepType": "CHOICE", - "status": "LOCKED", - "availableMethods": [ - { "type": "TOTP", "name": "Authenticator App", "enrolled": true, "preferred": true }, - { "type": "EMAIL_OTP", "name": "Email OTP", "enrolled": true }, - { "type": "FACE", "name": "Face Recognition", "enrolled": true }, - { "type": "SMS_OTP", "name": "SMS OTP", "enrolled": false } - ] - } - ], - "currentStep": 1, - "totalSteps": 2 -} -``` - -Response (single-factor, no MFA): -```json -{ - "mfaRequired": false, - "accessToken": "eyJ...", - "refreshToken": "...", - "expiresIn": 3600, - "user": { ... } -} -``` - -### 4.2 Step Verification - -**POST /api/v1/auth/step/verify** - -Request: -```json -{ - "sessionToken": "mfa_abc123def456", - "stepNumber": 1, - "method": "PASSWORD", - "data": { - "password": "user_password_here" - } -} -``` - -Response (step passed, more steps remaining): -```json -{ - "stepCompleted": true, - "currentStep": 2, - "totalSteps": 2, - "nextStep": { - "stepNumber": 2, - "stepType": "CHOICE", - "status": "PENDING", - "availableMethods": [ - { "type": "TOTP", "name": "Authenticator App", "enrolled": true, "preferred": true }, - { "type": "EMAIL_OTP", "name": "Email OTP", "enrolled": true } - ] - } -} -``` - -Response (final step passed, auth complete): -```json -{ - "stepCompleted": true, - "authComplete": true, - "accessToken": "eyJ...", - "refreshToken": "...", - "expiresIn": 3600, - "user": { ... } -} -``` - -Response (step failed): -```json -{ - "stepCompleted": false, - "error": "Invalid verification code", - "attemptsRemaining": 2 -} -``` - -### 4.3 Backward Compatibility - -The existing `POST /auth/login` with `{ email, password }` remains supported: - -- If the flow has PASSWORD as step 1, the backend auto-verifies it in the login request -- If step 2+ exists, returns `twoFactorRequired: true` with `availableMethods[]` -- Old clients that only read `twoFactorMethod` (singular) still work — it's set to the preferred/first enrolled method - -### 4.4 Admin: Configure Auth Flow - -**PUT /api/v1/auth-flows/{flowId}/steps** - -```json -{ - "steps": [ - { - "stepOrder": 1, - "stepType": "SEQUENTIAL", - "authMethodType": "PASSWORD" - }, - { - "stepOrder": 2, - "stepType": "CHOICE", - "methods": ["TOTP", "EMAIL_OTP", "FACE", "SMS_OTP"], - "fallbackMethod": "EMAIL_OTP", - "timeoutSeconds": 120, - "maxAttempts": 3 - }, - { - "stepOrder": 3, - "stepType": "SEQUENTIAL", - "authMethodType": "FACE", - "timeoutSeconds": 60 - } - ] -} -``` - ---- - -## 5. Frontend: Step-Based Auth UI - -### 5.1 Step Progress Indicator - -``` -┌─────────────────────────────────────────┐ -│ ● Step 1 ○ Step 2 ○ Step 3 │ ← progress dots -│ Password 2FA Face │ -├─────────────────────────────────────────┤ -│ │ -│ [Current step content here] │ -│ │ -└─────────────────────────────────────────┘ -``` - -### 5.2 Method Picker (for CHOICE steps) - -``` -┌─────────────────────────────────────────┐ -│ Step 2 of 3: Choose Verification │ -│ │ -│ ┌───────────────────────────────────┐ │ -│ │ 🔑 Authenticator App ★ │ │ ← preferred (star) -│ │ Enter 6-digit code from app │ │ -│ └───────────────────────────────────┘ │ -│ │ -│ ┌───────────────────────────────────┐ │ -│ │ ✉️ Email OTP │ │ -│ │ Code sent to a***@gmail.com │ │ -│ └───────────────────────────────────┘ │ -│ │ -│ ┌───────────────────────────────────┐ │ -│ │ 👤 Face Recognition │ │ -│ │ Verify with your camera │ │ -│ └───────────────────────────────────┘ │ -│ │ -│ ┌───────────────────────────────────┐ │ -│ │ 📱 SMS OTP ⚠️ │ │ ← not enrolled -│ │ Not set up — go to Settings │ │ -│ └───────────────────────────────────┘ │ -│ │ -└─────────────────────────────────────────┘ -``` - -### 5.3 Component Architecture - -``` -LoginPage / WidgetAuthPage - └─ StepAuthFlow (new orchestrator component) - ├─ StepProgressBar (dots: ● ○ ○) - ├─ if currentStep.type === 'CHOICE': - │ └─ MethodPickerStep (cards for each method) - │ └─ on select → render appropriate input component - ├─ if currentStep.type === 'SEQUENTIAL': - │ └─ render method component directly - │ - ├─ Method Components (existing, reused): - │ ├─ PasswordStep - │ ├─ TotpStep - │ ├─ EmailOtpStep - │ ├─ SmsOtpStep - │ ├─ FaceCaptureStep - │ ├─ VoiceStep - │ ├─ FingerprintStep - │ ├─ HardwareKeyStep - │ ├─ QrCodeStep - │ └─ NfcStep - │ - └─ on all steps complete → receive tokens → redirect/postMessage -``` - ---- - -## 6. Widget Responsiveness Fix - -### 6.1 Root Causes - -| Problem | File | Line(s) | -|---------|------|---------| -| `minHeight: '100vh'` inside 540px iframe | WidgetAuthPage.tsx | 861 | -| Same in 2FA components | TwoFactorVerification.tsx, TwoFactorDispatcher.tsx | 124, 189 | -| Fixed iframe height `540px` | bys-demo/index.html | — | -| `overflow: hidden` clips content | bys-demo CSS | — | -| Inconsistent maxWidth (360–480px) | Multiple components | — | - -### 6.2 Fixes - -**A) Iframe detection + adaptive layout:** -```tsx -const isInIframe = window !== window.parent - - -``` - -**B) Dynamic iframe resizing via postMessage:** -```tsx -useEffect(() => { - if (isInIframe) { - const height = document.documentElement.scrollHeight - window.parent.postMessage({ - type: 'fivucsas:resize', - payload: { height: Math.min(height, 700) } - }, '*') - } -}, [currentStep, selectedMethod, loading, error]) -``` - -**C) Overlay container — allow scroll:** -```css -.fivucsas-overlay-inner { - overflow-y: auto; /* was: hidden */ - max-height: min(90vh, 640px); -} -``` - -**D) Standardize component widths:** -```tsx -const WIDGET_CONTENT_MAX_WIDTH = 400 // single source of truth -``` - ---- - -## 7. Admin UI: Flow Builder - -### 7.1 Visual Step Builder - -The Auth Flows admin page gets a drag-and-drop step builder: - -``` -┌─ Flow: Marmara Adaptive Login ─────────────────┐ -│ Operation: APP_LOGIN | ● Active ● Default │ -├──────────────────────────────────────────────────┤ -│ │ -│ Step 1 [×] │ -│ ┌──────────────────────────────────────┐ │ -│ │ Type: ● Sequential ○ Choice │ │ -│ │ Method: [PASSWORD ▼] │ │ -│ └──────────────────────────────────────┘ │ -│ │ -│ Step 2 [×] │ -│ ┌──────────────────────────────────────┐ │ -│ │ Type: ○ Sequential ● Choice │ │ -│ │ Methods: │ │ -│ │ [x] EMAIL_OTP │ │ -│ │ [x] TOTP │ │ -│ │ [x] FACE │ │ -│ │ [ ] SMS_OTP │ │ -│ │ [x] FINGERPRINT │ │ -│ │ [x] HARDWARE_KEY │ │ -│ │ [ ] VOICE │ │ -│ │ Fallback: [EMAIL_OTP ▼] │ │ -│ └──────────────────────────────────────┘ │ -│ │ -│ [+ Add Step] │ -│ │ -│ ──────────────────────────────────────── │ -│ Preview: PASSWORD → CHOICE[6 methods] (2FA) │ -│ │ -│ [Save Flow] [Cancel] │ -└──────────────────────────────────────────────────┘ -``` - ---- - -## 8. Implementation Plan - -### Phase A: Widget Responsiveness (0.5 session) - -| # | Task | Files | -|---|------|-------| -| A1 | Add `isInIframe` detection + adaptive min-height | WidgetAuthPage.tsx | -| A2 | Remove `minHeight: '100vh'` from 2FA components | TwoFactorVerification.tsx, TwoFactorDispatcher.tsx | -| A3 | Add postMessage resize on state changes | WidgetAuthPage.tsx | -| A4 | Fix overlay CSS (`overflow-y: auto`) | bys-demo/index.html | -| A5 | Standardize maxWidth to 400px | All widget components | -| A6 | Test in iframe (BYS demo) + standalone | Manual | - -### Phase B: Backend Multi-Step MFA (1 session) - -| # | Task | Files | -|---|------|-------| -| B1 | Flyway V30 migration | V30__adaptive_mfa.sql | -| B2 | Add `StepType` enum + update `AuthFlowStep` entity | StepType.java, AuthFlowStep.java | -| B3 | Create `AuthStepSession` entity (Redis/DB) | AuthStepSession.java | -| B4 | Create `AvailableTwoFactorMethod` DTO | AvailableTwoFactorMethod.java | -| B5 | Refactor `AuthenticateUserService` — build step chain | AuthenticateUserService.java | -| B6 | New endpoint: `POST /auth/step/verify` | AuthController.java | -| B7 | Update login response (availableMethods, steps) | AuthResponse.java | -| B8 | Backward compat: old login with password still works | AuthController.java | -| B9 | Seed CHOICE flow for Marmara tenant | V30 migration | -| B10 | Add `preferred_2fa_method` endpoint | AuthController.java | - -### Phase C: Frontend Multi-Step (1 session) - -| # | Task | Files | -|---|------|-------| -| C1 | Create `StepAuthFlow` orchestrator component | StepAuthFlow.tsx | -| C2 | Create `StepProgressBar` component | StepProgressBar.tsx | -| C3 | Create `MethodPickerStep` component | MethodPickerStep.tsx | -| C4 | Update `LoginPage` to use `StepAuthFlow` | LoginPage.tsx | -| C5 | Update `WidgetAuthPage` to use `StepAuthFlow` | WidgetAuthPage.tsx | -| C6 | Admin: Flow Builder with CHOICE step UI | AuthFlowsPage.tsx | -| C7 | Settings: preferred 2FA method selector | SettingsPage.tsx | -| C8 | i18n: method picker strings (EN + TR) | en.json, tr.json | - ---- - -## 9. Security Considerations - -1. **Step order enforcement:** Backend rejects step N verification if step N-1 is not COMPLETED -2. **Method validation:** Chosen method must be (a) in the flow step AND (b) enrolled by the user -3. **Session expiry:** MFA sessions expire in 10 minutes; abandoned sessions auto-cleanup -4. **Rate limiting:** Per-method limits (EMAIL_OTP: 5 sends/10min, PASSWORD: 5 attempts/15min) -5. **Audit trail:** Log each step completion with method, IP, user-agent, timestamp -6. **No downgrade:** If a flow requires 3 steps, all 3 must pass; client cannot skip steps -7. **Fallback security:** Fallback methods (e.g., EMAIL_OTP when TOTP fails) count as the same step — not a bypass -8. **Enrollment check:** Methods with `requires_enrollment: true` are only offered if the user has `status: ENROLLED` -9. **Replay prevention:** Each step verification token is single-use; session state tracks completed steps - ---- - -## 10. Migration & Backward Compatibility - -### 10.1 Zero-Downtime Migration - -1. V30 migration adds columns with defaults — no breaking change -2. Existing flows remain `SEQUENTIAL` at all steps — behavior unchanged -3. Old `POST /auth/login { email, password }` auto-resolves PASSWORD as step 1 -4. Old `twoFactorMethod` field remains in response alongside new `availableMethods[]` -5. Clients that don't understand `availableMethods` fall back to single `twoFactorMethod` - -### 10.2 Gradual Rollout - -1. Deploy backend changes → old flows work identically -2. Create new CHOICE flows → activate for specific tenants -3. Deploy frontend changes → method picker appears -4. Set CHOICE flow as default → users see new UI -5. Remove old single-method flows → cleanup diff --git a/plans/NFC_PUSH_APPROVAL_PROTOCOL.md b/plans/NFC_PUSH_APPROVAL_PROTOCOL.md deleted file mode 100644 index 13d25f2..0000000 --- a/plans/NFC_PUSH_APPROVAL_PROTOCOL.md +++ /dev/null @@ -1,332 +0,0 @@ -# NFC Push-Approval Protocol - -Status: Draft v1.0 -Owner: Identity Core API / Client-Apps -Scope: Cross-device NFC verification handoff (browser -> mobile -> browser) -Depends on: V34-V38 (confidential clients, mfa_sessions guards), QR session pattern, device registration -Author: Platform Engineering -Last reviewed: 2026-04-18 - -## 1. Problem Statement - -FIVUCSAS supports ten auth methods, including `NFC_DOCUMENT`. The web surface cannot read an ICAO 9303 passport, a Turkish eID chip (TD1 MRZ), nor arbitrary ISO 14443 cards across target browsers: - -- **iOS Safari has no WebNFC.** No shipped API, no public timeline. iPhone users have no chip path today. -- **Desktop browsers have no NFC radio.** Even where WebNFC exists (Chromium Android) it only exposes NDEF, not ISO-DEP / APDU required for BAC/PACE. -- **Web BAC is impossible.** BAC derives session keys from the MRZ and opens secure messaging over APDU; the WebNFC NDEF surface cannot transmit `transceive()` traffic. -- **The app can already read the chips.** `PassportNfcReader.kt` does BAC + secure messaging + SOD/DG1/DG2 today; `StudentCardNfcReader` and `IstanbulkartNfcReader` cover NDEF. Capability exists; cross-device handoff does not. - -e-Devlet solves the same gap by handing users into a mobile app to approve a pending web session. This spec defines the FIVUCSAS equivalent. - -## 2. Actors - -| Actor | Role | -|-------|------| -| Browser | Initiates verification, renders QR/deep-link, polls. Hosted login (`verify.fivucsas.com`) or widget. | -| Identity Core (IC) | `api.fivucsas.com`. Owns session state (Redis + Postgres), validates chip signatures, mints MFA tokens. | -| Mobile App | KMP/Compose (Android now, iOS Phase 2). Reads chip, signs with device-bound key, returns user to browser. | -| FCM / APNS | Optional nudge when browser is on the same phone and tab is hidden. | -| User | Physically present with phone + chip. | - -## 3. End-to-End Sequence - -### 3.1 Textual steps - -1. **Browser** `POST /api/v1/nfc/session` with `{ cardType, flow, returnUrl, clientId, mfaSessionId? }`. `cardType in {passport, tckn_id, student_card, rp_card}`; `flow in {enroll, auth}`; `mfaSessionId` present when NFC is a step inside an MFA chain. -2. **IC** writes `nfc:session:{sessionId}` in Redis: `status=PENDING_SCAN`, TTL 300s, random base64url `nonce` (32 bytes) bound to the session (PKCE-style: app must echo, IC recomputes). Returns `{ sessionId, nonce, expiresAt, deepLink, qrPayload }`. -3. **Browser** renders QR + "Open in App" button (on mobile user-agent). Link: `fivucsas://nfc-session?sessionId=&nonce=&returnUrl=`. Polls `GET /api/v1/nfc/session/{sessionId}` every 2s. -4. **User** opens app via deep link / Universal Link / manual code. App displays approval context (requesting device fingerprint, city, time) and prompts for scan. -5. **App** reads chip. Passport / TCKN: user enters MRZ first; `PassportNfcReader.readCardWithAuth()` runs BAC and returns SOD-verified DG1/DG2. NDEF cards: `StudentCardNfcReader` returns UID + parsed records. -6. **App** `POST /api/v1/nfc/session/{sessionId}/submit` with body `{ deviceId, nonce, cardType, chipPayload, documentHash, capturedAt, sodSignatureValid, dg1Hash, dg2Hash }`, signed by device private key (Ed25519), `Authorization: Bearer `. -7. **IC** validates in order: (a) session exists + `PENDING_SCAN`, (b) nonce matches, (c) device JWT valid + trusted, (d) payload signature verifies, (e) for ICAO chips: passive authentication (SOD -> CSCA trust store; submitted DG hashes match SOD), (f) dedupe (same device in last 30s), (g) document not blacklisted. -8. **IC** marks session `APPROVED`, writes a `verification_sessions` row linking `nfc_session_id` + resolved `user_id` + `document_hash`, and if inside an MFA chain advances `mfa_sessions` per the V35 `consumed_at` pattern. -9. **Browser** polling receives `{ status: "APPROVED", mfaSessionToken }`, calls `POST /api/v1/auth/mfa/step`, completes the chain, redirects to `returnUrl` with the OIDC `code`. -10. **App** optionally fires `Intent.ACTION_VIEW(returnUrl)` (Android) or `UIApplication.open(_:)` (iOS) so the same-phone browser tab returns. Desktop browsers advance on their own via polling. - -### 3.2 Sequence diagram - -```mermaid -sequenceDiagram - participant U as User - participant B as Browser - participant IC as Identity Core - participant R as Redis - participant A as Mobile App - participant P as FCM/APNS - - B->>IC: POST /api/v1/nfc/session {cardType, flow, returnUrl} - IC->>R: SETEX nfc:session:{id} PENDING_SCAN, nonce, 300s - IC-->>B: {sessionId, nonce, deepLink, qrPayload} - B->>U: Render QR + "Open in App" - Note over B,IC: Browser begins polling GET /session/{id} - - U->>A: Scan QR (or tap deep link) - A->>A: Prompt MRZ (passport/TCKN) -> tap chip - A->>A: BAC + secure messaging + SOD verify - A->>IC: POST /nfc/session/{id}/submit (device JWT + signed payload) - IC->>IC: Validate nonce, device, signature, passive auth - IC->>R: SET nfc:session:{id} APPROVED - IC-->>A: {ok, userId, mfaSessionToken} - - alt Browser on same phone - A->>B: Intent.ACTION_VIEW(returnUrl) - else Browser elsewhere - IC-->>P: Optional nudge (if browser-side push registered) - P-->>B: Notification - end - - B->>IC: GET /nfc/session/{id} - IC-->>B: {status: APPROVED, mfaSessionToken} - B->>IC: POST /auth/mfa/step (continue chain) - IC-->>B: {code} -> redirect to returnUrl -``` - -## 4. Deep-Link URI Scheme - -### 4.1 Format - -``` -fivucsas://nfc-session?sessionId=&nonce=&returnUrl=&v=1 -``` - -`sessionId` (UUID v4), `nonce` (base64url 32B, must match Redis), `returnUrl` (HTTPS, validated against `oauth2_clients.redirect_uris` before the app renders it), `v` (protocol version; unknown versions fail closed). - -### 4.2 Android registration - -`AndroidManifest.xml` (`client-apps/androidApp/src/main/AndroidManifest.xml`) adds an intent filter on the entry activity: - -```xml - - - - - - - - - - - - -``` - -App Link hardens against hostile apps registering the same scheme; `assetlinks.json` lives at `https://api.fivucsas.com/.well-known/assetlinks.json`. - -### 4.3 iOS registration - -`Info.plist`: - -```xml -CFBundleURLTypes - - - CFBundleURLNamecom.fivucsas.mobile - CFBundleURLSchemesfivucsas - - -``` - -Universal Link: `apple-app-site-association` at `https://api.fivucsas.com/.well-known/apple-app-site-association` with `applinks` path `/nfc-session/*`. Requires Apple Developer Team ID (Section 15). - -### 4.4 Fallback when app is not installed - -If the deep link does not resolve within 1500ms, the browser redirects to a mobile landing page that sends the user to the Play / App Store with a `referrer` carrying the `sessionId`. On first launch the app reads the install referrer and resumes the session if still within TTL. - -## 5. Device Registration Protocol - -Submissions must be signed by a registered, user-bound device; otherwise a harvested link plus a forged chip dump would authenticate anyone. - -### 5.1 One-time flow - -1. User logs in on the mobile app (existing flow). -2. App generates a non-exportable Ed25519 key pair in Android Keystore (StrongBox preferred) or iOS Secure Enclave. -3. App `POST /api/v1/device/register` with: - -```json -{ - "publicKey": "", - "platform": "android|ios", - "osVersion": "14", - "appVersion": "1.4.0", - "fingerprint": "", - "fcmToken": "", - "apnsToken": "" -} -``` - -4. IC persists a `devices` row, returns `{ deviceId, deviceJwt }`. JWT lifetime 90 days, claim `cnf.jkt = sha256(publicKey)` so replay requires the private key. -5. Subsequent submits sign the canonical JSON payload with Ed25519 and send the signature in `X-Device-Signature`; unsigned submissions are rejected. - -### 5.2 Revocation - -My Profile lists devices with `last_seen` + revoke button. Revoke flips `devices.trusted=false` and adds a Redis denylist entry `device:revoked:{deviceId}` (TTL = remaining JWT lifetime). - -## 6. FCM / APNS Push - -### 6.1 When push fires - -Push is optional; primary path is polling. Push fires only when the browser is on the same phone, the user has switched apps (tab hidden), and a push token is registered. Without push, polling completes in 2 seconds. - -### 6.2 Payload - -```json -{ - "type": "nfc.approve", - "sessionId": "", - "expiresAt": "2026-04-18T14:32:17Z", - "cardType": "passport" -} -``` - -Silent on Android (`content_available=true`), `aps.content-available=1` on iOS. App posts a high-priority system notification and deep-links to the approval screen on tap. - -### 6.3 Rate limit - -One push per `sessionId`, at most three per device per hour, enforced via the existing Bucket4j layer. - -### 6.4 Fallback - -On `NotRegistered` / `Unregistered`, mark the token inactive and fall back to polling. Push delivery never blocks the flow. - -## 7. Return Path - -Once the app has submitted and IC returns `APPROVED`, the user's attention must return to the browser that began the session. - -| Option | Mechanism | Trade-off | -|--------|-----------|-----------| -| **(a) Deep-link back** | Android `Intent.ACTION_VIEW(returnUrl)`, iOS `UIApplication.open(_:)`. | Works same-phone; no-op when browser is elsewhere. **Ship.** | -| **(b) In-app browser** | Custom Tabs / SFSafariViewController. | Seamless single-device, but cookie isolation + doesn't help cross-device. Not Phase 1. | -| **(c) Manual switch + polling** | Browser polls every 2s. | Works across all topologies; risk if user closes tab. **Always active.** | - -Ship (a) + (c). Success screen copy: "You can return to your computer now." - -## 8. Security Review - -| Threat | Mitigation | Server-side test | -|--------|------------|------------------| -| Deep-link replay | Nonce bound to session, 5-min TTL, invalidated on first submit. | Submit same nonce twice -> 409. | -| MITM on submit | TLS 1.3, HSTS preload, device JWT bound to pubkey (`cnf.jkt`). | Reject when `cnf.jkt` != hash(pubkey). | -| Session fixation | `sessionId` generated server-side; never accepted from client. | Attacker-chosen id -> 400. | -| Cross-session confusion | Submit carries `sessionId` + `nonce`; IC cross-checks. | Swap nonces across sessions -> 401. | -| Device spoofing | Device JWT + Ed25519 signature; StrongBox / Secure Enclave when available. | Rotated pubkey -> 401. | -| Chip forgery (passive auth) | SOD verified against CSCA trust store; DG1/DG2 hashes must match SOD. | Tampered DG1 -> 422; unknown CSCA -> 422. | -| Active Authentication bypass | When DG15/DG14 present, require AA response; policy-gated rejection if absent. | DG15-present fixture with no AA -> reject in strict mode. | -| PII in logs / URLs | `returnUrl` query params tenant-allowlisted; `SecureLogger` redacts chip fields. | Static scan + unit: logs carry no chip fields. | -| TTL leak / zombies | Redis TTL 300s; terminal write to Postgres; polling past TTL -> 410. | Approve, wait 301s -> Postgres row present, Redis key gone. | -| `returnUrl` open redirect | Validated against `oauth2_clients.redirect_uris` at session creation. | Non-allowlisted URL -> 400 at create. | -| FCM/APNS token leak | AES-GCM encrypted at rest; never echoed to browser; rotated on reinstall. | Dump `devices` row JSON -> token masked. | -| Stolen document | Daily Interpol SLTD refresh; KPS/MERNIS check when tenant has contract. | Blacklisted hash -> 403 `DOCUMENT_REVOKED`. | -| Unrelated chip | `cardType` declared in web session checked against AID / DG1 format. | Mismatched type -> 422. | - -All rows above must have passing tests before Phase 1 ships. - -## 9. Database Changes - -Next migration: `V39__nfc_sessions_and_devices.sql` (current max confirmed is V38). - -```sql --- V39__nfc_sessions_and_devices.sql - -CREATE TABLE nfc_sessions ( - id UUID PRIMARY KEY, - tenant_id UUID NOT NULL REFERENCES tenants(id), - client_id UUID NOT NULL REFERENCES oauth2_clients(id), - mfa_session_id UUID REFERENCES mfa_sessions(id), - card_type VARCHAR(32) NOT NULL, - flow VARCHAR(16) NOT NULL, -- 'enroll' | 'auth' - status VARCHAR(24) NOT NULL, -- PENDING_SCAN | APPROVED | EXPIRED | REJECTED - nonce_hash CHAR(64) NOT NULL, -- SHA-256 of nonce; raw nonce never persisted - return_url TEXT NOT NULL, - device_id UUID, - document_hash CHAR(64), -- SHA-256 of document number + issuer - approved_at TIMESTAMPTZ, - created_at TIMESTAMPTZ NOT NULL DEFAULT now(), - expires_at TIMESTAMPTZ NOT NULL -); - -CREATE INDEX idx_nfc_sessions_status_expires - ON nfc_sessions(status, expires_at); -CREATE INDEX idx_nfc_sessions_tenant_created - ON nfc_sessions(tenant_id, created_at DESC); - -CREATE TABLE devices ( - id UUID PRIMARY KEY, - user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE, - public_key BYTEA NOT NULL, - platform VARCHAR(16) NOT NULL, - os_version VARCHAR(32), - app_version VARCHAR(32), - fingerprint CHAR(64) NOT NULL, - fcm_token_enc BYTEA, - apns_token_enc BYTEA, - trusted BOOLEAN NOT NULL DEFAULT true, - created_at TIMESTAMPTZ NOT NULL DEFAULT now(), - last_seen_at TIMESTAMPTZ, - revoked_at TIMESTAMPTZ, - UNIQUE(user_id, fingerprint) -); - -CREATE INDEX idx_devices_user_trusted - ON devices(user_id, trusted) WHERE revoked_at IS NULL; - -ALTER TABLE verification_sessions - ADD COLUMN nfc_session_id UUID REFERENCES nfc_sessions(id); -CREATE INDEX idx_verification_sessions_nfc - ON verification_sessions(nfc_session_id); -``` - -Notes: Redis is source of truth for live sessions; Postgres row is written on terminal transition so audit survives a Redis flush. Only the nonce hash is persisted; raw nonce never leaves Redis. `fcm_token_enc` / `apns_token_enc` use AES-GCM via existing `CryptoService`. - -## 10. Android Implementation Notes - -- Manifest: add the two intent filters from Section 4.2 to `MainActivity`. -- `NfcSessionDeepLinkParser` extracts `sessionId`, `nonce`, `returnUrl`; reject on missing/malformed. -- `PassportNfcReader.readCardWithAuth(tag, AuthenticationData.MrzData(...))` is unchanged. New `NfcApprovalViewModel` invokes it, then `NfcSessionRepository.submit(...)` handles canonical JSON + Ed25519 signing. -- ViewModel states: `Idle -> AwaitingMrz -> Ready -> Scanning -> Submitting -> Approved | Failed(reason)`, logged via `SecureLogger`. -- Error UX: no NFC hardware -> fall back to manual entry if tenant permits; NFC disabled -> `Settings.ACTION_NFC_SETTINGS`; BAC failed -> retry up to 3x then server-side invalidate; SOD invalid -> abort with support code; expired -> back to browser. -- Timeouts: chip read 45s (existing `TIMEOUT_MS`); submit HTTP 10s with exponential back-off on 5xx. - -## 11. iOS Implementation Notes - -- Entitlements: `com.apple.developer.nfc.readersession.formats = ["TAG"]` and `applinks:api.fivucsas.com`. Requires paid developer account. -- `NFCTagReaderSession` with `.iso14443` polling; cast to `NFCISO7816Tag`; run the same APDU ladder as `EidApduHelper`. -- BAC/PACE: iOS has no OS-level BAC. Use a port of JMRTD or in-house OpenSSL primitives in `shared/iosMain`, sharing logic with `BacAuthentication` via `expect/actual`. -- Reuse `MrzParser`, `Dg1Parser`, `Dg2Parser` from `shared/commonMain`. -- Deep-link: `SceneDelegate.scene(_:openURLContexts:)` for custom scheme; `scene(_:continue:)` + `NSUserActivity.webpageURL` for Universal Links. Both route to `NfcApprovalViewModel`. -- Pre-NFC iPhones (6 and below): show `CoreNFC not supported`, offer QR-to-other-device fallback. - -## 12. Desktop Implementation Notes - -Desktop typically has no NFC radio. Two paths: - -- **(a) Delegate to phone.** Default. Browser renders QR, user scans with the app, polling completes. No new desktop code. -- **(b) USB NFC reader.** Phase 3. Compose Desktop module using `javax.smartcardio` to drive PC/SC readers (ACR1252U class). Reuses `PassportNfcReader` via KMP `desktopMain`. Gated on tenant demand. - -Phase 1 ships (a) only. - -## 13. Test Plan - -- **Unit.** Chip fixtures (3 TD3 passports: US/TR/DE; 2 TD1 Turkish eID; 2 student cards); canonical JSON + Ed25519 round-trip; nonce replay/mismatch; device JWT tampering; `cnf.jkt` mismatch. -- **Integration (Testcontainers).** Full `/api/v1/nfc/session` lifecycle (Postgres + Redis); passive auth against a test CSCA; SLTD / MERNIS / KPS stubs via WireMock; per-device submit rate limits. -- **End-to-end.** Playwright drives `verify.fivucsas.com`, reads QR; Android emulator with HCE fixture consumes the deep link and submits; browser must advance within 3s. -- **Acceptance.** 99.5% happy-path sessions under 90s wall-clock; zero false approvals in a 10k fuzz suite; p95 submit validation under 400ms excluding cached CSCA chain; every Section 8 row has a passing test. - -## 14. Rollout Phases - -| Phase | Scope | Gate | -|-------|-------|------| -| 1 | Android + web. Passports + TCKN. Polling only. Internal tenants. | V39 applied; Android internal track; Section 13 acceptance. | -| 2 | iOS CoreNFC. Universal Links. FCM + APNS. | Apple entitlement; CSCA loaded in prod. | -| 3 | Desktop USB reader module. | Tenant demand; hardware matrix frozen. | -| 4 | Tenant opt-in GA. Dashboard + runbook. SLA. | 30 days of Phase 1+2 with <0.1% non-user validation failures. | - -## 15. Open Questions (for Ahmet) - -1. **Turkish ID ISO-DEP scope.** Target only post-2017 Kimlik Kart, or do we need a legacy read path? Field data suggests post-2017 only; confirm. -2. **Apple Developer Team ID.** Universal Links + CoreNFC need a paid account. Team ID? Is the USD 99/yr budgeted? Blocks Phase 2. -3. **CSCA master list source.** Public ICAO PKD, commercial mirror (Netrust/HID), or monthly download from ICAO's free master list? Drives passive-auth freshness SLA. -4. **SMS push fallback.** For devices without FCM/APNS (HMS-only OEMs), do we accept SMS carrying the deep link (Twilio cost), or polling-only? -5. **KPS/MERNIS contract.** TCKN revocation needs a licensed NVI integrator. Partner lined up, or Phase 1 ships without revocation check? -6. **Active Authentication policy.** When DG15/DG14 present, reject on missing AA, or log-only? Strict is safer; log-only is more compatible with older chips. -7. **`nfc_sessions` retention.** Proposed 90 days then purge. Confirm against KVKK/GDPR retention. diff --git a/plans/PATH_TO_20_20.md b/plans/PATH_TO_20_20.md deleted file mode 100644 index c1a281d..0000000 --- a/plans/PATH_TO_20_20.md +++ /dev/null @@ -1,91 +0,0 @@ -# Path to 20/20 — Android Feature Parity Close-out Plan - -> Last updated: 2026-04-18e — Canonical plan for closing the five remaining gaps between the FIVUCSAS Android client (v5.1.0) and the web-app 20/20 reference. Total estimate: ~8 engineer-days, fully parallelizable across five code agents (20A–20E). This file supersedes per-gap notes scattered across `client-apps/docs/TODO.md`, `CLIENT_APPS_PARITY.md`, and `NFC_PUSH_APPROVAL_PROTOCOL.md` for the Android-only 20/20 push. - -## Context - -Cross-platform deep review (2026-04-18e) confirmed: - -- **KMP genuineness.** 337 files under `client-apps/shared/src/commonMain/` totalling ~11,500 LOC of real domain / data / presentation code. This is not a shared-scaffold + per-platform-fork project. -- **Android baseline: ~15/20 feature parity** against web. The previously circulated 13/20 figure underweighted the already-ported NFC infrastructure. -- **NFC crypto already ported.** 5,447 LOC under `client-apps/androidApp/src/main/kotlin/com/fivucsas/mobile/android/data/nfc/`: `PassportNfcReader` (873), `TurkishEidReader` (457), `BacAuthentication` (502), `SecureMessaging` (470), plus Dg1/Dg2/MRZ parsers and `CardReaderFactory`. `NfcReadScreen.kt` (642 LOC, MRZ input UI + `koinInject`) exists. **The gap is integration only**: `MfaFlowScreen.kt:324` still dispatches `NFC_DOCUMENT` to `GenericMethodStepInput` placeholder. -- **Ship A** (Wave A prod fixes — CORS preflight, verify-widget ORT 404, BlazeFace singleton, `dropConsole`, i18n banner) verified in prod. -- **Ship D** (Android TOTP authenticator v5.1.0 — RFC 6238 engine in commonMain, `EncryptedSharedPreferences` vault, Compose Material 3 UI) tagged and shipped. QR-scan follow-up = Gap #5. - -The five gaps below are what stand between Android v5.1.0 and 20/20. - -## The five gaps - -| # | Gap | Current state (commit/line references) | Work to do | Files new | Files modified | Days | -|---|-----|-----------------------------------------|------------|-----------|----------------|------| -| **1** | **Passport BAC MFA integration** | NFC crypto stack (5,447 LOC) already under `androidApp/data/nfc/`. `NfcReadScreen.kt` exists (MRZ input UI + `koinInject`). `MfaFlowScreen.kt:324` still routes `NFC_DOCUMENT` → `GenericMethodStepInput` placeholder. MRZ camera capture does not exist on Android (only on `practice-and-test/UniversalNfcReader`). | Port `MrzScannerScreen.kt` from `practice-and-test/UniversalNfcReader` (CameraX preview + OCR via ML Kit text recognition + ICAO MRZ line regex). Create `NfcStepScreen.kt` that hosts `MrzScannerScreen` → BAC key derivation → `PassportNfcReader.read()` → DG1/DG2 parse → server `/api/v1/mfa/nfc/verify`. Replace the `GenericMethodStepInput` dispatch at `MfaFlowScreen.kt:324`. | `NfcStepScreen.kt`, `MrzScannerScreen.kt`, `NfcStepViewModel.kt`, `MrzScannerViewModel.kt` | `MfaFlowScreen.kt` (dispatcher), `AndroidManifest.xml` (camera permission already present — verify), `strings.xml` + `en.json`/`tr.json` (MRZ capture copy) | ~2 | -| **2** | **GDPR/KVKK export mobile UI** | Backend `GET /users/{id}/export` shipped 2026-04-16b. Web-app wired 2026-04-18 on `MyProfilePage`. Android has **zero UI**. | New `GdprRepository` in `data/repository/` hitting the `/export` endpoint; `GdprViewModel` in `shared/presentation/viewmodel/`; "Download my data" row on `ProfileScreen` with DataStore-gated rate-limit; Android `DownloadManager` integration to save the returned JSON to Downloads; 8 i18n keys covering button label, confirmation dialog, success toast, error toast, "Download started" notification, file-name template, rate-limit message, KVKK disclosure. | `GdprRepository.kt`, `GdprViewModel.kt`, `GdprExportButton.kt` (Compose row) | `ProfileScreen.kt` (add row), `AppModule.kt` (DI), `en.json` + `tr.json` (8 keys), `AndroidManifest.xml` (WRITE permission if scoped-storage path chosen) | ~2 | -| **3** | **FCM action buttons + `fivucsas://` deep-link** | `FivucsasFirebaseMessagingService` currently shows plain notifications. `AndroidManifest.xml` has only the `TECH_DISCOVERED` intent-filter (NFC tag discovery). No Allow/Deny actions, no deep-link scheme, no `onNewIntent` handler. Protocol spec already exists in `docs/plans/NFC_PUSH_APPROVAL_PROTOCOL.md`. | Add Allow / Deny `NotificationCompat.Action` buttons on push notifications built in `FivucsasFirebaseMessagingService`; create `ApprovalActionReceiver` (BroadcastReceiver) to POST the signed approval to `/api/v1/nfc/approve` or `/deny`; add `fivucsas://nfc-session` custom scheme to `AndroidManifest.xml` with `android:autoVerify="false"`; wire `MainActivity.onNewIntent` to parse the session-id path segment + hop to `NfcStepScreen`; Ed25519 signature per protocol spec. | `ApprovalActionReceiver.kt`, `NfcSessionDeepLinkHandler.kt` | `FivucsasFirebaseMessagingService.kt`, `AndroidManifest.xml`, `MainActivity.kt`, `AppModule.kt` | ~2 | -| **4** | **Dark mode toggle in Settings** | `AppColors.kt` already exposes both palettes (light + dark). Theme is driven by `isSystemInDarkTheme()` with no user override. Settings has no theme row. | Add `ThemeMode { SYSTEM, LIGHT, DARK }` enum in `shared/presentation/state/`. New `ThemePreferences` backed by DataStore. Expose via `CompositionLocalOf` so `FivucsasTheme` can resolve. Add a 3-radio row on `SettingsScreen` ("Follow system / Light / Dark") with live preview. | `ThemeMode.kt`, `ThemePreferences.kt`, `ThemeModeRow.kt` | `FivucsasTheme.kt`, `SettingsScreen.kt`, `SettingsViewModel.kt`, `AppModule.kt`, `en.json` + `tr.json` (4 keys) | ~1 | -| **5** | **Authenticator QR scanner** | v5.1.0 shipped manual entry only. The "Scan QR" bottom-sheet entry is currently a `Toast` redirecting users to manual entry. Existing `QrScannerScreen` (CameraX + ML Kit barcode) is already in the codebase for the QR-code auth method. `OtpauthUri.parse()` is already implemented in `shared/commonMain/.../authenticator/totp/`. | Create `OtpQrScannerScreen.kt` that reuses the existing `QrScannerScreen` CameraX + ML Kit pipeline but filters `BARCODE_FORMAT_QR_CODE`, pipes raw text through `OtpauthUri.parse()`, and dispatches a `ScannedAccount` event up to `AuthenticatorViewModel.addAccount()`. Replace the `Toast` fallback in the "Scan QR" bottom-sheet branch with a navigation call. | `OtpQrScannerScreen.kt`, `OtpQrScannerViewModel.kt` | `AuthenticatorScreen.kt` (bottom-sheet branch), `NavGraph.kt`, `en.json` + `tr.json` (3 keys) | ~1 | - -**Total: ~8 engineer-days, fully parallelizable.** - -## Implementation sequencing - -### Wave 1 — Documentation (1 agent, ~1 hour) - -Update the eight documentation files listed in the 2026-04-18e CHANGELOG entry. Blocks nothing but unblocks Wave 2 agents by publishing the canonical plan (this file). - -**Verification:** `git diff --stat` shows 8 files touched; `grep "2026-04-18e" ROADMAP.md CHANGELOG.md CLAUDE.md` returns matches; new `docs/plans/PATH_TO_20_20.md` exists. - -### Wave 2 — Five parallel code agents (20A–20E, ~8 engineer-days in parallel wall-clock) - -- **Agent 20A** — Gap #1 (NFC MFA integration). Owns `NfcStepScreen.kt` + `MrzScannerScreen.kt` + `MfaFlowScreen.kt:324` dispatcher change. -- **Agent 20B** — Gap #2 (GDPR export UI). Owns `GdprRepository` + `GdprViewModel` + `ProfileScreen` row + `DownloadManager` hook. -- **Agent 20C** — Gap #3 (FCM actions + deep link). Owns `ApprovalActionReceiver` + `fivucsas://` scheme + `onNewIntent` handler. -- **Agent 20D** — Gap #4 (Dark mode toggle). Owns `ThemeMode` enum + `ThemePreferences` + `SettingsScreen` row. -- **Agent 20E** — Gap #5 (QR scanner). Owns `OtpQrScannerScreen` + `AuthenticatorScreen` bottom-sheet branch. - -Agents work on separate feature branches off `main` to avoid collisions. `AppModule.kt`, `en.json`, and `tr.json` are the only commonly touched files; each agent lands their strings/DI wiring in a dedicated section with clear markers to reduce merge friction. - -### Wave 3 — Held on user input (queued) - -- **Ship B** (Android keystore rotation execution) — user-gated per GitGuardian #29836028 / `docs/SECURITY_INCIDENTS.md`. Scaffolding already shipped in commit `cb6eab9` 2026-04-18. -- **Ship C** (Phase C Wave 0 ops hardening — PostgreSQL + Redis + JWT + Twilio + biometric `X-API-Key` + Hostinger SMTP rotation + `.env.prod` history purge) — requires scheduled 2-hour maintenance window (JWT rotation signs everyone out). - -### Wave 4 — Consolidation + v5.2.0 tag - -After Wave 2 agents merge: - -1. Rebase all five branches onto `main`; resolve `AppModule.kt` + `en.json` + `tr.json` merges manually (expected). -2. `./gradlew :shared:test :androidApp:assembleDebug :androidApp:testDebugUnitTest` — expect all green except the pre-existing `BiometricViewModelTest.enrollFace` failure (tracked under Phase D of `client-apps/docs/TODO.md`). -3. Manual smoke tests on an Android device: - - Passport BAC → MRZ scanner captures, DG1/DG2 read, server accepts (Gap #1). - - Profile → Download my data → JSON lands in Downloads (Gap #2). - - FCM Allow action POSTs signed approval; `fivucsas://nfc-session/` deep-link opens app on correct screen (Gap #3). - - Settings → Theme → Light/Dark/System radio flips palette live (Gap #4). - - Authenticator → Scan QR → ML Kit reads `otpauth://totp/...` QR, account added (Gap #5). -4. Update `client-apps/CHANGELOG.md` `[Unreleased] — v5.2.0 planning` section to `[5.2.0] — ` with done items checked off. -5. Tag `v5.2.0` on `client-apps` submodule. Build signed release APK via `./gradlew :androidApp:assembleRelease` (requires `ANDROID_KEYSTORE_PASSWORD` / `ANDROID_KEY_PASSWORD` — see `client-apps/docs/RELEASE.md`). -6. Update parent `CHANGELOG.md` with the v5.2.0 shipping entry; bump submodule pointer. - -## Verification per wave - -| Wave | Command | Expected | -|------|---------|----------| -| 1 | `git diff --stat` on parent repo | 8 files changed (plus the new `PATH_TO_20_20.md`). | -| 2 (all 5) | `./gradlew :shared:test` | 424 + new tests green. | -| 2 (all 5) | `./gradlew :androidApp:assembleDebug` | APK produced. | -| 2 (all 5) | `./gradlew :androidApp:testDebugUnitTest` | Green except `BiometricViewModelTest.enrollFace` (pre-existing). | -| 4 | `./gradlew :androidApp:assembleRelease` | Signed release APK with the rotated keystore credentials. | -| 4 | Manual device smoke (5 flows above) | All five flows succeed end-to-end. | - -## Out of scope - -- **iOS / macOS parity.** DROPPED 2026-04-26 — permanently out of scope. The product owner has no Apple hardware for development, signing, or testing. Android APK + Windows + Linux desktop cover the demonstration target. Pre-existing KMP `iosMain` directories remain in the codebase for compile structure but receive no further engineering work. -- **Desktop NFC + installer signing.** PC/SC NFC stack and Windows Authenticode are Phase 3 of `CLIENT_APPS_PARITY.md`. macOS notarization is dropped (no Mac hardware). Tracked under `client-apps/docs/TODO.md` Phase C. -- **GitGuardian #29836028 keystore rotation.** User-gated; full playbook in `docs/SECURITY_INCIDENTS.md`. Rotation scaffolding already shipped (`cb6eab9`), but actual `keytool -storepasswd` + `keytool -keypasswd` + GitHub-secret paste is a manual operator action. -- **Phase C Wave 0 secret rotation.** PostgreSQL / Redis / JWT / Twilio / biometric / Hostinger SMTP rotation + `.env.prod` history purge requires a scheduled 2-hour maintenance window. Tracked as Phase C1–C5 in parent `ROADMAP.md`. -- **Biometric-processor 79 CVE triage.** Separate workstream; independent of client-apps 20/20 push. -- **Pre-existing `BiometricViewModelTest.enrollFace` failure.** Known red test on `client-apps`; does not block 20/20 or v5.2.0 tag. Tracked under Phase D of `client-apps/docs/TODO.md`. - -## Cross-references - -- [`docs/plans/CLIENT_APPS_PARITY.md`](./CLIENT_APPS_PARITY.md) — feature matrix; Phase 2 (Desktop Win+Linux) roadmap. iOS dropped 2026-04-26. -- [`docs/plans/NFC_PUSH_APPROVAL_PROTOCOL.md`](./NFC_PUSH_APPROVAL_PROTOCOL.md) — cross-device NFC handoff spec; `fivucsas://nfc-session` deep link, Ed25519 device registration, FCM/APNS push payload, V39 migration sketch, 13-threat security review. diff --git a/plans/PRODUCTION_HARDENING_PLAN.md b/plans/PRODUCTION_HARDENING_PLAN.md deleted file mode 100644 index f59cdda..0000000 --- a/plans/PRODUCTION_HARDENING_PLAN.md +++ /dev/null @@ -1,956 +0,0 @@ -# Production Hardening Plan - -**Version:** 1.0 -**Date:** 2026-04-05 -**Status:** Design Document (Pre-Implementation) -**Author:** Ahmet Abdullah Gultekin -**Project:** FIVUCSAS - Face and Identity Verification Using Cloud-Based SaaS -**Organization:** Marmara University - Computer Engineering Department - ---- - -## Table of Contents - -1. [Executive Summary](#1-executive-summary) -2. [Current Production State](#2-current-production-state) -3. [Penetration Testing](#3-penetration-testing) -4. [Performance Benchmarks and SLAs](#4-performance-benchmarks-and-slas) -5. [Disaster Recovery Plan](#5-disaster-recovery-plan) -6. [Monitoring and Alerting](#6-monitoring-and-alerting) -7. [Backup Verification](#7-backup-verification) -8. [Zero-Downtime Deployment](#8-zero-downtime-deployment) -9. [SSL and Certificate Management](#9-ssl-and-certificate-management) -10. [Database Maintenance](#10-database-maintenance) -11. [Log Aggregation](#11-log-aggregation) -12. [Incident Response Playbook](#12-incident-response-playbook) -13. [Implementation Phases](#13-implementation-phases) -14. [Risk Assessment](#14-risk-assessment) -15. [Dependencies and Prerequisites](#15-dependencies-and-prerequisites) - ---- - -## 1. Executive Summary - -FIVUCSAS is running in production on a Hetzner CX43 (8 CPU, 16 GB RAM, 150 GB disk) with 16 healthy containers serving real traffic. The platform has passed a security audit (9 critical + 34 high findings fixed, documented in AUDIT-2026-03-31.md), has 304 unit tests + 28 Playwright E2E tests + 103 API tests, and operates with automated daily backups. However, the system lacks formal SLAs, automated backup verification, zero-downtime deployment, centralized log aggregation, and a structured incident response process. This document defines the complete production hardening checklist to bring FIVUCSAS from "works in production" to "enterprise-ready production" with quantified uptime targets, tested disaster recovery, and operational runbooks. - ---- - -## 2. Current Production State - -### Infrastructure Overview - -``` -+------------------------------------------------------------------+ -| Hetzner CX43 — Nuremberg, Germany | -| 8 vCPU | 16 GB RAM | 150 GB NVMe | Ubuntu 24.04 | -+------------------------------------------------------------------+ -| | -| Traefik v3.6.12 (reverse proxy, SSL termination) | -| | | -| +-- api.fivucsas.com -> identity-core-api:8080 | -| +-- bio.fivucsas.com -> biometric-api:8001| -| +-- mizan.fivucsas.com -> mizan:3000 | -| +-- sarnic.fivucsas.com -> sarnic:3001 | -| +-- muhabbet.fivucsas.com -> muhabbet:5000 | -| | -| shared-postgres (PostgreSQL 17 + pgvector) | -| shared-redis (Redis 7.4) | -| identity-core-api (Spring Boot 3.4.7, Java 21) | -| biometric-api (FastAPI, Python 3.12, 4 GB RAM) | -| + Mizan, Sarnic, Muhabbet, Share-Agent, VPN containers | -| | -| Disk: ~36% used | RAM: ~36% used | Backups: daily at 03:00 | -+------------------------------------------------------------------+ -``` - -### What Is Already Done - -| Area | Status | Details | -|------|--------|---------| -| SSH hardening | Done | Key-only, fail2ban, IP whitelist | -| Docker security | Done | no-new-privileges, read_only, non-root | -| Firewall | Done | UFW: 22/80/443 only | -| SSL/TLS | Done | Let's Encrypt via Traefik, auto-renewal | -| Rate limiting | Done | Spring Boot + Traefik rate limits | -| Security audit | Done | Semgrep, Trivy, Hadolint, ShellCheck | -| Daily backups | Done | 4 databases, compressed, 7-day retention | -| VPN | Done | WireGuard (wg-easy) for admin access | -| Monitoring | Partial | Prometheus + Grafana deployed | -| CI/CD | Done | GitHub Actions, self-hosted runner | - -### What Is Missing - -| Area | Status | Priority | -|------|--------|----------| -| Penetration test | Not done | P0 | -| Formal SLAs | Not defined | P0 | -| Backup restore testing | Not automated | P0 | -| Zero-downtime deploy | Not implemented | P1 | -| Centralized logging | Not implemented | P1 | -| Alerting rules | Not configured | P1 | -| Incident response playbook | Not written | P1 | -| Database maintenance schedule | Ad-hoc | P2 | -| Chaos testing | Not done | P2 | - ---- - -## 3. Penetration Testing - -### Scope Definition - -``` -+------------------------------------------------------------------+ -| PENTEST SCOPE | -+------------------------------------------------------------------+ -| | -| IN SCOPE: | -| +------------------+ +------------------+ +------------------+ | -| | Web Dashboard | | Identity Core | | Biometric | | -| | (React SPA) | | API (132 endpts) | | Processor (46+) | | -| +------------------+ +------------------+ +------------------+ | -| +------------------+ +------------------+ +------------------+ | -| | Auth Widget | | OAuth 2.0 Flow | | WebAuthn Flow | | -| +------------------+ +------------------+ +------------------+ | -| +------------------+ +------------------+ | -| | Android APK | | Network (SSH, | | -| | (decompile test) | | Traefik, ports) | | -| +------------------+ +------------------+ | -| | -| OUT OF SCOPE: | -| - Hetzner hypervisor/host OS | -| - Hostinger shared hosting infrastructure | -| - Third-party services (Stripe, GitHub) | -| - Physical security | -+------------------------------------------------------------------+ -``` - -### Test Categories - -| Category | Tests | Tools | Focus | -|----------|-------|-------|-------| -| Authentication | 15 | Burp Suite, custom scripts | JWT manipulation, session hijack, brute force | -| Authorization | 12 | Burp Suite | RBAC bypass, tenant isolation, IDOR | -| Injection | 10 | sqlmap, custom payloads | SQL injection, XSS, command injection | -| Biometric-specific | 8 | Custom scripts | Replay attacks, embedding poisoning, spoofing | -| API security | 10 | OWASP ZAP, Postman | Mass assignment, rate limit bypass, CORS | -| Infrastructure | 8 | nmap, nikto, testssl.sh | Port scan, TLS config, header analysis | -| Mobile | 5 | jadx, frida | APK decompile, certificate pinning, storage | -| Business logic | 7 | Manual | Enrollment bypass, verification flow skip | - -### Biometric-Specific Tests - -| Test | Attack Vector | Expected Defense | -|------|--------------|-----------------| -| Face replay (photo) | Show photo to camera | Passive liveness detection | -| Face replay (video) | Play video on screen | Active liveness (head turn, blink) | -| Voice replay | Play recorded audio | STT passphrase verification (W17) | -| Embedding injection | Submit crafted embedding via API | Server-side embedding extraction only | -| Template poisoning | Enroll with adversarial image | Quality gate rejects low-quality | -| Cross-tenant search | Query another tenant's gallery | RLS + tenant_id in every query | -| NFC chip cloning | Replayed APDU sequences | Challenge-response with random nonce | -| Rate limit bypass | Rotate IP/API key | Per-user + per-IP + global limits | - -### Methodology: OWASP Testing Guide v4.2 - -``` -Phase 1: Reconnaissance (1 day) - - Port scan, service fingerprinting - - Subdomain enumeration - - Technology stack identification - -Phase 2: Threat Modeling (0.5 day) - - STRIDE analysis per component - - Attack surface mapping - - Data flow diagrams with trust boundaries - -Phase 3: Vulnerability Assessment (3 days) - - Automated scanning (ZAP, Burp, sqlmap) - - Manual testing per category above - - Biometric-specific tests - -Phase 4: Exploitation (1 day) - - Attempt to exploit discovered vulnerabilities - - Chain vulnerabilities for impact amplification - - Document proof-of-concept for each finding - -Phase 5: Reporting (0.5 day) - - CVSS v3.1 scoring - - Remediation recommendations - - Executive summary for stakeholders -``` - ---- - -## 4. Performance Benchmarks and SLAs - -### Target SLAs - -| Metric | Free Tier | Developer | Enterprise | -|--------|----------|-----------|------------| -| Uptime | 99.0% | 99.5% | 99.9% | -| API latency (P50) | <500ms | <300ms | <200ms | -| API latency (P95) | <2000ms | <1000ms | <500ms | -| Face verify latency | <2000ms | <1500ms | <1000ms | -| Voice verify latency | <1500ms | <1000ms | <800ms | -| Error rate | <5% | <1% | <0.1% | -| Data durability | 99.9% | 99.99% | 99.999% | - -### Uptime Budget - -| SLA | Annual Downtime | Monthly Downtime | Weekly Downtime | -|-----|----------------|-----------------|-----------------| -| 99.0% | 3.65 days | 7.3 hours | 1.68 hours | -| 99.5% | 1.83 days | 3.65 hours | 50 minutes | -| 99.9% | 8.76 hours | 43.8 minutes | 10 minutes | - -### Load Testing Plan - -``` -Tool: k6 (already in load-tests/) - -Scenario 1: Baseline (sustained) - - 50 concurrent users - - 60 minutes duration - - Mix: 40% face verify, 30% auth flow, 20% search, 10% enroll - - Target: P95 < 1000ms, error rate < 1% - -Scenario 2: Spike (burst) - - Ramp from 10 to 200 users in 30 seconds - - Hold for 5 minutes - - Ramp down to 10 in 30 seconds - - Target: No 5xx errors, P95 < 3000ms during spike - -Scenario 3: Endurance (soak) - - 30 concurrent users - - 24 hours - - Target: No memory leak, no connection pool exhaustion, stable latencies - -Scenario 4: Stress (breaking point) - - Ramp from 10 to 500 users over 30 minutes - - Find the breaking point (when error rate > 5%) - - Document max concurrent capacity -``` - -### Current Baseline (Estimated) - -| Metric | Current | Target | Gap | -|--------|---------|--------|-----| -| Max concurrent users | ~30 (untested) | 100 | Needs load test | -| Face verify P95 | ~1500ms | <1000ms | Client-side ML (Phase 4.2) | -| Voice verify P95 | ~800ms | <600ms | Thread pool tuning | -| Auth flow P95 | ~2000ms | <1000ms | Connection pooling | -| Memory stability (24h) | Unknown | <5% drift | Needs soak test | - ---- - -## 5. Disaster Recovery Plan - -### Recovery Objectives - -| Scenario | RTO (Recovery Time) | RPO (Data Loss) | Strategy | -|----------|-------------------|-----------------|----------| -| Container crash | <2 minutes | 0 | Docker restart policy: always | -| Database corruption | <30 minutes | <24 hours | Restore from daily backup | -| Server failure (hardware) | <2 hours | <24 hours | New CX43 + restore | -| Data center outage | <4 hours | <24 hours | Hetzner Falkenstein DC | -| Ransomware/compromise | <4 hours | <24 hours | Clean server + offsite backup | - -### Backup Architecture - -``` -+------------------+ +------------------+ +-------------------+ -| Daily Backup | --> | Local Storage | --> | Offsite Storage | -| (03:00 cron) | | (/opt/backups/) | | (Hetzner Storage | -| | | 7-day retention | | Box or S3) | -| Databases: | | | | 30-day retention | -| - identity_core | | ~50 MB/day | | | -| - biometric_db | | compressed | | Encrypted with | -| - muhabbet | | | | GPG (AES-256) | -| - sarnic | | | | | -+------------------+ +------------------+ +-------------------+ -``` - -### Disaster Recovery Runbook - -``` -SCENARIO: Complete Server Loss - -1. Provision new CX43 (Hetzner Cloud Console) - - Ubuntu 24.04, Nuremberg region - - Estimated time: 5 minutes - -2. Run server bootstrap script - $ curl -sL https://raw.githubusercontent.com/.../bootstrap.sh | bash - - Installs Docker, sets up deploy user, firewall, SSH keys - - Estimated time: 10 minutes - -3. Clone repositories - $ cd /opt/projects && git clone --recurse-submodules ... - - Estimated time: 5 minutes - -4. Restore .env.prod files (from secure backup) - - Decrypt GPG-encrypted env files - - Place in each project directory - - Estimated time: 5 minutes - -5. Download latest backup from offsite - $ ./scripts/restore-backup.sh --date latest - - Downloads and decompresses database dumps - - Estimated time: 10 minutes - -6. Start infrastructure - $ docker compose -f docker-compose.prod.yml --env-file .env.prod up -d - - PostgreSQL + Redis start first - - Estimated time: 5 minutes - -7. Restore databases - $ pg_restore -d identity_core /opt/backups/latest/identity_core.sql.gz - $ pg_restore -d biometric_db /opt/backups/latest/biometric_db.sql.gz - - Estimated time: 5 minutes - -8. Start application containers - $ ./infra/deploy.sh restart all - - Estimated time: 10 minutes - -9. Update DNS (if IP changed) - - Cloudflare: api.fivucsas.com -> new IP - - Estimated time: 2 minutes (instant propagation via Cloudflare) - -10. Verify all services - $ ./infra/deploy.sh status - $ curl https://api.fivucsas.com/ping - - Estimated time: 5 minutes - -TOTAL ESTIMATED RECOVERY TIME: ~62 minutes -``` - ---- - -## 6. Monitoring and Alerting - -### Monitoring Stack - -``` -+------------------------------------------------------------------+ -| MONITORING ARCHITECTURE | -+------------------------------------------------------------------+ -| | -| +------------------+ +------------------+ | -| | Prometheus | --> | Grafana | | -| | (metrics scrape) | | (dashboards) | | -| +------------------+ +--------+---------+ | -| | | | -| Scrape targets: Dashboards: | -| - /actuator/prometheus - System (CPU, RAM, disk, network) | -| - /metrics (biometric) - Application (request rate, latency) | -| - node_exporter - Database (connections, queries, size) | -| - cadvisor (containers) - Biometric (verify success rate, EER) | -| - Business (enrollments, verifications) | -| | -| +------------------+ +------------------+ | -| | Alertmanager | --> | Notification | | -| | (rules engine) | | Channels | | -| +------------------+ +------------------+ | -| | - Telegram bot | | -| | - Email | | -| | - PagerDuty | | -| +------------------+ | -+------------------------------------------------------------------+ -``` - -### Alert Rules - -| Alert | Condition | Severity | Action | -|-------|----------|----------|--------| -| ServiceDown | HTTP probe fails for >2 min | P0 / Critical | Telegram + email immediately | -| HighErrorRate | 5xx rate > 5% for 5 min | P0 / Critical | Telegram + email | -| HighLatency | P95 > 3s for 10 min | P1 / Warning | Telegram | -| DiskFull | Disk usage > 80% | P1 / Warning | Email | -| MemoryHigh | Container RAM > 90% for 5 min | P1 / Warning | Telegram | -| BackupFailed | Backup cron exit code != 0 | P1 / Warning | Email | -| CertExpiring | SSL cert expires in <14 days | P2 / Info | Email | -| DatabaseSlow | Query P95 > 1s for 10 min | P2 / Info | Email | -| VerifyFailRate | Face verify reject > 30% for 1h | P2 / Info | Email (may indicate model issue) | -| QuotaApproaching | Disk/RAM > 70% | P3 / Info | Weekly summary | - -### Prometheus Rules (prometheus/rules.yml) - -```yaml -groups: - - name: fivucsas_alerts - rules: - - alert: ServiceDown - expr: probe_success{job="blackbox"} == 0 - for: 2m - labels: - severity: critical - annotations: - summary: "{{ $labels.instance }} is down" - description: "HTTP probe has been failing for more than 2 minutes" - - - alert: HighErrorRate - expr: | - sum(rate(http_server_requests_seconds_count{status=~"5.."}[5m])) - / sum(rate(http_server_requests_seconds_count[5m])) > 0.05 - for: 5m - labels: - severity: critical - annotations: - summary: "Error rate above 5%" - - - alert: HighMemory - expr: container_memory_usage_bytes / container_spec_memory_limit_bytes > 0.9 - for: 5m - labels: - severity: warning - annotations: - summary: "{{ $labels.name }} memory above 90%" -``` - ---- - -## 7. Backup Verification - -### Automated Restore Testing - -``` -Schedule: Weekly (Sunday 06:00, after Saturday backup) - -+------------------+ +------------------+ +------------------+ -| Download Latest | --> | Spin Up Temp | --> | Restore Into | -| Backup Files | | PostgreSQL | | Temp Instance | -| | | (Docker, port | | | -| | | 15432) | | | -+------------------+ +------------------+ +------------------+ - | - v - +------------------+ - | Validate: | - | - Row counts | - | - Key tables | - | - pgvector ops | - | - Sample queries | - +------------------+ - | - v - +------------------+ - | Report + Cleanup | - | - Email result | - | - Remove temp DB | - +------------------+ -``` - -### Validation Queries - -```sql --- Table existence -SELECT count(*) FROM information_schema.tables -WHERE table_schema = 'public'; - --- Row counts for critical tables -SELECT 'users' as tbl, count(*) FROM users -UNION ALL SELECT 'tenants', count(*) FROM tenants -UNION ALL SELECT 'face_embeddings', count(*) FROM face_embeddings -UNION ALL SELECT 'voice_enrollments', count(*) FROM voice_enrollments -UNION ALL SELECT 'audit_logs', count(*) FROM audit_logs; - --- pgvector functionality -SELECT embedding <=> embedding AS self_distance -FROM face_embeddings LIMIT 1; --- Expected: 0.0 (vector compared to itself) - --- Recent data (not stale) -SELECT max(created_at) FROM audit_logs; --- Expected: within 24 hours -``` - ---- - -## 8. Zero-Downtime Deployment - -### Current Deployment (Downtime: 30-60 seconds) - -``` -1. docker compose build (image rebuild) -2. docker compose up -d (container replacement) - ^^ ~30-60s of downtime while container restarts -``` - -### Target: Rolling Update Strategy - -``` -+------------------+ +------------------+ +------------------+ -| Build New Image | --> | Health Check | --> | Swap Traffic | -| (no downtime) | | New Container | | (Traefik dynamic)| -+------------------+ | (on temp port) | +------------------+ - +------------------+ | - v - +------------------+ - | Stop Old | - | Container | - | (graceful drain) | - +------------------+ -``` - -### Implementation with Docker Compose + Traefik - -```yaml -# docker-compose.prod.yml (zero-downtime config) -services: - identity-core-api: - deploy: - update_config: - parallelism: 1 - delay: 10s - order: start-first # Start new before stopping old - rollback_config: - parallelism: 1 - delay: 10s - healthcheck: - test: ["CMD", "curl", "-f", "http://localhost:8080/ping"] - interval: 10s - timeout: 5s - retries: 3 - start_period: 30s - labels: - - "traefik.http.services.identity.loadbalancer.healthcheck.path=/ping" - - "traefik.http.services.identity.loadbalancer.healthcheck.interval=5s" -``` - -### Deployment Script (deploy-zero-downtime.sh) - -```bash -#!/bin/bash -SERVICE=$1 - -# 1. Build new image -docker compose -f docker-compose.prod.yml --env-file .env.prod build $SERVICE - -# 2. Scale up (start new alongside old) -docker compose -f docker-compose.prod.yml --env-file .env.prod up -d --scale $SERVICE=2 --no-recreate - -# 3. Wait for new container health check -echo "Waiting for new container to be healthy..." -sleep 30 - -# 4. Remove old container -OLD_CONTAINER=$(docker ps --filter "name=$SERVICE" --format '{{.ID}}' | tail -1) -docker stop --time 30 $OLD_CONTAINER - -# 5. Scale back to 1 -docker compose -f docker-compose.prod.yml --env-file .env.prod up -d --scale $SERVICE=1 -``` - ---- - -## 9. SSL and Certificate Management - -### Current Setup - -- Traefik ACME (Let's Encrypt) with automatic renewal -- Certificates stored in `acme.json` (Traefik volume) -- Auto-renewal 30 days before expiry - -### Hardening - -| Task | Current | Target | -|------|---------|--------| -| TLS version | 1.2 + 1.3 | 1.3 only (for new clients) | -| Cipher suites | Traefik defaults | ECDHE+AESGCM only | -| HSTS | Enabled | max-age=63072000, includeSubDomains, preload | -| OCSP stapling | Not configured | Enable in Traefik | -| Certificate monitoring | None | Alert 14 days before expiry | -| CAA record | Not set | Add `0 issue "letsencrypt.org"` DNS record | - -### Traefik TLS Configuration - -```yaml -# traefik/dynamic/tls.yml -tls: - options: - default: - minVersion: VersionTLS12 - cipherSuites: - - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 - - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 - - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 - sniStrict: true - modern: - minVersion: VersionTLS13 -``` - ---- - -## 10. Database Maintenance - -### Scheduled Maintenance Tasks - -| Task | Frequency | Command | Purpose | -|------|-----------|---------|---------| -| VACUUM ANALYZE | Daily (04:00) | `vacuumdb --analyze --all` | Reclaim space, update statistics | -| REINDEX | Weekly (Sunday 05:00) | `reindex database identity_core` | Rebuild bloated indexes | -| pg_stat_reset | Monthly | `SELECT pg_stat_reset()` | Reset statistics counters | -| Table bloat check | Weekly | Custom query | Identify tables needing VACUUM FULL | -| Index usage check | Monthly | `pg_stat_user_indexes` | Drop unused indexes | -| Connection check | Hourly | `pg_stat_activity` | Identify long-running queries | -| pgvector HNSW rebuild | Monthly | `REINDEX INDEX idx_face_hnsw` | Maintain search quality | - -### Maintenance Script - -```bash -#!/bin/bash -# /opt/scripts/db-maintenance.sh -# Run via cron: 0 4 * * * /opt/scripts/db-maintenance.sh - -DATABASES="identity_core biometric_db muhabbet sarnic" -PG_CONTAINER="shared-postgres" - -for DB in $DATABASES; do - echo "[$(date)] VACUUM ANALYZE on $DB" - docker exec $PG_CONTAINER psql -U postgres -d $DB -c "VACUUM ANALYZE;" - - echo "[$(date)] Check table bloat on $DB" - docker exec $PG_CONTAINER psql -U postgres -d $DB -c " - SELECT schemaname, tablename, - pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) as total_size, - n_dead_tup, - n_live_tup, - CASE WHEN n_live_tup > 0 - THEN round(n_dead_tup::numeric / n_live_tup * 100, 2) - ELSE 0 - END as dead_pct - FROM pg_stat_user_tables - WHERE n_dead_tup > 1000 - ORDER BY n_dead_tup DESC; - " -done - -# Weekly: REINDEX (only on Sundays) -if [ "$(date +%u)" = "7" ]; then - for DB in $DATABASES; do - echo "[$(date)] REINDEX on $DB" - docker exec $PG_CONTAINER reindexdb -d $DB - done -fi -``` - -### pgvector-Specific Maintenance - -```sql --- Check HNSW index health -SELECT indexname, pg_size_pretty(pg_relation_size(indexname::regclass)) as size -FROM pg_indexes -WHERE indexdef LIKE '%hnsw%'; - --- Rebuild if search recall drops below 95% -REINDEX INDEX CONCURRENTLY idx_face_embeddings_hnsw; -REINDEX INDEX CONCURRENTLY idx_voice_enrollments_hnsw; -``` - ---- - -## 11. Log Aggregation - -### Current State - -- Each container logs to Docker (stdout/stderr) -- `docker logs ` for individual access -- No centralized search or retention policy - -### Target Architecture - -``` -+------------------------------------------------------------------+ -| Containers (stdout/stderr) | -| identity-core-api | biometric-api | shared-postgres | traefik | -+--------+--------------------+--------------------+---------------+ - | | | - v v v -+------------------------------------------------------------------+ -| Promtail (log collector, Docker plugin) | -| - Reads container logs via Docker socket | -| - Adds labels: container_name, service, level | -| - Parses JSON logs (Spring Boot), plain text (Python) | -+------------------------------------------------------------------+ - | - v -+------------------------------------------------------------------+ -| Loki (log storage) | -| - Stores compressed log chunks | -| - S3-compatible backend (Hetzner Storage Box) | -| - 30-day retention | -| - Label-based indexing (not full-text) | -+------------------------------------------------------------------+ - | - v -+------------------------------------------------------------------+ -| Grafana (visualization) | -| - Log Explorer: search by container, level, time range | -| - Dashboard: error rate trends, slow query logs | -| - Alerts: trigger on log patterns (ERROR, CRITICAL) | -+------------------------------------------------------------------+ -``` - -### Resource Estimate - -| Component | RAM | Disk | CPU | -|-----------|-----|------|-----| -| Promtail | 50 MB | Minimal | Minimal | -| Loki | 256 MB | ~1 GB/month (compressed) | Low | -| **Total** | ~300 MB | ~1 GB/month | Minimal | - -### Log Format Standardization - -```json -// identity-core-api (Spring Boot structured logging) -{ - "timestamp": "2026-04-05T12:00:00.000Z", - "level": "INFO", - "logger": "c.f.a.s.AuthenticateUserService", - "message": "User authenticated successfully", - "tenant_id": "abc-123", - "user_id": "def-456", - "method": "FACE", - "duration_ms": 1250, - "trace_id": "xyz-789" -} - -// biometric-api (Python structured logging) -{ - "timestamp": "2026-04-05T12:00:00.000Z", - "level": "INFO", - "module": "face_verify", - "message": "Face verification complete", - "similarity": 0.92, - "threshold": 0.75, - "duration_ms": 890, - "trace_id": "xyz-789" -} -``` - ---- - -## 12. Incident Response Playbook - -### Severity Levels - -| Level | Definition | Response Time | Example | -|-------|-----------|---------------|---------| -| P0 / Critical | Service completely down or data breach | 15 min | All APIs returning 5xx | -| P1 / Major | Significant degradation | 1 hour | Face verify latency >5s | -| P2 / Minor | Non-critical issue | 4 hours | Grafana dashboard down | -| P3 / Low | Cosmetic or improvement | Next business day | Log format inconsistency | - -### Incident Response Flow - -``` -+------------------+ -| Alert Triggered | -| (Prometheus/ | -| manual report) | -+--------+---------+ - | - v -+------------------+ +------------------+ -| Acknowledge | --> | Assess Severity | -| (Telegram reply) | | (P0/P1/P2/P3) | -+------------------+ +--------+---------+ - | - +-------------+-------------+ - | | - P0/P1 P2/P3 - | | - v v - +------------------+ +------------------+ - | Mitigate | | Schedule Fix | - | (restart, scale, | | (next session) | - | failover) | | | - +--------+---------+ +------------------+ - | - v - +------------------+ - | Root Cause | - | Analysis | - | (within 24h) | - +--------+---------+ - | - v - +------------------+ - | Post-Mortem | - | (document, | - | prevent | - | recurrence) | - +------------------+ -``` - -### Common Incident Runbooks - -#### Runbook: Container OOMKilled - -``` -Symptom: Container exits with code 137 -Diagnosis: - $ docker inspect | grep OOMKilled - $ docker stats --no-stream -Fix: - 1. Check for memory leak: docker logs | grep -i "memory\|heap" - 2. Increase memory limit in docker-compose.prod.yml - 3. Restart: docker compose up -d - 4. If biometric-api: check model loading (DeepFace, Resemblyzer, Whisper) -Prevention: - - Set memory alerts at 80% threshold - - Monthly memory profiling -``` - -#### Runbook: Database Connection Exhaustion - -``` -Symptom: "too many connections" in logs -Diagnosis: - $ docker exec shared-postgres psql -U postgres -c "SELECT count(*) FROM pg_stat_activity;" - $ docker exec shared-postgres psql -U postgres -c "SELECT usename, state, count(*) FROM pg_stat_activity GROUP BY usename, state;" -Fix: - 1. Kill idle connections: SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE state = 'idle' AND query_start < now() - interval '10 minutes'; - 2. Restart affected application container - 3. Check HikariCP pool config (max_pool_size) -Prevention: - - Set max_connections = 200 in postgresql.conf - - HikariCP pool per service: max 20 - - Connection leak detection: leakDetectionThreshold = 30000 -``` - -#### Runbook: SSL Certificate Failure - -``` -Symptom: Browser shows "NET::ERR_CERT_DATE_INVALID" -Diagnosis: - $ docker exec traefik cat /acme.json | jq '.[] | .Certificates[].domain' - $ echo | openssl s_client -connect api.fivucsas.com:443 2>/dev/null | openssl x509 -noout -dates -Fix: - 1. Force Traefik certificate renewal: - $ docker exec traefik rm /acme.json - $ docker restart traefik - 2. Wait 2 minutes for Let's Encrypt issuance - 3. Verify: curl -vI https://api.fivucsas.com -Prevention: - - Alertmanager: cert expiry < 14 days - - Traefik auto-renewal (should handle this) -``` - ---- - -## 13. Implementation Phases - -### Phase 1 — Monitoring and Alerting (2 weeks) - -| Task | Effort | Details | -|------|--------|---------| -| Prometheus alert rules | 2 days | 10 rules as defined above | -| Alertmanager + Telegram bot | 1 day | Notification channel setup | -| Grafana dashboards (4) | 3 days | System, Application, Database, Biometric | -| Loki + Promtail deployment | 2 days | Log aggregation with 30-day retention | -| Log format standardization | 2 days | JSON structured logging in both services | - -### Phase 2 — Backup and Recovery (1 week) - -| Task | Effort | Details | -|------|--------|---------| -| Offsite backup to Hetzner Storage Box | 1 day | GPG-encrypted, rsync | -| Automated restore test script | 2 days | Weekly cron, temp PostgreSQL, validation queries | -| Disaster recovery runbook | 1 day | Document full rebuild procedure | -| DR drill (test full restore) | 1 day | Execute runbook end-to-end | - -### Phase 3 — Zero-Downtime Deploy (1 week) - -| Task | Effort | Details | -|------|--------|---------| -| /ping endpoint on all services | 0.5 day | Already on identity-core-api; add to biometric-api | -| Docker Compose health checks | 1 day | Proper start_period, interval, retries | -| deploy-zero-downtime.sh script | 1.5 days | Scale up -> health check -> swap -> scale down | -| Traefik health check integration | 1 day | Dynamic routing based on container health | -| Rollback script | 1 day | Revert to previous image tag | - -### Phase 4 — Database Maintenance (0.5 week) - -| Task | Effort | Details | -|------|--------|---------| -| db-maintenance.sh script | 1 day | VACUUM, REINDEX, bloat check | -| Cron schedule | 0.5 day | Daily VACUUM, weekly REINDEX | -| pgvector HNSW monitoring | 0.5 day | Recall quality check query | -| Connection pool tuning | 0.5 day | HikariCP per-service optimization | - -### Phase 5 — Penetration Test (1 week) - -| Task | Effort | Details | -|------|--------|---------| -| Scope and threat model | 1 day | As defined in Section 3 | -| Automated scanning | 1 day | OWASP ZAP, sqlmap, testssl.sh | -| Manual testing | 2 days | Auth, RBAC, biometric-specific | -| Remediation | 1 day | Fix critical/high findings | -| Report | 0.5 day | CVSS scoring, executive summary | - -### Phase 6 — Incident Response (0.5 week) - -| Task | Effort | Details | -|------|--------|---------| -| Incident response playbook | 1 day | Severity levels, runbooks, escalation | -| On-call rotation setup | 0.5 day | Telegram alerting, acknowledgment flow | -| Post-mortem template | 0.5 day | Standardized format for RCA | -| Chaos test (kill random container) | 0.5 day | Verify auto-restart + alerts fire | - -### Total Effort: ~6 weeks - -``` -Week 1-2: Phase 1 (Monitoring, alerting, log aggregation) -Week 3: Phase 2 (Backup verification, DR drill) -Week 4: Phase 3 (Zero-downtime deployment) -Week 4.5: Phase 4 (Database maintenance automation) -Week 5: Phase 5 (Penetration testing) -Week 5.5: Phase 6 (Incident response setup) -Week 6: Buffer + chaos testing + documentation polish -``` - ---- - -## 14. Risk Assessment - -| Risk | Probability | Impact | Mitigation | -|------|------------|--------|------------| -| Pentest reveals critical vulnerability | Medium | Critical | Fix before any public BaaS launch; allocate 1 week buffer | -| Loki consumes too much disk | Medium | Low | 30-day retention policy; compress + offsite | -| Zero-downtime deploy fails (race condition) | Low | Medium | Test thoroughly in staging; keep manual deploy as fallback | -| DR drill takes longer than 2 hours | Medium | Medium | Pre-build server snapshot; keep bootstrap script tested | -| Alert fatigue (too many false positives) | High | Medium | Tune thresholds iteratively; start with P0 alerts only | -| Database maintenance causes performance dip | Low | Low | Schedule during lowest-traffic window (03:00-05:00) | -| Monitoring stack itself goes down | Low | Medium | Prometheus/Grafana health checks; separate from app stack | - ---- - -## 15. Dependencies and Prerequisites - -### Technical Prerequisites - -| Prerequisite | Status | Notes | -|-------------|--------|-------| -| Prometheus | Deployed | Needs alert rules configuration | -| Grafana | Deployed | Needs dashboards creation | -| Alertmanager | Not deployed | Install as Docker container | -| Loki | Not deployed | Install as Docker container | -| Promtail | Not deployed | Install as Docker sidecar | -| /ping endpoint | Partial | identity-core-api has it; biometric-api needs it | -| Hetzner Storage Box | Not provisioned | For offsite backup storage | -| Telegram bot | Not created | For alert notifications | - -### Cost Estimate - -| Item | Monthly Cost | Notes | -|------|-------------|-------| -| Hetzner Storage Box (100 GB) | ~3.50 EUR | Offsite backups | -| Telegram bot | Free | Unlimited messages | -| Loki/Promtail | Free (self-hosted) | ~300 MB RAM | -| Alertmanager | Free (self-hosted) | ~50 MB RAM | -| **Total** | **~3.50 EUR/month** | | - ---- - -*Production hardening is not a one-time event but a continuous process. This document should be reviewed quarterly, and the incident response playbook should be tested with a chaos engineering drill at least twice per year. The penetration test should be repeated annually or after any major feature release (especially BYOD and BaaS).* diff --git a/plans/SMS_ACTIVATION_PLAN.md b/plans/SMS_ACTIVATION_PLAN.md deleted file mode 100644 index c57e399..0000000 --- a/plans/SMS_ACTIVATION_PLAN.md +++ /dev/null @@ -1,547 +0,0 @@ -# SMS OTP Activation Plan — Twilio Integration - -**Project**: FIVUCSAS Identity Core API -**Date**: 2026-04-05 -**Status**: Infrastructure built, awaiting Twilio credentials -**Author**: Ahmet Abdullah Gultekin - ---- - -## Table of Contents - -1. [Architecture Overview](#1-architecture-overview) -2. [Current State](#2-current-state) -3. [Activation Steps](#3-activation-steps) -4. [Alternative: Twilio Verify API](#4-alternative-twilio-verify-api) -5. [Future: Firebase Phone Auth](#5-future-firebase-phone-auth) -6. [Testing Plan](#6-testing-plan) -7. [Cost Estimation](#7-cost-estimation) - ---- - -## 1. Architecture Overview - -SMS OTP follows the project's hexagonal architecture (Ports and Adapters). The application -layer never touches Twilio directly — it depends only on the `SmsService` output port. - -``` - FIVUCSAS Identity Core API - ┌──────────────────────────────────────────────────────────────┐ - │ │ - │ ┌─────────────────────────────────────────────────────┐ │ - │ │ APPLICATION LAYER │ │ - │ │ │ │ - │ │ OtpController ──> OtpService (Redis) │ │ - │ │ │ │ │ │ - │ │ │ generate / validate │ │ - │ │ │ │ │ │ - │ │ SmsOtpAuthHandler ─────┘ │ │ - │ │ │ │ │ - │ │ │ depends on │ │ - │ │ ▼ │ │ - │ │ ┌─────────────┐ │ │ - │ │ │ SmsService │ ◄── OUTPUT PORT (interface) │ │ - │ │ └──────┬──────┘ │ │ - │ └──────────┼──────────────────────────────────────────┘ │ - │ │ │ - │ ┌──────────┼──────────────────────────────────────────┐ │ - │ │ │ INFRASTRUCTURE LAYER │ │ - │ │ │ │ │ - │ │ ┌─────┴──────────────┐ ┌─────────────────────┐ │ │ - │ │ │ TwilioSmsService │ │ NoOpSmsService │ │ │ - │ │ │ (ADAPTER) │ │ (ADAPTER) │ │ │ - │ │ │ │ │ │ │ │ - │ │ │ sms.enabled=true │ │ sms.enabled=false │ │ │ - │ │ │ Sends real SMS │ │ Logs OTP to stdout │ │ │ - │ │ └────────┬───────────┘ └─────────────────────┘ │ │ - │ │ │ │ │ - │ └─────────────┼────────────────────────────────────────┘ │ - │ │ │ - └─────────────────┼──────────────────────────────────────────────┘ - │ - ▼ - ┌──────────────┐ - │ Twilio API │ (external service) - │ REST / SDK │ - └──────────────┘ -``` - -### Key Design Decisions - -- **SmsService** is the output port (interface). The application layer only knows this contract. -- **TwilioSmsService** is the concrete adapter, activated via `@ConditionalOnProperty(name = "sms.enabled", havingValue = "true")`. -- **NoOpSmsService** is the fallback adapter, active when `sms.enabled=false` (or missing). Logs OTP codes to stdout for development. -- **OtpService** handles code generation, storage (Redis with 5-minute TTL), and validation. It is transport-agnostic — the same service is used for email OTP and SMS OTP. -- Swapping Twilio for another SMS provider requires only a new adapter implementing `SmsService`. Zero changes to application or domain layers. - ---- - -## 2. Current State - -Everything is built. The only missing piece is **Twilio account credentials**. - -### Files and Their Roles - -| File | Layer | Role | -|------|-------|------| -| `infrastructure/sms/SmsService.java` | Output Port | Interface: `void sendOtp(String phoneNumber, String code)` | -| `infrastructure/sms/TwilioSmsService.java` | Adapter | Real Twilio SDK integration (Twilio Java SDK 10.1.0) | -| `infrastructure/sms/NoOpSmsService.java` | Adapter | Dev/test fallback, logs OTP to console | -| `infrastructure/otp/OtpService.java` | Service | 6-digit code generation, Redis storage, 5-min TTL, validate-and-consume | -| `application/service/handler/SmsOtpAuthHandler.java` | App Service | Multi-step auth handler for SMS_OTP method type | -| `controller/OtpController.java` | Input Adapter | REST endpoints: `POST /api/v1/otp/sms/send/{userId}`, `POST /api/v1/otp/sms/verify/{userId}` | -| `resources/application.yml` | Config | `sms.enabled`, `sms.twilio.account-sid`, `sms.twilio.auth-token`, `sms.twilio.from-number` | -| `pom.xml` | Build | `com.twilio.sdk:twilio:10.1.0` dependency | -| `scripts/setup-twilio.sh` | DevOps | Interactive script: writes credentials to `.env.prod`, restarts container | -| `test/.../SmsOtpAuthHandlerTest.java` | Test | 7 unit tests for SmsOtpAuthHandler (send, verify, edge cases) | -| `test/.../TwilioSmsServiceTest.java` | Test | 2 unit tests for NoOpSmsService configuration | -| `resources/db/migration/V16__auth_flow_system.sql` | DB | SMS_OTP registered as auth method type, seeded in auth_methods table | - -### Current Behavior (sms.enabled=false) - -1. User triggers SMS OTP via auth flow or `/api/v1/otp/sms/send/{userId}`. -2. OtpService generates a 6-digit code and stores it in Redis with 5-minute TTL. -3. NoOpSmsService receives the code and **logs it to stdout** (no SMS sent). -4. In production logs: `SMS disabled - OTP for +905551234567: 482901`. -5. Verification works normally via `/api/v1/otp/sms/verify/{userId}` against Redis. - ---- - -## 3. Activation Steps - -### 3.1 GitHub Student Developer Pack - -1. Go to https://education.github.com/pack -2. Verify student status (Marmara University email or student ID). -3. Once approved, navigate to **Twilio** in the partner list. -4. Click "Get access" to claim **$50 USD in Twilio credit**. - -### 3.2 Twilio Account Setup - -1. Sign up at https://www.twilio.com/try-twilio (use the GitHub Student Pack link for credit). -2. Verify your personal phone number (Twilio requires this for trial accounts). -3. From the **Twilio Console Dashboard** (https://console.twilio.com), note: - - **Account SID** (starts with `AC`) - - **Auth Token** (click "Show" to reveal) - -### 3.3 Get a Twilio Phone Number - -1. In Twilio Console, go to **Phone Numbers > Manage > Buy a Number**. -2. Select a number with **SMS capability** (US numbers are cheapest at $1.00/month). -3. For Turkey-originating messages, a US number works but the sender will show as a US number. -4. Note the number in **E.164 format**: `+1XXXXXXXXXX`. - -> **Important**: Trial accounts can only send SMS to **verified phone numbers**. Add your -> test numbers at Console > Verified Caller IDs before testing. After upgrading to a paid -> account (or applying the $50 credit), this restriction is lifted. - -### 3.4 Configure the Server - -**Option A: Run the setup script (recommended)** - -```bash -ssh deploy@116.203.222.213 -cd /opt/projects/fivucsas -./scripts/setup-twilio.sh -``` - -The script will prompt for Account SID, Auth Token, and From Number, then write them to -`identity-core-api/.env.prod` and restart the container. - -**Option B: Manual configuration** - -Add these lines to `/opt/projects/fivucsas/identity-core-api/.env.prod`: - -```env -# Twilio SMS OTP -SMS_ENABLED=true -TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx -TWILIO_AUTH_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx -TWILIO_FROM_NUMBER=+1XXXXXXXXXX -``` - -Then rebuild and restart: - -```bash -cd /opt/projects/fivucsas/identity-core-api -docker compose -f docker-compose.prod.yml --env-file .env.prod up -d identity-core-api -``` - -### 3.5 Verify Activation - -Check the container logs for the initialization message: - -```bash -docker logs identity-core-api --tail 20 | grep -i twilio -# Expected: "Twilio SMS service initialized with from-number: +1XXXXXXXXXX" -``` - -If you see `NoOpSmsService` in the logs instead, `SMS_ENABLED` is not reaching the container. -Verify with: - -```bash -docker exec identity-core-api env | grep SMS -docker exec identity-core-api env | grep TWILIO -``` - ---- - -## 4. Alternative: Twilio Verify API - -The current implementation uses the **Programmable Messaging API** (raw SMS). Twilio offers a -higher-level **Verify API** that handles OTP generation, delivery, rate limiting, retry logic, -and fraud detection out of the box. - -### Why Upgrade - -| Feature | Current (raw SMS) | Twilio Verify API | -|---------|-------------------|-------------------| -| OTP generation | Our OtpService (Redis) | Twilio-managed | -| Rate limiting | None (must build) | Built-in (5 attempts/10 min) | -| Retry on failure | None | Automatic fallback channels | -| Fraud detection | None | Twilio Fraud Guard | -| Delivery receipts | Not checked | Built-in status callbacks | -| Pricing | $0.0079/SMS segment | $0.05/verification (includes SMS cost) | -| International | Varies by country | Managed by Twilio | - -### Recommendation - -For a university project with low volume, the **current raw SMS approach is sufficient**. -However, if this were a production SaaS, upgrading to Verify API is strongly recommended for -the rate limiting and fraud detection alone. - -### Code Changes for Twilio Verify API - -Only the infrastructure adapter needs to change. The port stays the same. - -**New adapter: `TwilioVerifySmsService.java`** - -```java -package com.fivucsas.identity.infrastructure.sms; - -import com.twilio.Twilio; -import com.twilio.rest.verify.v2.service.Verification; -import com.twilio.rest.verify.v2.service.VerificationCheck; -import jakarta.annotation.PostConstruct; -import lombok.extern.slf4j.Slf4j; -import org.springframework.beans.factory.annotation.Value; -import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; -import org.springframework.stereotype.Service; - -/** - * Twilio Verify API adapter. - * Uses Twilio's managed OTP generation and delivery. - * - * Activate with: sms.provider=verify (vs sms.provider=raw for TwilioSmsService). - * - * NOTE: When using Verify API, OTP generation is handled by Twilio, not our OtpService. - * The SmsService interface would need to be extended with a verify() method, - * or a new VerifySmsService port should be created. - */ -@Service -@ConditionalOnProperty(name = "sms.provider", havingValue = "verify") -@Slf4j -public class TwilioVerifySmsService implements SmsService { - - @Value("${sms.twilio.account-sid}") - private String accountSid; - - @Value("${sms.twilio.auth-token}") - private String authToken; - - @Value("${sms.twilio.verify-service-sid}") - private String verifyServiceSid; - - @PostConstruct - void init() { - Twilio.init(accountSid, authToken); - log.info("Twilio Verify service initialized (SID: {})", verifyServiceSid); - } - - @Override - public void sendOtp(String phoneNumber, String code) { - // NOTE: The 'code' parameter is ignored — Twilio Verify generates its own OTP. - // This is a design trade-off to keep the SmsService interface unchanged. - try { - Verification verification = Verification.creator( - verifyServiceSid, - phoneNumber, - "sms" - ).create(); - - log.info("Twilio Verify sent to {} - SID: {}, status: {}", - phoneNumber, verification.getSid(), verification.getStatus()); - } catch (Exception e) { - log.error("Twilio Verify failed for {}: {}", phoneNumber, e.getMessage()); - throw new RuntimeException("SMS verification delivery failed", e); - } - } - - /** - * Verify a code using the Twilio Verify API. - * This bypasses our Redis-based OtpService — Twilio manages the OTP lifecycle. - * - * NOTE: To use this, SmsOtpAuthHandler would need to call this method - * instead of OtpService.validate(). Consider extending SmsService interface: - * boolean verifyOtp(String phoneNumber, String code); - */ - public boolean verifyOtp(String phoneNumber, String code) { - try { - VerificationCheck check = VerificationCheck.creator(verifyServiceSid) - .setTo(phoneNumber) - .setCode(code) - .create(); - - boolean approved = "approved".equals(check.getStatus()); - log.info("Twilio Verify check for {}: status={}", phoneNumber, check.getStatus()); - return approved; - } catch (Exception e) { - log.error("Twilio Verify check failed for {}: {}", phoneNumber, e.getMessage()); - return false; - } - } -} -``` - -**Interface extension (if adopting Verify API):** - -```java -public interface SmsService { - void sendOtp(String phoneNumber, String code); - - // Optional: server-side verification for Twilio Verify API - default boolean verifyOtp(String phoneNumber, String code) { - // Default: not supported (raw SMS adapters use OtpService + Redis) - throw new UnsupportedOperationException("Use OtpService for verification"); - } -} -``` - -**Additional application.yml properties:** - -```yaml -sms: - provider: verify # 'raw' for TwilioSmsService, 'verify' for TwilioVerifySmsService - twilio: - verify-service-sid: ${TWILIO_VERIFY_SERVICE_SID:} -``` - -**Setup in Twilio Console:** - -1. Go to **Verify > Services** in the Twilio Console. -2. Create a new Verify Service (name: "FIVUCSAS Identity"). -3. Copy the **Service SID** (starts with `VA`). -4. Add `TWILIO_VERIFY_SERVICE_SID=VAxxxxxxxx` to `.env.prod`. - ---- - -## 5. Future: Firebase Phone Auth - -### Why Firebase Phone Auth Is NOT a Good Fit - -Firebase Phone Auth is designed for **client-side phone-based login** where Firebase controls -the entire authentication flow. This conflicts with FIVUCSAS's architecture: - -| Concern | FIVUCSAS Requirement | Firebase Phone Auth | -|---------|---------------------|---------------------| -| OTP lifecycle | Server-controlled (Redis TTL, consume-on-use) | Firebase-controlled (client SDK) | -| Auth session | Managed by identity-core-api (AuthSession entity) | Firebase manages its own session | -| Multi-step flows | SMS OTP is one step in a configurable flow | Firebase is a standalone auth method | -| Token format | Our JWT with custom claims | Firebase ID Token (different format) | -| Backend verification | Our OtpService validates against Redis | Firebase Admin SDK verifies Firebase tokens | -| User store | PostgreSQL (users table, RLS) | Firebase Authentication user store | -| Tenant isolation | Multi-tenant with tenant_id scoping | No built-in multi-tenancy | - -### When Firebase COULD Be Used - -Firebase Phone Auth could serve as an **alternative adapter** for a simplified phone-based -login flow (not multi-step auth). The implementation would: - -1. Create a `FirebasePhoneAuthAdapter` implementing a new `PhoneAuthService` port. -2. The client app calls Firebase SDK directly to get a Firebase ID Token. -3. The backend verifies the Firebase ID Token via Firebase Admin SDK. -4. Map the Firebase UID to a local user account. - -This is a fundamentally different flow from SMS OTP within multi-step auth. It bypasses our -OtpService and SmsService entirely, acting as a standalone identity provider. - -**Verdict**: Not recommended for FIVUCSAS. Twilio (raw or Verify API) is the correct choice -for server-controlled SMS OTP within hexagonal architecture. Firebase would introduce a -parallel auth system that doesn't integrate cleanly with the existing auth flow engine. - ---- - -## 6. Testing Plan - -### 6.1 Unit Tests (Already Passing) - -| Test File | Tests | Status | -|-----------|-------|--------| -| `SmsOtpAuthHandlerTest.java` | 7 tests (send, verify valid/invalid, missing code, no user, no phone, method type) | PASSING | -| `TwilioSmsServiceTest.java` (SmsServiceConfigTest) | 2 tests (NoOp instanceof, no-throw) | PASSING | - -### 6.2 Integration Test (Post-Activation) - -After enabling Twilio, run this manual test sequence: - -```bash -# 1. Login as admin to get JWT -TOKEN=$(curl -s -X POST https://api.fivucsas.com/api/v1/auth/login \ - -H "Content-Type: application/json" \ - -d '{"email":"admin@fivucsas.com","password":""}' \ - | jq -r '.token') - -# 2. Ensure the target user has a phone number -# (set via user management or directly in DB) - -# 3. Send SMS OTP -curl -X POST https://api.fivucsas.com/api/v1/otp/sms/send/{userId} \ - -H "Authorization: Bearer $TOKEN" -# Expected: {"success":true,"message":"OTP sent via SMS","expiresInSeconds":300} - -# 4. Check your phone for the 6-digit code - -# 5. Verify the OTP -curl -X POST https://api.fivucsas.com/api/v1/otp/sms/verify/{userId} \ - -H "Authorization: Bearer $TOKEN" \ - -H "Content-Type: application/json" \ - -d '{"code":"XXXXXX"}' -# Expected: {"success":true,"message":"OTP verified successfully"} - -# 6. Verify OTP is consumed (replay should fail) -curl -X POST https://api.fivucsas.com/api/v1/otp/sms/verify/{userId} \ - -H "Authorization: Bearer $TOKEN" \ - -H "Content-Type: application/json" \ - -d '{"code":"XXXXXX"}' -# Expected: {"success":false,"message":"Invalid or expired OTP code"} -``` - -### 6.3 Multi-Step Auth Flow Test - -1. Create an auth flow with SMS_OTP as a step (via Auth Flow Builder UI or API). -2. Start an auth session against that flow. -3. At the SMS_OTP step, send `{"action":"send"}` to trigger OTP delivery. -4. Submit the received code to complete the step. -5. Verify the session advances to the next step. - -### 6.4 Edge Cases to Verify - -- Invalid phone number format (non-E.164) returns Twilio error, caught by try-catch. -- OTP expires after 5 minutes (Redis TTL). -- User without phone number gets `400 Bad Request`. -- NoOpSmsService activates when `SMS_ENABLED=false` (rollback path). -- Twilio trial account: SMS to unverified numbers fails with clear error. - -### 6.5 Container Health Check - -```bash -# After activation, verify container is healthy -docker ps --filter name=identity-core-api --format "{{.Status}}" -# Expected: "Up X minutes (healthy)" - -# Check Twilio initialization in logs -docker logs identity-core-api 2>&1 | grep -i "twilio" -# Expected: "Twilio SMS service initialized with from-number: +1XXXXXXXXXX" -``` - ---- - -## 7. Cost Estimation - -### Twilio Pricing (as of 2026) - -| Item | Cost | -|------|------| -| Phone number (US local) | $1.00/month | -| Outbound SMS (US to US) | $0.0079/segment | -| Outbound SMS (US to Turkey) | ~$0.0408/segment | -| Twilio Verify API | $0.05/successful verification | - -### Budget: $50 GitHub Student Credit - -**Scenario A: Raw SMS to Turkey (+90 numbers)** - -| Item | Monthly | 12 Months | -|------|---------|-----------| -| Phone number | $1.00 | $12.00 | -| Remaining for SMS | - | $38.00 | -| SMS to Turkey at $0.0408 | ~93/month | ~931 total | - -**Scenario B: Raw SMS to US (+1 numbers, development/testing)** - -| Item | Monthly | 12 Months | -|------|---------|-----------| -| Phone number | $1.00 | $12.00 | -| Remaining for SMS | - | $38.00 | -| SMS to US at $0.0079 | ~481/month | ~4,810 total | - -**Scenario C: Twilio Verify API** - -| Item | Monthly | 12 Months | -|------|---------|-----------| -| Phone number | Not needed | $0 | -| Verify at $0.05/verification | - | $50.00 | -| Total verifications | ~83/month | ~1,000 total | - -### Expected Usage - -For a university project with a small user base (5-20 active users, demo presentations, -exam portal integration): - -- **Development/testing**: ~50 SMS/month -- **Demo presentations**: ~10 SMS/event -- **Exam portal pilot**: ~100 SMS/semester - -**Estimated monthly cost**: $3-5 (raw SMS) or $5-10 (Verify API). -**$50 credit duration**: Easily lasts the entire academic year and beyond. - -### Recommendation - -Start with **raw SMS (TwilioSmsService)** to maximize the number of messages per dollar. -The existing implementation is ready — just add credentials. Upgrade to Verify API only if -rate limiting or fraud detection becomes necessary. - ---- - -## Appendix: Quick Reference - -``` -# Activate SMS -./scripts/setup-twilio.sh - -# Check status -./scripts/setup-twilio.sh --check - -# Deactivate (rollback) -# Set SMS_ENABLED=false in .env.prod, restart container - -# Logs -docker logs identity-core-api 2>&1 | grep -i sms -``` - ---- - -## Appendix: SMS Sender ID Branding (Turkey, +90) - -**Status (2026-04-15)**: Twilio Verify SMS messages to Turkish numbers currently show **"TWVerify"** as the sender, not "FIVUCSAS". This is NOT a bug and cannot be fixed in code. - -**Why**: "TWVerify" is Twilio's default shared alphanumeric sender for Verify routes in countries where no custom sender has been registered on the account. None of the following affect it: -- Verify Service "Friendly Name" (internal label only, never shown to end users) -- "Branded Sender ID" (a separate product — Branded Communications / RCS, not SMS) -- Java SDK or REST API parameters (`.setFriendlyName`, `.setLocale`, etc.) - -**What CAN change it**: Per Twilio Verify documentation, the SMS From field is controlled by (in priority order): -1. An **Alternate Sender** configured per country under *Verify → Service → Channel Configuration → SMS → Alternate Senders*, or -2. A Messaging Service SID passed via `.setMessagingServiceSid(...)` whose pool contains a registered alpha sender for TR, or -3. Twilio's default shared alpha ("TWVerify") — current state. - -**To set "FIVUCSAS" as the Turkish sender** (owner: Ahmet): -1. Register "FIVUCSAS" with the Turkish regulator (BTK / İYS — İleti Yönetim Sistemi) as a brand-origin sender ID. -2. Open a Twilio Support ticket titled "Register alphanumeric Sender ID 'FIVUCSAS' for Turkey (+90) on Verify Service SID VAxxxx". Attach: - - Turkish company registration proof - - BTK/İYS registration evidence -3. Approval: 1–4 weeks. -4. Once approved, in Twilio Console: **Verify → Services → (service) → Channel Configuration → SMS → Alternate Senders** → add `FIVUCSAS` under country `TR`. -5. No code change required — existing `Verification.creator(...).setLocale("tr").create()` will pick up the alternate sender automatically. - -**Code already in place**: `TwilioVerifySmsService.sendOtp` calls `.setLocale("tr")` so the message body is Turkish regardless of sender branding. diff --git a/plans/VOICE_STT_PLAN.md b/plans/VOICE_STT_PLAN.md deleted file mode 100644 index 784e5b4..0000000 --- a/plans/VOICE_STT_PLAN.md +++ /dev/null @@ -1,475 +0,0 @@ -# Voice Speech-to-Text Verification Plan - -**Version:** 1.0 -**Date:** 2026-04-05 -**Status:** Design Document (Pre-Implementation) -**Author:** Ahmet Abdullah Gultekin -**Project:** FIVUCSAS - Face and Identity Verification Using Cloud-Based SaaS -**Organization:** Marmara University - Computer Engineering Department -**Feature ID:** W17 - ---- - -## Table of Contents - -1. [Executive Summary](#1-executive-summary) -2. [Current Voice Architecture](#2-current-voice-architecture) -3. [Dual Verification Architecture](#3-dual-verification-architecture) -4. [STT Engine Selection](#4-stt-engine-selection) -5. [Passphrase Management](#5-passphrase-management) -6. [Anti-Replay and Liveness](#6-anti-replay-and-liveness) -7. [Integration with Existing System](#7-integration-with-existing-system) -8. [Implementation Phases](#8-implementation-phases) -9. [Risk Assessment](#9-risk-assessment) -10. [Dependencies and Prerequisites](#10-dependencies-and-prerequisites) - ---- - -## 1. Executive Summary - -FIVUCSAS currently implements voice biometric authentication using speaker embedding comparison (Resemblyzer, 256-dim). This verifies WHO is speaking but not WHAT they said. By adding Speech-to-Text (STT) verification, we create a dual-factor voice system: the speaker's identity is verified by their voiceprint, and their liveness is verified by recognizing a dynamically generated passphrase. This makes voice replay attacks virtually impossible -- an attacker would need both a perfect voice clone AND real-time synthesis of arbitrary phrases. The system generates a new random passphrase for each authentication attempt, displayed on screen, and verifies both the content match (>85% word accuracy) and speaker match (>0.75 cosine similarity) before granting access. - ---- - -## 2. Current Voice Architecture - -### Existing Pipeline - -``` -+----------------+ +----------------+ +-------------------+ -| Client | --> | biometric- | --> | PostgreSQL | -| (MediaRecorder| | processor | | (biometric_db) | -| WAV 16kHz) | | (FastAPI) | | | -+----------------+ +-------+--------+ +-------------------+ - | - +----------+-----------+ - | | - +-----v------+ +-----v------+ - | Resemblyzer| | pgvector | - | (256-dim | | (HNSW | - | embedding)| | cosine) | - +------------+ +------------+ -``` - -### Current Endpoints - -| Endpoint | Method | Function | -|----------|--------|----------| -| `/voice/enroll` | POST | Extract embedding, store in voice_enrollments | -| `/voice/verify` | POST | Compare embedding against enrolled user | -| `/voice/search` | POST | 1:N search across all enrolled voices | -| `/voice/delete` | DELETE | Remove enrollment | - -### Current Metrics - -- Embedding extraction: 490-585ms -- Verification (1:1): ~600ms total -- Search (1:N): ~800ms for 100 enrollments -- EER: ~3% (with quality-weighted centroids) - ---- - -## 3. Dual Verification Architecture - -### Architecture Diagram - -``` -+------------------------------------------------------------------+ -| CLIENT | -| | -| +------------------+ +------------------+ | -| | Display | | Record Audio | | -| | Passphrase: | | (WAV 16kHz, | | -| | "Yedi kirmizi | | 3-8 seconds) | | -| | balon uctu" | | | | -| +------------------+ +--------+---------+ | -| | | -+------------------------------------|---------+--------------------+ - | | - v | -+------------------------------------+---------v--------------------+ -| BIOMETRIC PROCESSOR | -| | -| +------------------+ +------------------+ | -| | Resemblyzer | | Whisper | | -| | Speaker Embed | | STT Engine | | -| | (WHO said it) | | (WHAT was said) | | -| +--------+---------+ +--------+---------+ | -| | | | -| v v | -| +------------------+ +------------------+ | -| | Speaker Match | | Content Match | | -| | cosine >= 0.75 | | WER <= 15% | | -| +--------+---------+ +--------+---------+ | -| | | | -| +----------+ +----------+ | -| | | | -| v v | -| +-------+--+--------+ | -| | DUAL VERDICT | | -| | speaker AND | | -| | content must | | -| | both pass | | -| +-------------------+ | -| | -+------------------------------------------------------------------+ -``` - -### Verification Decision Matrix - -| Speaker Match | Content Match | Verdict | Interpretation | -|--------------|---------------|---------|----------------| -| PASS (>= 0.75) | PASS (WER <= 15%) | VERIFIED | Correct person, correct phrase | -| PASS (>= 0.75) | FAIL (WER > 15%) | REJECTED | Right person, wrong/garbled phrase | -| FAIL (< 0.75) | PASS (WER <= 15%) | REJECTED | Wrong person, right phrase (replay?) | -| FAIL (< 0.75) | FAIL (WER > 15%) | REJECTED | Wrong person, wrong phrase | - -### Response Schema - -```json -{ - "verified": false, - "speaker_score": 0.82, - "speaker_threshold": 0.75, - "speaker_match": true, - "content_transcript": "yedi kirmizi balon uctu", - "content_expected": "yedi kirmizi balon uctu", - "content_wer": 0.0, - "content_threshold": 0.15, - "content_match": true, - "overall_verdict": "VERIFIED", - "passphrase_id": "a1b2c3d4", - "processing_time_ms": 1250 -} -``` - ---- - -## 4. STT Engine Selection - -### Comparison Matrix - -| Engine | Deployment | Turkish Support | Latency (3s audio) | Cost | Accuracy (WER) | -|--------|-----------|-----------------|---------------------|------|-----------------| -| **Whisper (small)** | Local | Yes (multi-lingual) | ~800ms (CPU) | Free | ~8% (TR) | -| **Whisper (tiny)** | Local | Yes | ~300ms (CPU) | Free | ~15% (TR) | -| Google STT | Cloud API | Yes (tr-TR) | ~500ms | $0.006/15s | ~5% (TR) | -| Azure STT | Cloud API | Yes (tr-TR) | ~500ms | $1/hr audio | ~5% (TR) | -| Vosk (offline) | Local | Yes (TR model) | ~400ms | Free | ~12% (TR) | - -### Recommendation: Whisper Small (Local) - -**Rationale:** - -1. **Privacy**: Audio never leaves the server; compliant with KVKK/GDPR -2. **Cost**: Zero per-request cost; critical for BaaS rental model viability -3. **Turkish**: Whisper's multi-lingual training includes Turkish with good accuracy -4. **Latency**: 800ms is acceptable when combined with speaker embedding (490ms runs in parallel) -5. **Consistency**: No external API dependency; no rate limits; no outages - -**Model size**: ~500 MB (whisper-small). Fits in current 4 GB biometric-api memory budget. - -### Whisper Integration - -```python -import whisper - -# Load once at startup (global singleton) -whisper_model = whisper.load_model("small", device="cpu") - -async def transcribe(audio_path: str, language: str = "tr") -> dict: - result = whisper_model.transcribe( - audio_path, - language=language, - task="transcribe", - fp16=False, # CPU mode - temperature=0.0, # Deterministic - no_speech_threshold=0.6 - ) - return { - "text": result["text"].strip().lower(), - "language": result["language"], - "confidence": 1.0 - result.get("no_speech_prob", 0) - } -``` - ---- - -## 5. Passphrase Management - -### Passphrase Types - -| Type | Example | Use Case | -|------|---------|----------| -| Random words (Turkish) | "mavi kedi pencereden baktı" | Default — high entropy | -| Random numbers | "dört yedi iki dokuz beş" | Simple, language-neutral | -| Challenge question | "bugün hava nasıl" | Conversational liveness | -| Custom (tenant-defined) | "Marmara Bankası hoş geldiniz" | Branded experience | - -### Turkish Word Pool - -```python -TURKISH_WORD_POOL = { - "subjects": ["kedi", "köpek", "kuş", "balık", "aslan", "tavşan", "kelebek", - "araba", "gemi", "uçak", "tren", "bisiklet"], - "adjectives": ["kırmızı", "mavi", "yeşil", "büyük", "küçük", "hızlı", - "yavaş", "güzel", "eski", "yeni", "sıcak", "soğuk"], - "numbers": ["bir", "iki", "üç", "dört", "beş", "altı", "yedi", - "sekiz", "dokuz", "sıfır"], - "verbs": ["koştu", "uçtu", "yüzdü", "baktı", "güldü", "uyudu", - "atladı", "döndü", "durdu", "geldi"] -} - -def generate_passphrase(word_count: int = 4) -> str: - """Generate a pronounceable Turkish passphrase. - 4 words from pool of ~50 = ~50^4 = 6.25M combinations. - """ - pattern = random.choice([ - "{adj} {subj} {verb}", # "kırmızı kedi koştu" - "{num} {adj} {subj} {verb}", # "üç büyük kuş uçtu" - "{subj} {adj} {subj} {verb}", # "kedi küçük balık gördü" - ]) - # ... fill from pool -``` - -### Passphrase Lifecycle - -``` -1. Client requests passphrase: - POST /voice/challenge -> { passphrase_id: "abc", text: "yedi kırmızı balon uçtu", expires_at: +60s } - -2. Server stores in Redis: - SET voice:challenge:abc "yedi kırmızı balon uçtu" EX 60 - -3. Client displays passphrase, user speaks it - -4. Client sends audio + passphrase_id: - POST /voice/verify-stt { audio: , passphrase_id: "abc", user_id: "..." } - -5. Server: - a. GET voice:challenge:abc -> expected text (fails if expired/used) - b. DEL voice:challenge:abc (one-time use) - c. Run speaker embedding (Resemblyzer) || Run STT (Whisper) in parallel - d. Compare speaker + content - e. Return dual verdict -``` - ---- - -## 6. Anti-Replay and Liveness - -### Why Dual Verification Defeats Replay - -| Attack | Speaker-Only | STT-Only | Dual (Ours) | -|--------|-------------|----------|-------------| -| Pre-recorded audio | Passes (same voice) | Passes (if same phrase) | **Fails** (phrase is random each time) | -| Voice cloning (TTS) | May pass (advanced clone) | Passes | **Fails** (clone quality + random phrase timing) | -| Live impersonator | Fails (different voiceprint) | May pass | Fails (different voiceprint) | -| Replay with editing | Passes | Fails (spliced audio artifacts) | Fails (both) | - -### Additional Liveness Signals - -| Signal | Method | Weight | -|--------|--------|--------| -| Phrase freshness | Passphrase expires in 60s, one-time use | Critical (gate) | -| Audio duration | Must be 2-8 seconds (reject too short/long) | High | -| Speech continuity | No >500ms gaps (detect concatenation) | Medium | -| Background consistency | Whisper noise profile should be uniform | Low | -| Timing | Response within 10s of challenge display | Medium | - -### Rate Limiting - -``` -voice:challenge:{user_id} -> max 5 challenges per minute -voice:verify:{user_id} -> max 3 attempts per challenge -voice:lockout:{user_id} -> 15 min lockout after 5 consecutive failures -``` - ---- - -## 7. Integration with Existing System - -### VoiceAuthHandler Extension - -```java -// identity-core-api: VoiceAuthHandler.java -// Currently: -public class VoiceAuthHandler implements AuthStepHandler { - @Override - public AuthStepResult handle(AuthSession session, AuthStepData data) { - // Calls biometric-processor /voice/verify - // Returns: speaker match only - } -} - -// After STT integration: -public class VoiceAuthHandler implements AuthStepHandler { - @Override - public AuthStepResult handle(AuthSession session, AuthStepData data) { - String mode = data.getMode(); // "speaker_only" or "speaker_stt" - - if ("speaker_stt".equals(mode)) { - // 1. Validate passphrase_id not expired - // 2. Call biometric-processor /voice/verify-stt - // 3. Check BOTH speaker_match AND content_match - } else { - // Existing behavior: speaker embedding only - } - } -} -``` - -### New Biometric Processor Endpoints - -``` -POST /voice/challenge - Request: { language: "tr", word_count: 4 } - Response: { passphrase_id: "abc123", text: "yedi kirmizi balon uctu", expires_at: "..." } - -POST /voice/verify-stt - Request: multipart { audio: , user_id: "...", passphrase_id: "abc123" } - Response: { verified: bool, speaker_score, content_wer, transcript, ... } -``` - -### Auth Flow Configuration - -Tenants can choose voice verification mode per auth flow: - -```json -{ - "auth_flow_steps": [ - { - "method": "VOICE", - "config": { - "mode": "speaker_stt", // or "speaker_only" - "passphrase_type": "random_tr", // or "random_numbers", "custom" - "word_count": 4, - "speaker_threshold": 0.75, - "content_wer_threshold": 0.15 - } - } - ] -} -``` - -### Frontend Changes - -``` -VoiceStep component (web-app + client-apps): - -+----------------------------------------------+ -| | -| Please say the following phrase: | -| | -| +--------------------------------------+ | -| | | | -| | "Yedi kirmizi balon uctu" | | -| | | | -| +--------------------------------------+ | -| | -| [ Recording... 2.3s ] |||||||||||| | -| | -| Speaker Match: 0.87 / 0.75 [PASS] | -| Content Match: 0.00 WER [PASS] | -| | -| [Verified] | -| | -+----------------------------------------------+ -``` - ---- - -## 8. Implementation Phases - -### Phase 1 — Whisper Integration (1 week) - -| Task | Effort | Details | -|------|--------|---------| -| Install Whisper in biometric-processor | 1 day | pip install openai-whisper, download "small" model | -| /voice/challenge endpoint | 1 day | Turkish word pool, Redis storage, expiry | -| /voice/verify-stt endpoint | 2 days | Parallel Resemblyzer + Whisper, dual verdict | -| WER calculation utility | 0.5 day | Levenshtein distance on word arrays | -| Unit tests | 0.5 day | Mock audio, verify scoring logic | - -### Phase 2 — Backend Integration (1 week) - -| Task | Effort | Details | -|------|--------|---------| -| VoiceAuthHandler STT mode | 1 day | Extend existing handler | -| BiometricServicePort extension | 0.5 day | Add verifySpeakerAndContent method | -| Auth flow step config schema | 0.5 day | mode, passphrase_type, thresholds | -| Rate limiting for voice challenges | 0.5 day | Redis-based per-user limits | -| Integration tests | 1.5 days | End-to-end with test audio files | - -### Phase 3 — Frontend (1 week) - -| Task | Effort | Details | -|------|--------|---------| -| VoiceStep STT mode (web-app) | 2 days | Passphrase display, dual result UI | -| VoiceStep STT mode (client-apps) | 2 days | KMP shared + Android/iOS/Desktop | -| Auth-test page update | 1 day | Add STT verification section | - -### Phase 4 — Hardening (0.5 week) - -| Task | Effort | Details | -|------|--------|---------| -| Turkish accent testing | 1 day | Test with various accents, adjust WER threshold | -| Performance optimization | 1 day | Whisper batch mode, model warmup | -| Documentation | 0.5 day | API docs, tenant configuration guide | - -### Total Effort: ~3.5 weeks - -``` -Week 1: Phase 1 (Whisper integration + endpoints) -Week 2: Phase 2 (Backend integration + auth flow config) -Week 3: Phase 3 (Frontend: web-app + client-apps) -Week 3.5: Phase 4 (Hardening + accent testing) -``` - ---- - -## 9. Risk Assessment - -| Risk | Probability | Impact | Mitigation | -|------|------------|--------|------------| -| Whisper Turkish accuracy insufficient | Low | High | Whisper-small has ~8% WER on TR; threshold is 15% (generous margin) | -| Whisper model size (500 MB) exceeds memory | Medium | Medium | Current biometric-api has 4 GB; Whisper + Resemblyzer + DeepFace fit within budget | -| Users cannot pronounce passphrase correctly | Medium | Medium | Allow 3 retries; configurable word_count (fewer words = easier) | -| Noisy environment degrades both speaker and STT | High | Medium | Silero VAD pre-filter; instruct user to find quiet environment | -| Latency: Whisper 800ms + Resemblyzer 500ms | Medium | Low | Run in parallel (not sequential); total ~900ms acceptable | -| Accessibility: deaf/mute users excluded | Low | Medium | Voice STT is optional; tenants can use speaker-only or other auth methods | -| Whisper hallucination on silence | Medium | Low | no_speech_threshold=0.6; reject if confidence < 0.5 | -| Language detection mismatch | Low | Low | Force language="tr" (do not auto-detect) | - ---- - -## 10. Dependencies and Prerequisites - -### Technical Prerequisites - -| Prerequisite | Status | Notes | -|-------------|--------|-------| -| Resemblyzer (speaker embedding) | Deployed | Already in biometric-processor | -| Redis (challenge storage) | Deployed | shared-redis on Hetzner | -| WAV audio capture (client) | Implemented | MediaRecorder in web-app, AudioRecorder in client-apps | -| VoiceAuthHandler | Implemented | identity-core-api, speaker-only mode | -| Whisper Python package | Not installed | `pip install openai-whisper` (~500 MB model download) | - -### Infrastructure Impact - -| Resource | Current | After STT | Delta | -|----------|---------|-----------|-------| -| biometric-api RAM | ~3.5 GB | ~4.2 GB | +700 MB (Whisper model) | -| biometric-api disk | ~2 GB | ~2.5 GB | +500 MB (model file) | -| Redis keys | ~100 | ~200 (peak) | +100 (voice challenges, 60s TTL) | -| CPU (inference) | Moderate | Higher | Whisper small: ~800ms CPU per request | - -### Model Requirements - -- Whisper "small" (244M parameters): Best accuracy/speed tradeoff for CPU -- If CPU becomes bottleneck: upgrade to Whisper "tiny" (39M parameters, ~300ms, 15% WER) -- Future: Whisper.cpp for 2x speedup without GPU (C++ implementation) - ---- - -*This feature is a natural extension of the existing voice biometric system. The passphrase-based liveness mechanism provides a significant security improvement with relatively low implementation effort, since Resemblyzer and the voice pipeline are already deployed and tested.* diff --git a/presentations/DEFENSE_PRESENTATION_JAN_2026.md b/presentations/DEFENSE_PRESENTATION_JAN_2026.md deleted file mode 100644 index 2ae669f..0000000 --- a/presentations/DEFENSE_PRESENTATION_JAN_2026.md +++ /dev/null @@ -1,515 +0,0 @@ -# FIVUCSAS - CSE4297 Engineering Project 1 Defense Presentation - -**Date:** January 7, 2026 -**Duration:** 12 minutes + 3 minutes Q&A -**Language:** English - ---- - -## Slide 1: Title Slide (Page 1) - -### Face and Identity Verification Using Cloud-based SaaS Models (FIVUCSAS) - -**CSE4297 Engineering Project 1** - -**Team Members:** -- Ahmet Abdullah Gültekin -- Ayşe Gülsüm Eren -- Ayşenur Arıcı - -**Advisor:** Assoc. Prof. Dr. Mustafa Ağaoğlu - -**Marmara University - Faculty of Technology** -Department of Computer Engineering - -January 7, 2026 - ---- - -## Slide 2: Outline (Page 2) - -### Presentation Outline - -1. **Problem Definition** - Authentication security challenges -2. **Project Aims** - Four main objectives -3. **Related Work** - Existing solutions and gaps -4. **Scope** - Project boundaries and deliverables -5. **Methodology & Technical Approach** - Architecture and algorithms -6. **Tasks Accomplished** - First semester achievements -7. **Difficulties Encountered** - Challenges and solutions -8. **Second Semester Tasks** - Remaining work - ---- - -## Slide 3: Problem Definition (Page 3) - -### The Authentication Security Problem - -**Current Challenges:** - -| Challenge | Impact | -|-----------|--------| -| Password-only authentication | 81% of breaches involve weak credentials | -| Static biometric systems | Vulnerable to spoofing attacks (photos, videos) | -| Complex multi-factor auth | Poor user adoption due to friction | -| Identity document fraud | Increasing synthetic identity crimes | - -**The Gap:** -- Existing solutions either sacrifice **security** for usability or **usability** for security -- No unified platform combining face recognition, liveness detection, and document verification - ---- - -## Slide 4: Problem Definition - Real World Impact (Page 4) - -### Why This Matters - -**Industry Statistics:** -- Average cost of data breach: **$4.45M** (IBM, 2023) -- Face spoofing attacks increased **50%** since 2020 -- **73%** of organizations lack proper biometric security - -**Target Users:** -1. Financial institutions (KYC compliance) -2. Educational platforms (exam proctoring) -3. Enterprise access control -4. Government services (e-ID verification) - -*Figure 1: Authentication vulnerability attack vectors* - ---- - -## Slide 5: Project Aims (Page 5) - -### Four Main Objectives - -| # | Objective | Description | -|---|-----------|-------------| -| 1 | **Biometric Puzzle** | Novel liveness detection algorithm using random challenge sequences | -| 2 | **SaaS Platform** | Multi-tenant cloud-based biometric authentication service | -| 3 | **Cross-Platform App** | Mobile/desktop application with integrated biometrics | -| 4 | **Document Verification** | ICAO-compliant NFC passport/ID card reading | - -**Success Metrics:** -- Face recognition accuracy: >98% -- Liveness detection spoof rejection: >99% -- API response time: <500ms -- Multi-platform support: Android, iOS, Desktop - ---- - -## Slide 6: Related Work (Page 6) - -### Existing Solutions Analysis - -| Solution | Strengths | Limitations | -|----------|-----------|-------------| -| **DeepFace** | Multiple models, open-source | No liveness detection | -| **FaceNet** | 99.63% LFW accuracy | Single embedding model | -| **ArcFace** | State-of-art accuracy | Computationally heavy | -| **AWS Rekognition** | Cloud-scalable | Expensive, vendor lock-in | -| **Apple Face ID** | Excellent UX | Device-specific, not SaaS | - -**Our Differentiation:** -- **Multi-model fusion** (9 ML models) -- **Active + Passive liveness** (Biometric Puzzle) -- **Self-hosted SaaS** (no vendor lock-in) -- **NFC document integration** - ---- - -## Slide 7: Scope (Page 7) - -### Project Scope & Deliverables - -**In Scope:** - -| Component | Technology | Status | -|-----------|------------|--------| -| Biometric API | FastAPI + DeepFace | ✅ Complete | -| Identity API | Spring Boot + JWT | 🔄 68% | -| Web Dashboard | Next.js + shadcn/ui | ✅ Complete | -| Mobile/Desktop | Kotlin Multiplatform | 🔄 60% | -| NFC Reader | Android NFC SDK | ✅ PoC Complete | -| Database | PostgreSQL + pgvector | ✅ Complete | - -**Out of Scope:** -- Hardware development (dedicated biometric sensors) -- Custom ML model training (using pre-trained models) -- ISO/IEC 30107 certification (future work) - ---- - -## Slide 8: System Architecture (Page 8) - -### High-Level Architecture - -``` -┌─────────────────────────────────────────────────────────────────────┐ -│ CLIENT LAYER │ -│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ -│ │ Android App │ │ Desktop App │ │ Web Admin │ │ -│ │ (Kotlin) │ │ (Kotlin) │ │ (Next.js) │ │ -│ └──────────────┘ └──────────────┘ └──────────────┘ │ -└─────────────────────────────────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────────────┐ -│ API GATEWAY │ -└─────────────────────────────────────────────────────────────────────┘ - │ - ┌───────────────┴───────────────┐ - ▼ ▼ -┌─────────────────────────┐ ┌─────────────────────────┐ -│ Identity Core API │───▶│ Biometric Processor │ -│ (Spring Boot) │ │ (FastAPI) │ -│ • Authentication │ │ • Face Recognition │ -│ • User Management │ │ • Liveness Detection │ -│ • Multi-Tenancy │ │ • Quality Analysis │ -└───────────┬─────────────┘ └───────────┬─────────────┘ - │ │ - └──────────────┬───────────────┘ - ▼ - ┌─────────────────────────┐ - │ PostgreSQL + pgvector │ - │ (Face Embeddings) │ - └─────────────────────────┘ -``` - -*Figure 2: FIVUCSAS microservices architecture* - ---- - -## Slide 9: Methodology - Biometric Puzzle Algorithm (Page 9) - -### Novel Liveness Detection: Biometric Puzzle - -**Challenge Sequence Generation:** -``` -Actions = {blink, smile, turn_left, turn_right, nod} -Sequence = random_sample(Actions, k=3) -Example: [smile → turn_left → blink] -``` - -**Detection Metrics (MediaPipe):** - -| Metric | Formula | Threshold | -|--------|---------|-----------| -| Eye Aspect Ratio (EAR) | (p2-p6 + p3-p5) / (2×p1-p4) | < 0.21 = blink | -| Mouth Aspect Ratio (MAR) | (p14-p18) / (p12-p16) | > 0.60 = smile | -| Head Pose | pitch, yaw, roll angles | ±15° threshold | - -**Advantages over Passive-Only:** -- Defeats photo/video replay attacks -- Cannot be predicted (random sequence) -- Natural user interaction - -*Figure 3: 468-point MediaPipe facial landmarks* - ---- - -## Slide 10: Methodology - Face Recognition Pipeline (Page 10) - -### Multi-Model Face Recognition - -**Pipeline Stages:** - -``` -Image Input → Detection → Alignment → Embedding → Matching - │ │ │ │ │ - │ RetinaFace MediaPipe FaceNet512 Cosine - │ or MTCNN landmarks or ArcFace Similarity -``` - -**Supported Models (9 Total):** - -| Model | Embedding Dim | Accuracy (LFW) | -|-------|---------------|----------------| -| FaceNet | 128-D | 99.63% | -| FaceNet512 | 512-D | 99.65% | -| ArcFace | 512-D | 99.82% | -| VGG-Face | 2622-D | 98.78% | - -**Similarity Calculation:** -``` -cos(θ) = (A · B) / (||A|| × ||B||) -Match if: cos(θ) ≥ τ (τ = 0.68 default) -``` - -*Figure 4: Face recognition pipeline flow* - ---- - -## Slide 11: Tasks Accomplished - Biometric Processor (Page 11) - -### First Semester: Biometric Processor API (100%) - -**46+ Endpoints Implemented:** - -| Category | Endpoints | Status | -|----------|-----------|--------| -| Face Enrollment | `/enroll`, `/enrollments/{id}` | ✅ | -| Verification (1:1) | `/verify` | ✅ | -| Search (1:N) | `/search` | ✅ | -| Liveness Detection | `/liveness`, `/liveness/challenge` | ✅ | -| Quality Analysis | `/quality/analyze` | ✅ | -| Demographics | `/demographics/analyze` | ✅ | -| Landmarks | `/landmarks/detect` (468 points) | ✅ | -| Batch Operations | `/batch/*` | ✅ | -| Proctoring | `/proctoring/*`, WebSocket | ✅ | -| Admin | `/admin/*` | ✅ | - -**Code Metrics:** -- Python files: 100+ -- Test coverage: 85% -- Lines of code: 15,000+ - ---- - -## Slide 12: Tasks Accomplished - Web Dashboard (Page 12) - -### First Semester: Demo GUI (100%) - -**14+ Interactive Pages:** - -| Page | Features | -|------|----------| -| Dashboard | Analytics overview, charts | -| Enrollment | Camera capture, real-time preview | -| Verification | 1:1 matching with confidence scores | -| Liveness | Biometric Puzzle demo | -| Quality | Image quality metrics visualization | -| Demographics | Age, gender, emotion analysis | -| Landmarks | 468-point interactive visualization | -| Similarity | NxN matrix clustering heatmap | -| Proctoring | Session management, WebSocket | - -**Technology Stack:** -- Next.js 14 (App Router) -- TypeScript -- shadcn/ui components -- TailwindCSS - -*Figure 5: Demo GUI screenshot - Dashboard* - ---- - -## Slide 13: Tasks Accomplished - Identity API & Mobile (Page 13) - -### First Semester: Supporting Components - -**Identity Core API (68%):** - -| Feature | Status | -|---------|--------| -| User Registration | ✅ Complete | -| JWT Authentication (HS512) | ✅ Complete | -| Refresh Token Management | ✅ Complete | -| BCrypt Password Hashing | ✅ Complete | -| Hexagonal Architecture | ✅ Complete | -| Database Schema (6 migrations) | ✅ Complete | -| RBAC Enforcement | 🔄 In Progress | - -**Client Applications (60%):** - -| Platform | UI | Backend Integration | -|----------|-----|---------------------| -| Android | ✅ Complete | 🔄 Pending | -| Desktop | ✅ Complete | 🔄 Pending | -| iOS | 📋 Ready | 🔄 Pending | - -**NFC Reader (85%):** Turkish eID + Passport reading PoC - ---- - -## Slide 14: Difficulties Encountered (Page 14) - -### Technical Challenges & Solutions - -| Challenge | Impact | Solution | -|-----------|--------|----------| -| **Model Loading Time** | 30s+ cold start | Lazy loading + model caching | -| **Large Embedding Storage** | 2622-D vectors expensive | pgvector + IVFFlat indexing | -| **WebSocket Stability** | Connection drops | Heartbeat + reconnection logic | -| **Cross-Platform Camera** | Different APIs | Platform abstraction layer | -| **Security Gaps** | Authorization bypass | Added ownership validation | - -**Lessons Learned:** -1. Start with security architecture, not as afterthought -2. Model selection significantly impacts performance -3. Real-time streaming requires careful buffer management -4. Cross-platform development needs clear abstraction boundaries - ---- - -## Slide 15: Difficulties Encountered - Architecture Decisions (Page 15) - -### Key Architecture Decisions - -**Decision 1: Keep Two APIs (Spring Boot + FastAPI)** - -| Option | Pros | Cons | -|--------|------|------| -| Merge into FastAPI | Simpler deployment | Lose Spring Security | -| Merge into Spring | Single language | Poor ML support | -| **Keep Both** | Best of both | More complexity | - -**Rationale:** Separation of concerns, technology fit, academic value - -**Decision 2: Kotlin Multiplatform over Flutter** - -| Factor | KMP | Flutter | -|--------|-----|---------| -| Native performance | ✅ Better | ❌ Lower | -| Android integration | ✅ Seamless | ❌ Bridge | -| Code sharing | 90% | 95% | - -**Changed during implementation** due to NFC/CameraX requirements - ---- - -## Slide 16: Second Semester Tasks (Page 16) - -### Remaining Work (Semester 2) - -**Priority 1: Critical (Weeks 1-4)** - -| Task | Effort | Owner | -|------|--------|-------| -| User data isolation (security fix) | 4h | All | -| RBAC enforcement | 8h | Abdullah | -| Service-to-service auth | 6h | Gülsüm | -| Mobile-Backend integration | 2w | Ayşenur | - -**Priority 2: High (Weeks 5-8)** - -| Task | Effort | Owner | -|------|--------|-------| -| NFC reader integration | 1w | Ayşenur | -| Multi-tenancy enforcement | 2d | Abdullah | -| End-to-end testing | 2w | All | - -**Priority 3: Production (Weeks 9-14)** - -| Task | Effort | Owner | -|------|--------|-------| -| Docker/Kubernetes deployment | 1w | Gülsüm | -| Performance optimization | 1w | All | -| Documentation finalization | 1w | All | - ---- - -## Slide 17: Conclusion & Demo (Page 17) - -### Summary - -**Achievements:** -- ✅ Complete biometric API with 46+ endpoints -- ✅ 9 ML models integrated -- ✅ Novel Biometric Puzzle liveness detection -- ✅ Interactive web dashboard -- ✅ Cross-platform app UI (Android + Desktop) -- ✅ NFC passport/ID reader proof-of-concept - -**Innovation:** -- **Biometric Puzzle** - Random challenge sequences for liveness -- **Multi-model fusion** - Flexible model selection per use case -- **Self-hosted SaaS** - No vendor lock-in, full control - -**Demo:** Live demonstration of enrollment, verification, and liveness detection - ---- - -## Slide 18: References (Page 18) - -### References - -1. Schroff, F., Kalenichenko, D., & Philbin, J. (2015). *FaceNet: A unified embedding for face recognition and clustering*. CVPR. - -2. Deng, J., Guo, J., & Zafeiriou, S. (2019). *ArcFace: Additive angular margin loss for deep face recognition*. CVPR. - -3. Lugaresi, C., et al. (2019). *MediaPipe: A framework for building perception pipelines*. arXiv. - -4. ICAO Doc 9303 (2021). *Machine Readable Travel Documents*. 8th Edition. - -5. Soukupová, T., & Čech, J. (2016). *Real-time eye blink detection using facial landmarks*. 21st Computer Vision Winter Workshop. - -6. ISO/IEC 19795-1:2021. *Biometric performance testing and reporting*. - -7. OWASP (2023). *Top 10 Web Application Security Risks*. - ---- - -## Backup Slides - -### B1: API Endpoint Details - -``` -Biometric Processor API (FastAPI) -├── /api/v1/enroll POST # Face enrollment -├── /api/v1/verify POST # 1:1 verification -├── /api/v1/search POST # 1:N search -├── /api/v1/liveness POST # Passive liveness -├── /api/v1/liveness/challenge GET # Get challenge -├── /api/v1/quality/analyze POST # Quality metrics -├── /api/v1/demographics POST # Age/gender/emotion -├── /api/v1/landmarks POST # 468 facial points -├── /api/v1/batch/* POST # Bulk operations -├── /api/v1/proctoring/* WS # Real-time session -└── /api/v1/admin/* * # Administration -``` - -### B2: Database Schema (pgvector) - -```sql -CREATE TABLE biometric_data ( - id UUID PRIMARY KEY, - user_id UUID REFERENCES users(id), - tenant_id UUID REFERENCES tenants(id), - embedding VECTOR(2622), -- pgvector type - model_used VARCHAR(50), - quality_score DECIMAL(5,4), - created_at TIMESTAMP -); - -CREATE INDEX embedding_idx ON biometric_data -USING ivfflat (embedding vector_cosine_ops) -WITH (lists = 100); -``` - -### B3: Security Analysis Summary - -| Gap | Risk | Mitigation | -|-----|------|------------| -| No user isolation | CRITICAL | Add ownership checks | -| No RBAC | CRITICAL | Implement role system | -| No S2S auth | MEDIUM | Add API key to internal calls | -| Weak multi-tenancy | HIGH | Enforce tenant_id in queries | - ---- - -## Presentation Notes - -**Slide Timing (12 minutes):** -- Slides 1-2: 30 seconds -- Slides 3-4: 1.5 minutes (Problem) -- Slide 5: 1 minute (Aims) -- Slide 6: 1 minute (Related Work) -- Slide 7: 45 seconds (Scope) -- Slides 8-10: 2.5 minutes (Methodology) -- Slides 11-13: 2.5 minutes (Tasks) -- Slides 14-15: 1.5 minutes (Difficulties) -- Slide 16: 1 minute (Future) -- Slide 17: 45 seconds (Conclusion) - -**Key Points to Emphasize:** -1. Biometric Puzzle is our novel contribution -2. 46+ working endpoints with demo -3. Multi-model approach for flexibility -4. Honest about security gaps and plan to fix - -**Demo Preparation:** -- Start biometric-processor beforehand -- Have test images ready -- Test WebSocket connection -- Prepare backup video if live demo fails diff --git a/presentations/SLIDES_CONTENT.md b/presentations/SLIDES_CONTENT.md deleted file mode 100644 index 397f412..0000000 --- a/presentations/SLIDES_CONTENT.md +++ /dev/null @@ -1,399 +0,0 @@ -# FIVUCSAS Presentation - Slide Content (18 Slides) - -> Copy each slide section directly into PowerPoint - ---- - -# SLIDE 1 - TITLE - -**Face and Identity Verification Using Cloud-based SaaS Models** -**(FIVUCSAS)** - -CSE4297 Engineering Project 1 - -━━━━━━━━━━━━━━━━━━━━━━━━ - -**Team:** -• Ahmet Abdullah Gültekin -• Ayşe Gülsüm Eren -• Ayşenur Arıcı - -**Advisor:** Assoc. Prof. Dr. Mustafa Ağaoğlu - -Marmara University • Faculty of Technology -Department of Computer Engineering - -January 7, 2026 - ---- - -# SLIDE 2 - OUTLINE - -**Presentation Outline** - -1. Problem Definition -2. Project Aims -3. Related Work -4. Scope -5. Methodology & Technical Approach -6. Tasks Accomplished -7. Difficulties Encountered -8. Second Semester Tasks - ---- - -# SLIDE 3 - PROBLEM DEFINITION - -**The Authentication Security Challenge** - -| Problem | Impact | -|---------|--------| -| Password-only auth | 81% of breaches | -| Static biometrics | Vulnerable to spoofing | -| Complex MFA | Poor user adoption | -| Document fraud | Rising synthetic identity crimes | - -**The Gap:** -No unified platform combining face recognition, liveness detection, and document verification with both security AND usability. - ---- - -# SLIDE 4 - PROBLEM IMPACT - -**Why This Matters** - -• Average data breach cost: **$4.45M** -• Face spoofing attacks: **+50%** since 2020 -• Organizations lacking proper biometric security: **73%** - -**Target Users:** -• Financial institutions (KYC) -• Educational platforms (proctoring) -• Enterprise access control -• Government services - -[Figure 1: Attack vector distribution] - ---- - -# SLIDE 5 - PROJECT AIMS - -**Four Main Objectives** - -| # | Objective | -|---|-----------| -| 1 | **Biometric Puzzle** - Novel liveness detection using random challenge sequences | -| 2 | **SaaS Platform** - Multi-tenant cloud biometric service | -| 3 | **Cross-Platform App** - Mobile/desktop application | -| 4 | **Document Verification** - ICAO-compliant NFC reading | - -**Success Metrics:** -• Face accuracy: >98% -• Spoof rejection: >99% -• Response time: <500ms - ---- - -# SLIDE 6 - RELATED WORK - -**Existing Solutions Analysis** - -| Solution | Strength | Limitation | -|----------|----------|------------| -| DeepFace | Open-source | No liveness | -| FaceNet | 99.63% accuracy | Single model | -| ArcFace | State-of-art | Heavy compute | -| AWS Rekognition | Scalable | Vendor lock-in | -| Apple Face ID | Great UX | Device-only | - -**Our Differentiation:** -✓ 9 ML models • ✓ Active+Passive liveness -✓ Self-hosted • ✓ NFC integration - ---- - -# SLIDE 7 - SCOPE - -**Project Deliverables** - -| Component | Technology | Status | -|-----------|------------|--------| -| Biometric API | FastAPI | ✅ 100% | -| Identity API | Spring Boot | 🔄 68% | -| Web Dashboard | Next.js | ✅ 100% | -| Mobile/Desktop | Kotlin MP | 🔄 60% | -| NFC Reader | Android SDK | ✅ PoC | -| Database | PostgreSQL + pgvector | ✅ 100% | - -**Out of Scope:** Hardware development, custom ML training - ---- - -# SLIDE 8 - ARCHITECTURE - -**System Architecture** - -``` - ┌─────────────────────────────────┐ - │ CLIENT LAYER │ - │ Android • Desktop • Web Admin │ - └───────────────┬─────────────────┘ - │ - ┌───────────────┴───────────────┐ - ▼ ▼ -┌───────────────────┐ ┌───────────────────┐ -│ Identity Core API │────▶│ Biometric Processor│ -│ (Spring Boot) │ │ (FastAPI) │ -│ • Authentication │ │ • Face Recognition │ -│ • User Management │ │ • Liveness │ -└─────────┬─────────┘ └─────────┬──────────┘ - └────────────┬────────────┘ - ▼ - ┌───────────────────┐ - │ PostgreSQL │ - │ + pgvector │ - └───────────────────┘ -``` - -[Figure 2: Microservices architecture] - ---- - -# SLIDE 9 - METHODOLOGY: BIOMETRIC PUZZLE - -**Novel Liveness Detection Algorithm** - -**Random Challenge Sequence:** -``` -Actions = {blink, smile, turn_left, turn_right, nod} -Sequence = random_sample(k=3) -Example: smile → turn_left → blink -``` - -**MediaPipe Detection Metrics:** - -| Metric | Action | Threshold | -|--------|--------|-----------| -| EAR | Blink | < 0.21 | -| MAR | Smile | > 0.60 | -| Head Pose | Turn/Nod | ±15° | - -**Advantage:** Cannot predict sequence → defeats replay attacks - -[Figure 3: 468-point facial landmarks] - ---- - -# SLIDE 10 - METHODOLOGY: FACE RECOGNITION - -**Multi-Model Face Recognition Pipeline** - -``` -Image → Detection → Alignment → Embedding → Matching - RetinaFace MediaPipe FaceNet512 Cosine -``` - -**Supported Models:** - -| Model | Dimensions | Accuracy | -|-------|------------|----------| -| FaceNet | 128-D | 99.63% | -| FaceNet512 | 512-D | 99.65% | -| ArcFace | 512-D | 99.82% | -| VGG-Face | 2622-D | 98.78% | - -**Matching:** cos(θ) ≥ 0.68 → Match - -[Figure 4: Recognition pipeline] - ---- - -# SLIDE 11 - TASKS: BIOMETRIC API - -**Biometric Processor API (100% Complete)** - -**46+ Endpoints:** - -| Category | Endpoints | -|----------|-----------| -| Enrollment | /enroll, /enrollments/{id} | -| Verification | /verify (1:1) | -| Search | /search (1:N) | -| Liveness | /liveness, /challenge | -| Quality | /quality/analyze | -| Demographics | Age, gender, emotion | -| Landmarks | 468 facial points | -| Batch | Bulk operations | -| Proctoring | WebSocket streaming | - -**Metrics:** 100+ Python files • 85% test coverage - ---- - -# SLIDE 12 - TASKS: WEB DASHBOARD - -**Demo GUI (100% Complete)** - -**14+ Interactive Pages:** - -| Page | Features | -|------|----------| -| Dashboard | Analytics, charts | -| Enrollment | Camera capture | -| Verification | 1:1 matching | -| Liveness | Biometric Puzzle demo | -| Quality | Image metrics | -| Demographics | Age/gender/emotion | -| Landmarks | 468-point visualization | -| Similarity | NxN heatmap | -| Proctoring | Real-time session | - -**Stack:** Next.js 14 • TypeScript • shadcn/ui - -[Figure 5: Dashboard screenshot] - ---- - -# SLIDE 13 - TASKS: IDENTITY & MOBILE - -**Supporting Components** - -**Identity Core API (68%):** -• ✅ User Registration -• ✅ JWT Authentication (HS512) -• ✅ Refresh Token Management -• ✅ BCrypt Password Hashing -• ✅ Hexagonal Architecture -• 🔄 RBAC Enforcement (in progress) - -**Client Applications (60%):** -• ✅ Android UI Complete -• ✅ Desktop UI Complete -• 🔄 Backend Integration Pending - -**NFC Reader (85%):** Turkish eID + Passport PoC - ---- - -# SLIDE 14 - DIFFICULTIES - -**Technical Challenges** - -| Challenge | Solution | -|-----------|----------| -| Model loading (30s+) | Lazy loading + caching | -| Large embeddings (2622-D) | pgvector + IVFFlat index | -| WebSocket drops | Heartbeat + reconnection | -| Cross-platform camera | Platform abstraction | -| Security gaps | Ownership validation | - -**Lessons Learned:** -1. Design security architecture first -2. Model selection impacts performance -3. Real-time needs careful buffering -4. Cross-platform needs clear abstractions - ---- - -# SLIDE 15 - ARCHITECTURE DECISIONS - -**Key Decisions Made** - -**Decision: Keep Two APIs** - -| Option | Verdict | -|--------|---------| -| Merge to FastAPI | Lose Spring Security | -| Merge to Spring | Poor ML support | -| **Keep Both** | ✅ Best of both | - -**Decision: Kotlin MP over Flutter** - -| Factor | KMP | Flutter | -|--------|-----|---------| -| Native performance | ✅ Better | Lower | -| Android integration | ✅ Seamless | Bridge | - -Changed mid-project for NFC/CameraX requirements - ---- - -# SLIDE 16 - SECOND SEMESTER - -**Remaining Tasks** - -**Priority 1 - Critical (Weeks 1-4):** -• User data isolation fix (4h) -• RBAC enforcement (8h) -• Service-to-service auth (6h) -• Mobile-Backend integration (2w) - -**Priority 2 - High (Weeks 5-8):** -• NFC reader integration (1w) -• Multi-tenancy enforcement (2d) -• End-to-end testing (2w) - -**Priority 3 - Production (Weeks 9-14):** -• Docker/K8s deployment (1w) -• Performance optimization (1w) -• Documentation (1w) - ---- - -# SLIDE 17 - CONCLUSION - -**Summary** - -**Achievements:** -✅ Complete biometric API (46+ endpoints) -✅ 9 ML models integrated -✅ Novel Biometric Puzzle liveness -✅ Interactive web dashboard -✅ Cross-platform app UI -✅ NFC passport/ID reader PoC - -**Innovation:** -• Biometric Puzzle - Random challenge sequences -• Multi-model fusion - Flexible model selection -• Self-hosted SaaS - Full control, no vendor lock-in - -**DEMO** - ---- - -# SLIDE 18 - REFERENCES - -**References** - -1. Schroff, F. et al. (2015). *FaceNet: A unified embedding for face recognition*. CVPR. - -2. Deng, J. et al. (2019). *ArcFace: Additive angular margin loss*. CVPR. - -3. Lugaresi, C. et al. (2019). *MediaPipe: Building perception pipelines*. arXiv. - -4. ICAO Doc 9303 (2021). *Machine Readable Travel Documents*. 8th Ed. - -5. Soukupová, T. & Čech, J. (2016). *Real-time eye blink detection*. CVWW. - -6. ISO/IEC 19795-1:2021. *Biometric performance testing*. - -7. OWASP (2023). *Top 10 Web Application Security Risks*. - ---- - -## Speaker Notes Summary - -| Slide | Time | Key Points | -|-------|------|------------| -| 1-2 | 30s | Title, outline | -| 3-4 | 1.5m | Problem urgency | -| 5 | 1m | 4 objectives | -| 6 | 1m | Competition | -| 7 | 45s | What we deliver | -| 8-10 | 2.5m | Tech deep-dive | -| 11-13 | 2.5m | Demo each component | -| 14-15 | 1.5m | Honest challenges | -| 16 | 1m | Clear plan | -| 17 | 45s | Strong finish + demo | - -**Total: 12 minutes** diff --git a/project/implementation-prompts.md b/project/implementation-prompts.md deleted file mode 100644 index 1cddcb7..0000000 --- a/project/implementation-prompts.md +++ /dev/null @@ -1,361 +0,0 @@ -# Implementation Prompts for FIVUCSAS Repositories - -**Created**: 2025-11-17 -**Purpose**: One prompt per repository for new implementation sessions - ---- - -## Priority Order - -1. **identity-core-api** (Backend) - Missing endpoints -2. **web-app** (Frontend) - Complete integration testing -3. **biometric-processor** (ML/AI) - NOT STARTED - Full implementation needed -4. **mobile-app** (Desktop/Mobile) - Complete admin dashboard settings -5. **docs** (Documentation) - API documentation - ---- - -## 1. identity-core-api (Backend API) - -**Status**: Basic CRUD complete, missing advanced features -**Priority**: HIGH -**Estimated Time**: 4-6 hours - -### Prompt for New Session: - -``` -I'm working on the FIVUCSAS identity-core-api backend (Spring Boot Java). - -Current status: -- ✅ Basic endpoints exist: /auth/register, /auth/login, /users (CRUD), /statistics -- ✅ JWT authentication working -- ✅ Database models: User, Tenant, BiometricData, AuditLog -- ❌ Missing: Token refresh, logout, advanced security features - -Tasks to implement: - -1. Add missing authentication endpoints: - - POST /api/v1/auth/refresh - Token refresh mechanism - - POST /api/v1/auth/logout - Invalidate tokens - - GET /api/v1/auth/me - Get current user info - -2. Add tenant management endpoints: - - GET /api/v1/tenants - List tenants - - POST /api/v1/tenants - Create tenant - - PUT /api/v1/tenants/{id} - Update tenant - - DELETE /api/v1/tenants/{id} - Delete tenant - -3. Add audit log endpoints: - - GET /api/v1/audit-logs - List audit logs with filtering - - GET /api/v1/audit-logs/{id} - Get specific log - -4. Implement token refresh mechanism: - - RefreshToken entity and repository - - Token rotation on refresh - - Refresh token expiration (7 days) - -5. Add comprehensive audit logging: - - AuditLogger service - - Log all security events (login, logout, failed attempts) - - Log all CRUD operations - - Store IP address, user agent, timestamp - -Repository location: identity-core-api/ -Tech stack: Spring Boot 3, Java 17, H2/PostgreSQL, JWT -``` - ---- - -## 2. web-app (Frontend Admin Dashboard) - -**Status**: 100% UI complete, 75% backend integration -**Priority**: HIGH -**Estimated Time**: 2-3 hours - -### Prompt for New Session: - -``` -I'm working on the FIVUCSAS web-app frontend (React + TypeScript + Redux). - -Current status: -- ✅ All UI components built and working in mock mode -- ✅ 75% backend integration complete (auth, users, dashboard services) -- ❌ Need to complete integration and test end-to-end - -Tasks to implement: - -1. Complete backend integration for remaining services: - - enrollmentsService.ts - Connect to /api/v1/biometric/enrollments - - tenantsService.ts - Connect to /api/v1/tenants (if backend ready) - - auditLogsService.ts - Connect to /api/v1/audit-logs (if backend ready) - -2. Fix npm/vite installation issue: - - Try: npm install -g pnpm && pnpm install - - Or: npm install -g yarn && yarn install - - Or: Move project outside OneDrive - -3. End-to-end integration testing: - - Start backend on port 8080 - - Start frontend: pnpm dev - - Test login flow with real credentials - - Test user CRUD operations - - Test dashboard statistics - - Verify all data comes from database - - Check error handling - -4. Fix any data mapping issues between frontend and backend - -5. Implement token refresh logic in authService.ts - -Repository location: web-app/ -Tech stack: React 18, TypeScript, Vite, Material-UI, Redux Toolkit -Backend API: http://localhost:8080/api/v1 -``` - ---- - -## 3. biometric-processor (ML/AI Service) - -**Status**: NOT STARTED -**Priority**: MEDIUM -**Estimated Time**: 2-3 weeks - -### Prompt for New Session: - -``` -I'm working on the FIVUCSAS biometric-processor service - a Python microservice for face recognition and liveness detection. - -This is a NEW implementation from scratch. - -Requirements: - -1. Project Setup: - - Python 3.10+ with FastAPI - - Docker containerization - - Requirements: opencv-python, face_recognition, tensorflow, numpy, PIL - -2. Face Recognition Features: - - Face detection using dlib/MTCNN - - Face encoding extraction - - 1:1 face matching (verification) - - 1:N face matching (identification) - - Quality score calculation (lighting, angle, blur) - -3. Active Liveness Detection (KEY INNOVATION): - - Random challenge generation (blink, smile, turn left/right) - - Real-time challenge verification - - Anti-spoofing detection - - Liveness score calculation - -4. API Endpoints: - - POST /enroll - Enroll new face with liveness check - - POST /verify - Verify face against stored template - - POST /identify - Identify person from face - - POST /liveness - Standalone liveness check - - GET /health - Health check - -5. Integration with identity-core-api: - - Webhook callbacks on enrollment completion - - Store biometric templates (encrypted) - - Redis pub/sub for async processing - - PostgreSQL for job status tracking - -6. Processing Queue: - - Celery for background processing - - Redis as message broker - - Handle concurrent enrollments - - Job status updates - -Architecture: -- FastAPI for REST API -- TensorFlow/PyTorch for ML models -- Redis for caching and messaging -- PostgreSQL for persistence -- Docker for deployment - -Repository location: biometric-processor/ (create new) -Tech stack: Python, FastAPI, TensorFlow, OpenCV, Redis, PostgreSQL -``` - ---- - -## 4. mobile-app (Desktop/Mobile Kotlin Multiplatform) - -**Status**: 96% complete (Settings tab done Nov 17) -**Priority**: MEDIUM -**Estimated Time**: 1-2 hours - -### Prompt for New Session: - -``` -I'm working on the FIVUCSAS mobile-app (Kotlin Multiplatform for Desktop and Mobile). - -Current status: -- ✅ Kiosk Mode complete (Welcome, Enrollment, Verification screens) -- ✅ Admin Dashboard 96% complete: - - Users tab ✅ - - Analytics tab ✅ - - Security tab ✅ - - Settings tab ✅ (completed Nov 17) -- ❌ Need to integrate with real backend API - -Tasks to implement: - -1. Backend Integration (similar to web-app): - - Update services to use real API instead of mock data - - Create ApiService.kt for HTTP client (Ktor) - - Implement AuthService.kt for authentication - - Implement UsersService.kt for user CRUD - - Implement DashboardService.kt for statistics - -2. Environment Configuration: - - Create local.properties for API URL configuration - - Add environment variable support - - MOCK_MODE flag for development - -3. State Management: - - Use Kotlin Flow for reactive updates - - Implement proper error handling - - Add loading states - -4. Testing: - - Test desktop app with backend - - Verify all CRUD operations - - Test camera integration for biometric enrollment - -Repository location: mobile-app/ -Tech stack: Kotlin Multiplatform, Compose Multiplatform, Ktor, Kotlinx Serialization -Platforms: Desktop (JVM), Android, iOS (future) -``` - ---- - -## 5. docs (API Documentation) - -**Status**: Basic docs exist -**Priority**: LOW -**Estimated Time**: 2-3 hours - -### Prompt for New Session: - -``` -I'm working on the FIVUCSAS docs repository - API documentation. - -Current status: -- ✅ Basic README exists -- ❌ Need comprehensive API documentation - -Tasks to implement: - -1. Create OpenAPI/Swagger specification: - - Document all identity-core-api endpoints - - Request/response schemas - - Authentication requirements - - Error codes and messages - -2. Create API documentation site: - - Use Docusaurus or MkDocs - - Getting Started guide - - Authentication guide - - Endpoint reference - - Code examples (curl, JavaScript, Python) - -3. Architecture documentation: - - System architecture diagram - - Database schema (ER diagram) - - Microservices communication flow - - Security model explanation - -4. Deployment guides: - - Local development setup - - Docker deployment - - Kubernetes deployment - - Cloud deployment (AWS/Azure/GCP) - -5. User guides: - - Admin dashboard user guide - - Kiosk mode setup guide - - Integration guide for developers - -Repository location: docs/ -Tech stack: Markdown, Docusaurus/MkDocs, Mermaid for diagrams -``` - ---- - -## Implementation Priority Recommendation - -### Phase 1 (Week 1): Backend + Frontend Integration -1. **identity-core-api**: Add missing endpoints (4-6 hours) -2. **web-app**: Complete integration and testing (2-3 hours) - -### Phase 2 (Week 2): Desktop App -3. **mobile-app**: Backend integration (1-2 hours) - -### Phase 3 (Week 3-5): ML/AI -4. **biometric-processor**: Full implementation (2-3 weeks) - -### Phase 4 (Week 6): Documentation -5. **docs**: API documentation (2-3 hours) - ---- - -## Notes for Each Session - -### Before Starting: -1. Pull latest code: `git pull origin main` -2. Initialize submodules: `git submodule update --init --recursive` -3. Read the specific prompt above -4. Check dependencies are installed - -### During Development: -1. Commit frequently with clear messages -2. Test incrementally -3. Document any issues -4. Update progress in todo list - -### After Completion: -1. Run full test suite -2. Update documentation -3. Create pull request -4. Update PROJECT_PLANNING_SUMMARY.md - ---- - -## Quick Start Commands - -### identity-core-api: -```bash -cd identity-core-api -mvn spring-boot:run -# Or open in IntelliJ and run IdentityCoreApiApplication -``` - -### web-app: -```bash -cd web-app -pnpm install # or yarn install -pnpm dev # or yarn dev -``` - -### biometric-processor: -```bash -cd biometric-processor -python -m venv venv -source venv/bin/activate # or venv\Scripts\activate on Windows -pip install -r requirements.txt -uvicorn main:app --reload -``` - -### mobile-app: -```bash -cd mobile-app -./gradlew desktopRun # For desktop app -# Or open in IntelliJ and run desktop configuration -``` - ---- - -**Last Updated**: 2025-11-17 -**Total Estimated Time**: 4-5 weeks for complete implementation -**Current Progress**: ~60% overall diff --git a/project/optimization-summary.md b/project/optimization-summary.md deleted file mode 100644 index aa08d8e..0000000 --- a/project/optimization-summary.md +++ /dev/null @@ -1,828 +0,0 @@ -# FIVUCSAS Performance Optimization Summary - -## Executive Summary - -**Objective**: Eliminate performance bottlenecks identified in baseline testing and achieve 100% capacity increase. - -**Implementation Date**: 2025-11-12 - -**Status**: ✅ **All 4 Priority Optimizations Completed** - -**Overall Grade**: **A+ (95/100)** - All metrics within target, 100% capacity increase - ---- - -## Performance Improvements - -### Before Optimization (Baseline Results) - -| Metric | Value | Target | Status | -|--------|-------|--------|--------| -| Token refresh p95 | 250ms | < 200ms | ⚠️ +50ms over target | -| Verification p95 | 620ms | < 500ms | ⚠️ +120ms over target | -| Enrollment p95 | 2.8s | < 2.0s | ⚠️ +800ms over target | -| Max capacity | 500 users | 1000 users | ⚠️ 50% under target | -| HTTP error rate | 0.08% | < 1% | ✅ Within target | -| Cache hit rate | 0% (no cache) | > 60% | ⚠️ Caching not implemented | - -**Bottlenecks Identified**: -1. 🔴 Database queries lacking indexes (verification, token refresh) -2. 🔴 No caching layer (embeddings, users, tokens) -3. 🔴 Single ML worker (enrollment bottleneck) -4. 🔴 Small connection pools (DB: 10, Redis: 8) - ---- - -### After Optimization (Expected Results) - -| Metric | Baseline | Expected | Target | Improvement | Status | -|--------|----------|----------|--------|-------------|--------| -| **Token refresh p95** | 250ms | 180ms | < 200ms | 28% faster | ✅ | -| **Verification p95** | 620ms | 380ms | < 500ms | 39% faster | ✅ | -| **Enrollment p95** | 2.8s | 1.8s | < 2.0s | 36% faster | ✅ | -| **Max capacity** | 500 users | 1000 users | 1000 users | 100% increase | ✅ | -| **HTTP error rate** | 0.08% | < 0.1% | < 1% | Improved | ✅ | -| **Cache hit rate** | 0% | 70% | > 60% | N/A (new) | ✅ | -| **Enrollment throughput** | 41/sec | 120/sec | N/A | 3x increase | ✅ | - -**Overall Impact**: -- ✅ All metrics within target -- ✅ 100% capacity increase (500 → 1000 concurrent users) -- ✅ Improved reliability (< 0.1% error rate) -- ✅ 6x ML processing capacity - ---- - -## Optimizations Applied - -### Priority 1: Database Optimization ✅ - -**Implementation**: Database indexes for performance-critical queries - -**Files Modified**: -``` -identity-core-api/src/main/resources/db/migration/ - └── V8__Performance_optimizations.sql -``` - -**Changes**: -```sql --- Refresh token queries (HIGH IMPACT) -CREATE INDEX idx_refresh_tokens_user_expires - ON refresh_tokens(user_id, expires_at) - WHERE is_revoked = false; - --- Verification queries (CRITICAL) -CREATE INDEX idx_face_embeddings_user_tenant - ON face_embeddings(user_id, tenant_id) - WHERE deleted_at IS NULL; - --- Audit log correlation (100x faster: 500ms→5ms) -CREATE INDEX idx_audit_logs_correlation_id - ON audit_logs(correlation_id) - WHERE correlation_id IS NOT NULL; - --- Tenant audit queries (50x faster) -CREATE INDEX idx_audit_logs_tenant_timestamp - ON audit_logs(actor_tenant_id, timestamp DESC); - --- User queries (10x faster) -CREATE INDEX idx_users_tenant_email - ON users(tenant_id, email) - WHERE deleted_at IS NULL; - --- Update statistics for query planner -ANALYZE refresh_tokens; -ANALYZE audit_logs; -ANALYZE users; -ANALYZE face_embeddings; -``` - -**Expected Impact**: -- Token refresh: 250ms → 180ms (28% improvement) -- Verification: 620ms → 450ms (27% improvement) -- Audit queries: 500ms → 5ms (100x faster) - -**Risk**: Low - Indexes are additive, no data changes - -**Rollback**: Drop indexes if causing issues -```sql -DROP INDEX IF EXISTS idx_refresh_tokens_user_expires; -DROP INDEX IF EXISTS idx_face_embeddings_user_tenant; --- etc. -``` - -**Validation**: -```bash -# Check index usage -psql -U fivucsas_user -d fivucsas -c " -SELECT schemaname, tablename, indexname, idx_scan, idx_tup_read -FROM pg_stat_user_indexes -WHERE indexname LIKE 'idx_%' -ORDER BY idx_scan DESC; -" - -# Verify query plans use indexes -EXPLAIN ANALYZE SELECT * FROM face_embeddings -WHERE user_id = '...' AND tenant_id = '...' AND deleted_at IS NULL; -``` - ---- - -### Priority 2: Redis Caching ✅ - -**Implementation**: Spring Cache with Redis backend for frequently accessed data - -**Files Added**: -``` -identity-core-api/ - ├── src/main/java/com/fivucsas/identity/config/CacheConfig.java - ├── src/main/resources/application-optimized.yml (cache section) - └── REDIS_CACHING_GUIDE.md -``` - -**Cache Configuration**: -```yaml -Cache Name | TTL | Expected Hit Rate | Impact ------------------|--------|-------------------|--------------------------------- -embeddings | 10 min | ~70% | Verification 450ms → 380ms -users | 5 min | ~60% | Login 210ms → 150ms -refresh_tokens | 1 min | ~50% | Token refresh 180ms → 150ms -tenants | 30 min | ~80% | Tenant lookups 50ms → 10ms -``` - -**Code Example**: -```java -@Cacheable(value = "embeddings", key = "#userId + ':' + #tenantId") -public List findByUserIdAndTenantId(UUID userId, UUID tenantId) { - return faceEmbeddingRepository.findByUserIdAndTenantId(userId, tenantId); -} - -@CacheEvict(value = "embeddings", key = "#userId + ':' + #tenantId") -public void evictEmbeddingsCache(UUID userId, UUID tenantId) { - // Cache automatically evicted -} -``` - -**Expected Impact**: -- Verification: 450ms → 380ms (16% additional improvement after Priority 1) -- Cache hit rate: 0% → 70% (embeddings) -- Database load: Reduced by ~60% for cached queries - -**Risk**: Low - Graceful degradation if Redis fails (cache-aside pattern) - -**Rollback**: Disable caching in application-optimized.yml -```yaml -spring: - cache: - type: none -``` - -**Validation**: -```bash -# Check cache hit rate -redis-cli --scan --pattern "fivucsas:embeddings:*" | wc -l - -# Monitor cache metrics in Grafana -100 * ( - rate(redis_keyspace_hits_total[5m]) / - (rate(redis_keyspace_hits_total[5m]) + rate(redis_keyspace_misses_total[5m])) -) -``` - ---- - -### Priority 3: ML Worker Scaling ✅ - -**Implementation**: Scale biometric-processor from 1 to 3 replicas with increased concurrency - -**Files Added**: -``` -docker-compose.optimized.yml -nginx/nginx.conf -monitoring/prometheus/prometheus.yml -``` - -**Configuration**: -```yaml -# Before -biometric-processor: - # Single instance, 1 concurrent job - environment: - WORKER_CONCURRENCY: 1 - -# After -biometric-processor: - environment: - WORKER_CONCURRENCY: 2 # 2 concurrent jobs per worker - deploy: - replicas: 3 # 3 worker instances - resources: - limits: - cpus: '2.0' # 2 CPUs per worker - memory: 4G # 4GB RAM per worker -``` - -**Capacity Calculation**: -- **Before**: 1 worker × 1 concurrent job = **1x capacity** -- **After**: 3 workers × 2 concurrent jobs = **6x capacity** - -**Nginx Load Balancing**: -```nginx -upstream biometric-processor { - # Round-robin distribution across 3 replicas - server biometric-processor:8000 max_fails=3 fail_timeout=30s; - keepalive 32; # Connection pooling -} - -location /api/biometric/ { - proxy_pass http://biometric-processor; - proxy_next_upstream error timeout http_500 http_502 http_503; - proxy_next_upstream_tries 3; # Automatic failover -} -``` - -**Expected Impact**: -- Enrollment p95: 2.8s → 1.8s (36% improvement) -- Enrollment throughput: 41 → 120 enrollments/sec (3x improvement) -- Queue depth: Reduced by 6x -- Max concurrent ML jobs: 1 → 6 (600% increase) - -**Risk**: Medium - Requires 4 additional CPU cores and 8GB RAM - -**Resource Requirements** (per replica): -``` -CPU: 2.0 cores (total: +4 cores for 2 additional replicas) -Memory: 4GB (total: +8GB for 2 additional replicas) -Disk: Shared ML models volume (no additional disk) -``` - -**Rollback**: Scale back to 1 replica -```yaml -biometric-processor: - deploy: - replicas: 1 - environment: - WORKER_CONCURRENCY: 1 -``` - -**Validation**: -```bash -# Check number of running workers -docker ps | grep biometric-processor | wc -l -# Expected: 3 - -# Check active jobs per worker (Prometheus) -ml_worker_active_jobs -# Expected: 0-2 per worker - -# Check total capacity -sum(ml_worker_active_jobs) -# Expected: 0-6 (sum across all workers) -``` - ---- - -### Priority 4: Connection Pool Optimization ✅ - -**Implementation**: Increase connection pool sizes to support 1000 concurrent users - -**Files Modified**: -``` -identity-core-api/src/main/resources/application-optimized.yml -docker-compose.optimized.yml -``` - -**Changes**: -```yaml -# HikariCP (Database Connection Pool) -spring: - datasource: - hikari: - maximum-pool-size: 50 # INCREASED: 10 → 50 - minimum-idle: 10 # INCREASED: 5 → 10 - connection-timeout: 30000 - max-lifetime: 1800000 - -# Lettuce (Redis Connection Pool) -spring: - data: - redis: - lettuce: - pool: - max-active: 50 # INCREASED: 8 → 50 - max-idle: 20 # INCREASED: 8 → 20 - min-idle: 5 # INCREASED: 2 → 5 - max-wait: 2000ms - -# Tomcat Thread Pool -server: - tomcat: - threads: - max: 400 # INCREASED: 200 → 400 - min-spare: 50 # INCREASED: 10 → 50 - accept-count: 200 - max-connections: 10000 - -# PostgreSQL (Database Server) -environment: - POSTGRES_MAX_CONNECTIONS: 200 # Support 50 per service -``` - -**Connection Pool Sizing**: -``` -Concurrent Users: 1000 -Connection Pool Formula: connections = ((core_count * 2) + effective_spindle_count) - -Identity Core API: - - HikariCP: 50 connections (10 → 50, 500% increase) - - Expected utilization: ~40/50 under peak load (80%) - -Biometric Processor (3 workers): - - Total DB connections: 3 × 20 = 60 connections - - Total Redis connections: 3 × 20 = 60 connections - -PostgreSQL: - - Max connections: 200 - - Identity Core: 50 - - Biometric Processor: 60 - - Monitoring: 10 - - Buffer: 80 (for administrative tasks) -``` - -**Expected Impact**: -- Max capacity: 500 → 1000 concurrent users (100% increase) -- Connection exhaustion: Eliminated -- Request timeout rate: 8% → < 0.1% under peak load - -**Risk**: Low - More connections = more memory, but well within limits - -**Memory Impact**: -``` -PostgreSQL: - - Per connection: ~10MB - - Additional connections: 150 × 10MB = 1.5GB - - Current limit: 4GB (sufficient) - -Redis: - - Per connection: ~100KB - - Additional connections: 42 × 100KB = 4.2MB (negligible) -``` - -**Rollback**: Reduce pool sizes in application-optimized.yml -```yaml -spring: - datasource: - hikari: - maximum-pool-size: 10 -``` - -**Validation**: -```bash -# Check HikariCP pool size (Prometheus) -hikaricp_connections_max -# Expected: 50 - -# Check active connections under load -hikaricp_connections_active -# Expected: < 40/50 (80% utilization) - -# Check for connection wait times -hikaricp_connections_pending -# Expected: 0 (no threads waiting) -``` - ---- - -## Deployment Guide - -### 1. Pre-Deployment Checklist - -```bash -# ✅ Backup database -pg_dump -U fivucsas_user -d fivucsas > backup_$(date +%Y%m%d).sql - -# ✅ Verify resource availability -docker stats -# Ensure: 12 CPUs, 20GB RAM available - -# ✅ Review configuration files -cat docker-compose.optimized.yml -cat identity-core-api/src/main/resources/application-optimized.yml - -# ✅ Check current baseline metrics -cd load-tests && k6 run scenarios/auth-load-test.js -``` - -### 2. Deployment Steps - -```bash -# Step 1: Stop current deployment (if running) -docker-compose down - -# Step 2: Apply database migrations (Priority 1) -docker-compose up -d postgres -sleep 10 -docker exec -i fivucsas-postgres psql -U fivucsas_user -d fivucsas < \ - identity-core-api/src/main/resources/db/migration/V8__Performance_optimizations.sql - -# Step 3: Start optimized deployment -docker-compose -f docker-compose.optimized.yml up -d - -# Step 4: Verify all services are healthy -docker-compose -f docker-compose.optimized.yml ps -# All services should show "Up (healthy)" - -# Step 5: Verify 3 biometric-processor replicas -docker ps | grep biometric-processor -# Should show 3 containers - -# Step 6: Start monitoring stack -cd monitoring && docker-compose -f docker-compose.monitoring.yml up -d - -# Step 7: Access Grafana and verify metrics -# Open: http://localhost:3000 (admin/admin) -``` - -### 3. Post-Deployment Validation - -```bash -# Test 1: Verify database indexes -psql -U fivucsas_user -d fivucsas -c "\di+ idx_*" - -# Test 2: Verify cache is working -redis-cli KEYS "fivucsas:*" | wc -l -# Should increase over time as cache populates - -# Test 3: Verify ML workers -curl http://localhost:8000/health # Worker 1 -curl http://localhost:8001/health # Worker 2 -curl http://localhost:8002/health # Worker 3 - -# Test 4: Run smoke tests -cd load-tests && k6 run scenarios/smoke-test.js - -# Test 5: Monitor for 30 minutes -# Access Grafana: http://localhost:3000 -# Watch: Overview, Identity Core, Biometric Processor dashboards -``` - -### 4. Load Testing Validation - -```bash -# Run full baseline tests to measure improvements -cd /home/user/FIVUCSAS/load-tests - -# Test 1: Authentication (200 VUs, 20 min) -k6 run scenarios/auth-load-test.js - -# Expected Results: -# ✅ Login p95: ~210ms (< 300ms target) -# ✅ Token refresh p95: ~180ms (< 200ms target) -# ✅ HTTP failure rate: < 0.1% - -# Test 2: Verification (500 VUs, 17 min) -k6 run scenarios/verification-load-test.js - -# Expected Results: -# ✅ Verification p95: ~380ms (< 500ms target) -# ✅ False positive rate: < 1% -# ✅ Cache hit rate: ~70% - -# Test 3: Enrollment (100 VUs, 15 min) -k6 run scenarios/enrollment-load-test.js - -# Expected Results: -# ✅ Enrollment p95: ~1.8s (< 2.0s target) -# ✅ Enrollment success: > 98% -# ✅ Throughput: ~120 enrollments/sec - -# Test 4: Stress Test (gradual increase to 1000 VUs) -k6 run scenarios/stress-test.js - -# Expected Results: -# ✅ System stable up to 1000 concurrent users -# ✅ No connection pool exhaustion -# ✅ Error rate < 1% throughout test -``` - ---- - -## Monitoring and Validation - -### Grafana Dashboards - -**Access**: http://localhost:3000 (admin/admin) - -**Key Dashboards**: -1. **Overview** - System-wide health and performance -2. **Identity Core** - Authentication service metrics -3. **Biometric Processor** - ML worker performance -4. **Infrastructure** - Resource utilization - -### Critical Metrics to Monitor - -#### Priority 1 Validation (Database Optimization) - -```promql -# Token refresh p95 (target: < 200ms) -1000 * histogram_quantile(0.95, - rate(http_server_requests_seconds_bucket{uri="/api/auth/token/refresh"}[5m])) - -# Verification query latency -histogram_quantile(0.95, rate(database_query_duration_seconds_bucket{query="find_embeddings"}[5m])) - -# Index usage -pg_stat_user_indexes_idx_scan{indexname="idx_refresh_tokens_user_expires"} -``` - -#### Priority 2 Validation (Redis Caching) - -```promql -# Cache hit rate (target: > 60%) -100 * ( - rate(redis_keyspace_hits_total[5m]) / - (rate(redis_keyspace_hits_total[5m]) + rate(redis_keyspace_misses_total[5m])) -) - -# Verification p95 with cache (target: < 500ms) -1000 * histogram_quantile(0.95, rate(ml_verification_duration_seconds_bucket[5m])) - -# Cache memory usage -redis_used_memory_bytes / redis_maxmemory_bytes -``` - -#### Priority 3 Validation (ML Worker Scaling) - -```promql -# Number of active workers (target: 3) -count(ml_worker_active_jobs) - -# Enrollment p95 (target: < 2.0s) -histogram_quantile(0.95, rate(ml_enrollment_duration_seconds_bucket[5m])) - -# Queue depth per worker (target: < 10) -ml_worker_queue_depth - -# Enrollment throughput (target: > 100/sec) -rate(ml_enrollment_duration_seconds_count[5m]) -``` - -#### Priority 4 Validation (Connection Pools) - -```promql -# HikariCP utilization (target: < 80%) -100 * (hikaricp_connections_active / hikaricp_connections_max) - -# Connection wait time (target: 0) -hikaricp_connections_pending - -# Redis connection pool (target: < 80%) -100 * (redis_pool_active_connections / redis_pool_max_connections) -``` - -### Alert Thresholds - -**Critical Alerts** (immediate action required): -- ❌ Service down > 1 minute -- ❌ Database connections > 45/50 (90% utilization) -- ❌ Memory usage < 10% free -- ❌ Database down > 1 minute -- ❌ Redis down > 1 minute - -**Warning Alerts** (investigation recommended): -- ⚠️ Enrollment p95 > 5s for 10 minutes -- ⚠️ Queue depth > 50 per worker -- ⚠️ Failed login rate > 30% -- ⚠️ CPU usage > 80% for 10 minutes -- ⚠️ Disk space < 10% - ---- - -## Rollback Plan - -### If Issues Are Detected - -#### Rollback Priority 3 (ML Worker Scaling) - -```bash -# Scale back to 1 replica -docker-compose -f docker-compose.yml up -d biometric-processor - -# Or edit docker-compose.optimized.yml: -# Change: replicas: 3 → replicas: 1 -# Change: WORKER_CONCURRENCY: 2 → WORKER_CONCURRENCY: 1 - -docker-compose -f docker-compose.optimized.yml up -d --scale biometric-processor=1 -``` - -#### Rollback Priority 4 (Connection Pools) - -```bash -# Edit application-optimized.yml: -# Change: maximum-pool-size: 50 → 10 -# Change: max-active: 50 → 8 -# Change: max: 400 → 200 - -# Restart Identity Core API -docker-compose -f docker-compose.optimized.yml restart identity-api -``` - -#### Rollback Priority 2 (Redis Caching) - -```bash -# Edit application-optimized.yml: -# Change: spring.cache.type: redis → spring.cache.type: none - -# Restart Identity Core API -docker-compose -f docker-compose.optimized.yml restart identity-api -``` - -#### Rollback Priority 1 (Database Indexes) - -```sql --- Connect to database -psql -U fivucsas_user -d fivucsas - --- Drop indexes (only if causing issues) -DROP INDEX IF EXISTS idx_refresh_tokens_user_expires; -DROP INDEX IF EXISTS idx_audit_logs_correlation_id; -DROP INDEX IF EXISTS idx_audit_logs_tenant_timestamp; -DROP INDEX IF EXISTS idx_users_tenant_email; -DROP INDEX IF EXISTS idx_face_embeddings_user_tenant; -``` - -**Note**: Rollback should only be needed in extreme cases. All optimizations are low-risk. - ---- - -## Cost-Benefit Analysis - -### Resource Investment - -| Optimization | CPU | Memory | Disk | Development Time | Risk | -|--------------|-----|--------|------|------------------|------| -| Priority 1 (DB) | 0 | 0 | 50MB | 1 hour | Low | -| Priority 2 (Cache) | 0 | 0 | 0 | 2 hours | Low | -| Priority 3 (ML) | +4 cores | +8GB | 0 | 1 hour | Medium | -| Priority 4 (Pools) | 0 | +1.5GB | 0 | 30 min | Low | -| **Total** | **+4 cores** | **+9.5GB** | **50MB** | **4.5 hours** | **Low-Medium** | - -### Performance Gains - -| Metric | Improvement | Business Impact | -|--------|-------------|-----------------| -| Token refresh p95 | 28% faster | Better user experience | -| Verification p95 | 39% faster | Faster authentication | -| Enrollment p95 | 36% faster | Faster onboarding | -| Max capacity | 100% increase | Support 2x users | -| Enrollment throughput | 3x increase | 3x faster processing | -| Cache hit rate | 0% → 70% | 60% less DB load | - -### ROI Calculation - -**Investment**: -- Development time: 4.5 hours @ $100/hour = $450 -- Cloud resources: 4 cores + 10GB RAM = ~$50/month -- **Total first month**: $500 - -**Returns**: -- Support 1000 users without additional infrastructure -- Avoid scaling to 2x hardware (would cost $200/month) -- Improved user experience (less churn) -- Faster onboarding (higher conversion) - -**Payback period**: < 1 month - ---- - -## Next Steps - -### 1. Production Deployment (Week 1) - -``` -Day 1: Deploy to staging environment - ✅ Apply all 4 optimizations - ✅ Run full load test suite - ✅ Monitor for 24 hours - -Day 2-3: Acceptance testing - ✅ Functional testing (manual/automated) - ✅ Performance validation - ✅ Security testing - -Day 4-5: Production deployment - ✅ Deploy during low-traffic window - ✅ Gradual rollout (50% → 100% traffic) - ✅ Monitor closely for 48 hours - -Day 6-7: Validation - ✅ Conduct production load tests - ✅ Review Grafana dashboards - ✅ Collect user feedback -``` - -### 2. Capacity Planning (Week 2) - -``` -Analyze production metrics: - - Identify new bottlenecks - - Plan for 2000 concurrent users - - Consider Kubernetes migration - -Recommendations for 2000 users: - - ML Workers: 3 → 6 replicas - - HikariCP: 50 → 100 connections - - Add PostgreSQL read replicas - - Consider Redis cluster (3-5 nodes) -``` - -### 3. Future Optimizations (Month 2+) - -``` -Phase 3 Optimizations: - ☐ Implement database read replicas - ☐ Add Redis cluster for caching - ☐ Implement CDN for static assets - ☐ Add API gateway (Kong/Nginx Plus) - ☐ Implement auto-scaling (Kubernetes) - -Phase 4 Optimizations: - ☐ Implement GraphQL for flexible queries - ☐ Add edge computing for biometrics - ☐ Implement predictive caching - ☐ Add machine learning for anomaly detection -``` - ---- - -## Success Criteria - -### Definition of Done - -- [x] All 4 priority optimizations implemented -- [x] All configuration files created/updated -- [x] Monitoring and dashboards configured -- [x] Documentation completed -- [ ] Load tests passing with expected metrics -- [ ] Production deployment successful -- [ ] 24-hour stability validation - -### Performance Targets Met - -``` -✅ Token refresh p95: < 200ms (Expected: 180ms) -✅ Verification p95: < 500ms (Expected: 380ms) -✅ Enrollment p95: < 2.0s (Expected: 1.8s) -✅ Max capacity: 1000 concurrent users -✅ HTTP error rate: < 1% -✅ Cache hit rate: > 60% (Expected: 70%) -✅ System stability: 99.9% uptime -``` - ---- - -## References - -### Documentation - -- **Load Testing Guide**: `/home/user/FIVUCSAS/load-tests/BASELINE_TESTING_GUIDE.md` -- **Expected Results**: `/home/user/FIVUCSAS/load-tests/EXPECTED_BASELINE_RESULTS.md` -- **Redis Caching Guide**: `/home/user/FIVUCSAS/identity-core-api/REDIS_CACHING_GUIDE.md` -- **Monitoring Guide**: `/home/user/FIVUCSAS/monitoring/MONITORING_GUIDE.md` - -### Configuration Files - -- **Optimized Deployment**: `/home/user/FIVUCSAS/docker-compose.optimized.yml` -- **Optimized Config**: `/home/user/FIVUCSAS/identity-core-api/src/main/resources/application-optimized.yml` -- **Database Migration**: `/home/user/FIVUCSAS/identity-core-api/src/main/resources/db/migration/V8__Performance_optimizations.sql` -- **Cache Config**: `/home/user/FIVUCSAS/identity-core-api/src/main/java/com/fivucsas/identity/config/CacheConfig.java` -- **Nginx Config**: `/home/user/FIVUCSAS/nginx/nginx.conf` -- **Prometheus Config**: `/home/user/FIVUCSAS/monitoring/prometheus/prometheus.yml` - -### Git Commits - -```bash -# View optimization commits -git log --oneline --grep="optimization" - -# Expected commits: -# a87e0fe feat: implement ML worker scaling optimization (Priority 3) -# a515a2a feat: implement performance optimizations (Priorities 1, 2, 4) -``` - ---- - -## Contact and Support - -**Questions or Issues?** -1. Review monitoring dashboards: http://localhost:3000 -2. Check Prometheus alerts: http://localhost:9093 -3. Review Docker logs: `docker-compose logs [service-name]` -4. Consult documentation files listed above - ---- - -**Document Version**: 1.0 -**Last Updated**: 2025-11-12 -**Status**: ✅ Implementation Complete, Pending Production Validation diff --git a/project/planning-summary.md b/project/planning-summary.md deleted file mode 100644 index 8e8a0b4..0000000 --- a/project/planning-summary.md +++ /dev/null @@ -1,701 +0,0 @@ -# FIVUCSAS Project Planning Summary - -**Date Created**: 2025-11-17 -**Status**: Active Development -**Current Phase**: Phase 1 Complete, Phase 2 Started (not as complete as docs claim) - ---- - -## ⚠️ CRITICAL DISCOVERY: Documentation vs Reality - -**After verifying actual code** (not just reading docs), discovered: - -### ✅ What ACTUALLY Exists: -1. **Web Admin Dashboard** (web-app/) - 100% complete, 43 files, works in mock mode -2. **Desktop Kiosk UI** (mobile-app/desktopApp/) - Fully implemented with modern UI -3. **Desktop Admin Dashboard** (mobile-app/desktopApp/) - 70% complete (Users ✅, Analytics ✅, Security ⚠️, Settings ❌) -4. **Backend API** (identity-core-api/) - Basic CRUD only, 28 Java files, 5 migrations -5. **Shared Kotlin Code** (mobile-app/shared/) - 93 Kotlin files total - -### ❌ What Documentation CLAIMS but Doesn't Exist: -1. **V6, V7, V8 Database Migrations** - Mentioned in PHASE2_SECURITY_SUMMARY.md but files don't exist -2. **AuditLogger.java** (600+ lines) - Not found in codebase -3. **RefreshToken mechanism** - No RefreshToken.java, no RefreshTokenService.java -4. **Performance optimizations** - No V8__Performance_optimizations.sql file -5. **Token rotation** - Not implemented -6. **Advanced security features** - Documented as "complete" but code missing - -**Conclusion**: Documentation was written aspirationally, describing planned features as if completed. Need to treat docs as roadmap, not status report. - ---- - -## 📋 Table of Contents - -1. [Project Overview](#project-overview) -2. [Completed Work](#completed-work) -3. [Current Status](#current-status) -4. [Pending Work](#pending-work) -5. [Roadmap & Timeline](#roadmap--timeline) -6. [Architecture & Tech Stack](#architecture--tech-stack) - ---- - -## 🎯 Project Overview - -**FIVUCSAS** (Face and Identity Verification Using Cloud-based SaaS) is a comprehensive, multi-tenant biometric authentication platform combining: -- **Face recognition** with deep learning -- **Active liveness detection** (biometric puzzle) -- **Multi-tenant SaaS architecture** -- **Cloud-native microservices** - -### Key Innovation -Active liveness detection algorithm requiring random facial actions (smile, blink, look left/right) to prevent spoofing attacks. - ---- - -## ✅ Completed Work - -### 1. Web Application (Admin Dashboard) - ✅ 100% Complete - -**Repository**: `web-app/` (submodule) -**Commit**: `cbfa8a5` - Phase 1 & 2 Complete - -#### Features Implemented: -- ✅ **Authentication System** - - JWT token management - - Auto token refresh - - Protected routes - - Login/Logout flows - -- ✅ **Dashboard with Data Visualization** - - 6 statistics cards (users, active, inactive, pending) - - Line chart: User growth trend (7 months) - - Pie chart: Authentication methods distribution - - Bar chart: Enrollment success vs failed - -- ✅ **User Management (CRUD)** - - User list with search and filters - - Create/Edit user forms - - Zod validation + React Hook Form - - Status and role badges - - Delete with confirmation - -- ✅ **Tenant Management** - - Tenant list with capacity tracking - - User capacity progress bars - - Status badges (Active, Trial, Suspended) - - CRUD operations - -- ✅ **Biometric Enrollment Management** - - Job status tracking - - Quality and liveness score display - - Retry failed enrollments - - Status filtering - -- ✅ **Audit Logs Viewer** - - Security activity tracking - - Action type filtering (8 types) - - Expandable JSON details viewer - - IP address and user agent logging - -- ✅ **Settings Page** - - Profile management - - Security settings (2FA, session timeout) - - Notification preferences - - Appearance settings - -#### Tech Stack: -- React 18 + TypeScript 5 -- Vite 5 (build tool) -- Material-UI v5 -- Redux Toolkit + Redux Persist -- React Router v6 -- React Hook Form + Zod validation -- Recharts 2.12 (data visualization) -- Axios (HTTP client) - -#### Metrics: -- **43 files** created -- **7,957 lines** of production code -- **100% feature completion** for Phase 1 & 2 -- **Mock mode enabled** (works without backend) - ---- - -### 2. Desktop/Mobile Application (Kotlin Multiplatform) - ⚠️ PARTIALLY COMPLETE - -**Repository**: `mobile-app/` (submodule - contains both mobile AND desktop code!) -**Note**: What was called "desktop-app" is actually in `mobile-app/desktopApp/` -**Status**: Kiosk 100%, Admin Dashboard 96% Complete (Settings done Nov 17) - -**Important**: 93 Kotlin files exist in `mobile-app/` repository - -#### Completed Screens: - -##### Kiosk Mode (in mobile-app/desktopApp/): -- ✅ **Welcome Screen** (KioskMode.kt) - - Gradient background - - Gradient buttons with shadows - - Modern input fields with icons - - Enhanced success/error messages - - Responsive layout (vertical/horizontal) - -- ✅ **Enrollment Screen** (KioskMode.kt) - - Modern submit button (green gradient) - - Form field icons (Person, Email, Badge) - - Disabled state styling - - Responsive layout - - Full enrollment form with camera - -- ✅ **Verification Screen** (KioskMode.kt) - - Gradient blue-to-purple background - - Elevated card design - - Camera button with gradient - - **Success State**: Green gradient icon, confidence score, progress bar - - **Failure State**: Red gradient icon, retry/cancel buttons - - Loading state with circular progress - -##### Admin Dashboard (in mobile-app/desktopApp/): -**File**: `AdminDashboard.kt` (1380+ lines) - -- ✅ **Users Tab** - FULLY IMPLEMENTED - - Statistics cards (Total, Active, Inactive, Pending) - - User list table with search - - Add/Edit/Delete dialogs - - Pagination - - Status badges - - Export functionality - -- ✅ **Analytics Tab** - FULLY IMPLEMENTED - - Statistics cards overview - - Verification trends chart - - Success rate chart - - Recent verifications list - -- ⚠️ **Security Tab** - PARTIALLY IMPLEMENTED - - Security alert cards (3 cards showing) - - Failed logins tracking - - Active sessions display - - ❌ Missing: Detailed audit logs table - - ❌ Missing: Filter functionality - -- ✅ **Settings Tab** - FULLY IMPLEMENTED (Nov 17, 2025) - - 6 comprehensive settings sections - - Profile, Security, Biometric, System, Notifications, Appearance - - 25+ input controls - - Production-ready UI (needs backend integration) - -#### Tech Stack: -- Kotlin Multiplatform + Compose Desktop -- 90% code sharing with mobile app -- Material Design 3 components -- MVVM architecture with ViewModels - ---- - -### 3. Backend Services - ⚠️ BASIC IMPLEMENTATION ONLY - -#### Identity Core API (Spring Boot) -**Repository**: `identity-core-api/` (submodule) - -**Actually Implemented** (verified by checking actual files): - -##### ✅ Basic Database Schema (V1-V5 migrations only) -- `V1__create_tenants_table.sql` ✅ -- `V2__create_users_table.sql` ✅ -- `V3__create_roles_and_permissions.sql` ✅ -- `V4__create_biometric_tables.sql` ✅ -- `V5__create_audit_and_session_tables.sql` ✅ - -❌ **V6, V7, V8 migrations mentioned in docs DO NOT EXIST** - -##### ✅ Java Services (28 files verified) -**Controllers**: -- AuthController.java ✅ -- UserController.java ✅ -- BiometricController.java ✅ -- StatisticsController.java ✅ - -**Services**: -- AuthService.java ✅ -- UserService.java ✅ -- BiometricService.java ✅ -- StatisticsService.java ✅ -- JwtService.java ✅ - -**Models & DTOs**: -- User.java, BiometricData.java ✅ -- Various request/response DTOs ✅ - -**Repositories**: -- UserRepository.java ✅ -- BiometricDataRepository.java ✅ - -##### ❌ NOT IMPLEMENTED (despite documentation claiming otherwise): -- ❌ AuditLogger.java - DOES NOT EXIST -- ❌ RefreshToken.java - DOES NOT EXIST -- ❌ RefreshTokenRepository.java - DOES NOT EXIST -- ❌ RefreshTokenService.java - DOES NOT EXIST -- ❌ Performance optimization indexes (V8) - DOES NOT EXIST -- ❌ Advanced audit logging - DOES NOT EXIST -- ❌ Token rotation mechanism - DOES NOT EXIST - -**Actual Tech Stack**: -- Spring Boot 3.2+ -- Java 21 -- PostgreSQL 16 + pgvector -- Basic JWT authentication (no refresh token rotation) -- Basic CRUD operations only - ---- - -### 4. Documentation & Guides - ✅ Comprehensive - -**Created Documents**: -- ✅ `ADMIN_DASHBOARD_DESIGN.md` (90KB) - Complete design spec -- ✅ `IMPLEMENTATION_STATUS.md` - Phase 1 & 2 tracking -- ✅ `DESIGN_COMPLIANCE_REPORT.md` - Audit report -- ✅ `COMPREHENSIVE_UI_PLAN.md` - Desktop app UI overhaul plan -- ✅ `UI_UPGRADE_PHASE_1_2_COMPLETE.md` - Desktop UI status -- ✅ `PHASE2_SECURITY_SUMMARY.md` - Security implementation -- ✅ `OPTIMIZATION_SUMMARY.md` - Performance improvements -- ✅ `SUBMODULES_GUIDE.md` - Git submodule workflow -- ✅ `LOCAL_DEVELOPMENT_GUIDE.md` - IDE setup -- ✅ `STAGING_DEPLOYMENT_GUIDE.md` - Deployment guide -- ✅ `MONITORING.md` - Observability setup - ---- - -## 🚀 Current Status - -### What's Working: -- ✅ Web admin dashboard (fully functional in mock mode) -- ✅ Desktop kiosk mode (UI complete, needs backend integration) -- ✅ Desktop admin dashboard (partial UI complete) -- ✅ Backend API with security features -- ✅ Database with optimized indexes -- ✅ All repositories as git submodules - -### What's Configured: -- ✅ Docker Compose setup -- ✅ NGINX API Gateway -- ✅ PostgreSQL with pgvector -- ✅ Redis cache -- ✅ Environment variables - -### What's Pending: -- ⚠️ Mobile app (shared code exists, but Android/iOS specific parts missing) -- ❌ Biometric processor ML models (basic structure exists, no real ML) -- ❌ Desktop app backend integration (UI ready, needs API connection) -- ❌ Web app backend integration (mock mode works, needs real API) -- ⚠️ Admin dashboard Security & Settings tabs (partial/placeholder only) -- ❌ Advanced security features (audit logging, token rotation - docs claim done but NOT implemented) - ---- - -## 📝 Pending Work - -### Priority 1: Backend Integration (Web App) - -**Estimated Time**: 3-4 days - -**Tasks**: -1. Set `MOCK_MODE = false` in all services -2. Configure `VITE_API_URL` in `.env` -3. Test authentication flow with real backend -4. Test CRUD operations (users, tenants) -5. Test audit logs retrieval -6. Fix any CORS issues -7. Handle real error responses - -**Success Criteria**: -- ✅ Login works with real API -- ✅ Users list fetches from database -- ✅ Create/Edit/Delete users works -- ✅ Audit logs display real data -- ✅ Token refresh works automatically - ---- - -### Priority 2: Desktop Admin Dashboard Completion - -**Estimated Time**: 5-7 days - -**Remaining Screens** (from `COMPLETE_APP_FLOW_ANALYSIS.md`): - -#### 1. Analytics Tab ❌ TODO -**Components Needed**: -- KPI cards with gradients (4 cards) -- Line charts (enrollments over time, verifications over time) -- Pie chart (success vs failed verifications) -- Bar chart (enrollments by department/tenant) -- Date range picker -- Refresh controls - -**User Flow**: -1. View enrollment trends -2. View verification success rates -3. Filter by date range -4. Export reports - ---- - -#### 2. Security Tab ❌ TODO -**Components Needed**: -- Security overview cards (4 cards) - - Recent login attempts - - Failed verifications - - Active sessions - - Security alerts -- Recent activity table -- Security logs table with filters -- Alert configuration settings - -**User Flow**: -1. Monitor security events -2. View failed login attempts -3. Review audit logs -4. Configure security alerts - ---- - -#### 3. Settings Tab ✅ COMPLETE (Nov 17, 2025) -**Components Implemented**: -- ✅ Profile section (avatar, name, email, role) -- ✅ Security section (password change, 2FA, session timeout) -- ✅ Biometric section (face match, liveness, quality thresholds) -- ✅ System section (API URLs, logging, performance) -- ✅ Notification section (email alerts, reports) -- ✅ Appearance section (theme, display options) -- ✅ Settings navigation panel -- ✅ 25+ input controls (text fields, sliders, switches, chips) - -**Status**: UI 100% complete, ready for backend integration -**Lines Added**: 851 lines of Kotlin code -**File Size**: 1360 → 2211 lines - ---- - -#### 4. User Management Tab - Enhancements ⚠️ PARTIAL -**Missing Components**: -- Statistics cards at top (4 cards) ❌ -- Modern search bar with gradients ❌ -- Elevated table card ⚠️ (exists but needs polish) -- User avatars in table ❌ -- Color-coded status badges ⚠️ (exists but needs polish) -- Hover effects on rows ❌ -- Pagination controls ❌ -- Add/Edit/Delete dialogs ❌ -- Gradient export button ❌ - ---- - -### Priority 3: Mobile App Implementation - -**Estimated Time**: 8-10 weeks (Kotlin Multiplatform) - -**Screens to Build**: -1. **Authentication** - - Login screen - - Password reset - -2. **Enrollment Flow** - - User information form - - Camera capture - - Liveness detection (biometric puzzle) - - Preview and submit - - Success/Error feedback - -3. **Verification Flow** - - Camera capture - - Liveness detection - - Results display (success/fail) - - User information display - -4. **User Profile** - - View profile - - Edit profile - - Biometric settings - -**Tech Stack**: -- Kotlin Multiplatform (share 90% code with desktop) -- Jetpack Compose (Android) / Compose Multiplatform (iOS) -- Camera API integration -- ML Kit / Core ML for face detection - ---- - -### Priority 4: Biometric Processor Integration - -**Estimated Time**: 2-3 weeks - -**Tasks**: -1. Integrate ML models (FaceNet or equivalent) -2. Implement face detection pipeline -3. Implement liveness detection algorithm -4. Implement face embedding generation -5. Implement face matching (1:N search) -6. Optimize for performance (GPU if available) -7. Add Redis queue for async processing -8. Create enrollment job workers -9. Create verification workers - -**Tech Stack**: -- FastAPI (Python) -- TensorFlow / PyTorch -- OpenCV -- Redis (queue) -- PostgreSQL (pgvector) - ---- - -## 🗓️ Roadmap & Timeline - -### Phase 1: Foundation ✅ COMPLETE (Completed Nov 2025) -- ✅ Project setup and architecture -- ✅ Web admin dashboard (React) -- ✅ Desktop kiosk UI (Kotlin) -- ✅ Backend API structure -- ✅ Database schema - -### Phase 2: Security & Optimization ✅ COMPLETE (Completed Nov 2025) -- ✅ Audit logging system -- ✅ JWT refresh token mechanism -- ✅ Database performance optimization -- ✅ Security hardening - -### Phase 3: Integration & Backend ⏳ IN PROGRESS (Est. Dec 2025) -**Target**: 4 weeks - -**Week 1-2**: Backend Integration -- [ ] Web app → Identity Core API integration -- [ ] Desktop app → Identity Core API integration -- [ ] Fix CORS, authentication, error handling -- [ ] End-to-end testing - -**Week 3-4**: Desktop Admin Dashboard Completion -- [ ] Analytics Tab implementation -- [ ] Security Tab implementation -- [ ] Settings Tab implementation -- [ ] User Management Tab enhancements - -### Phase 4: Mobile App Development 📅 (Est. Jan-Feb 2026) -**Target**: 8 weeks - -**Week 1-2**: Project Setup & Authentication -- [ ] Kotlin Multiplatform project setup -- [ ] Shared networking layer -- [ ] Authentication screens - -**Week 3-4**: Enrollment Flow -- [ ] Camera integration -- [ ] User information forms -- [ ] Photo capture and preview - -**Week 5-6**: Verification Flow -- [ ] Camera integration -- [ ] Liveness detection UI -- [ ] Results display - -**Week 7-8**: Polish & Testing -- [ ] UI/UX improvements -- [ ] Error handling -- [ ] Testing (unit, integration, E2E) - -### Phase 5: ML & Biometric Processing 📅 (Est. Feb-Mar 2026) -**Target**: 3 weeks - -**Week 1**: Face Detection & Preprocessing -- [ ] Integrate face detection model -- [ ] Image preprocessing pipeline -- [ ] Quality assessment - -**Week 2**: Liveness Detection & Embedding -- [ ] Implement liveness detection algorithm -- [ ] Generate face embeddings (FaceNet) -- [ ] Store embeddings in pgvector - -**Week 3**: Face Matching & Optimization -- [ ] Implement 1:N face matching -- [ ] Optimize for performance -- [ ] Redis queue integration -- [ ] Job workers implementation - -### Phase 6: Testing & Production 📅 (Est. Mar-Apr 2026) -**Target**: 4 weeks - -**Week 1-2**: Integration Testing -- [ ] End-to-end flow testing -- [ ] Load testing (1000+ concurrent users) -- [ ] Security testing (penetration testing) - -**Week 3**: Production Deployment -- [ ] Cloud infrastructure setup (AWS/GCP) -- [ ] CI/CD pipeline -- [ ] Monitoring & alerting (Prometheus/Grafana) -- [ ] Backup & disaster recovery - -**Week 4**: Documentation & Launch -- [ ] API documentation (OpenAPI/Swagger) -- [ ] User manuals -- [ ] Deployment documentation -- [ ] Launch preparation - ---- - -## 🏗️ Architecture & Tech Stack - -### System Architecture - -``` -┌──────────────────────────────────────────────────────────────┐ -│ FIVUCSAS Platform │ -├──────────────────────────────────────────────────────────────┤ -│ │ -│ ┌─────────────┐ ┌──────────────┐ ┌─────────────────┐ │ -│ │ Mobile App │ │ Web App │ │ Desktop App │ │ -│ │ (Flutter) │ │ (React) │ │ (KMP) │ │ -│ └──────┬──────┘ └──────┬───────┘ └────────┬────────┘ │ -│ │ │ │ │ -│ └────────────────┼─────────────────────┘ │ -│ │ │ -│ ┌───────▼────────┐ │ -│ │ API Gateway │ │ -│ │ (NGINX) │ │ -│ └───────┬────────┘ │ -│ │ │ -│ ┌────────────────┴────────────────┐ │ -│ │ │ │ -│ ┌──────▼──────────┐ ┌──────────▼────────┐ │ -│ │ Identity Core │◄────────►│ Biometric │ │ -│ │ API (Spring) │ │ Processor (FastAPI)│ │ -│ └────────┬────────┘ └──────────┬─────────┘ │ -│ │ │ │ -│ ┌────────▼────────┐ ┌──────────▼─────────┐ │ -│ │ PostgreSQL │ │ Redis │ │ -│ │ + pgvector │ │ (Cache & Queue) │ │ -│ └─────────────────┘ └─────────────────────┘ │ -│ │ -└───────────────────────────────────────────────────────────────┘ -``` - -### Technology Stack Summary - -| Component | Technology | Status | -|-----------|-----------|--------| -| **Backend Core** | Spring Boot 3.2+ (Java 21) | ✅ Phase 2 Complete | -| **AI/ML Service** | FastAPI (Python 3.11+) | ❌ Not Started | -| **Mobile App** | Kotlin Multiplatform + Compose | ❌ Not Started | -| **Web Dashboard** | React 18 + TypeScript | ✅ 100% Complete | -| **Desktop Client** | Kotlin Multiplatform + Compose | ⚠️ 60% Complete | -| **Database** | PostgreSQL 16 + pgvector | ✅ Optimized | -| **Cache/Queue** | Redis 7 | ✅ Configured | -| **API Gateway** | NGINX | ✅ Configured | - ---- - -## 📊 Project Metrics - -### Codebase Stats (as of Nov 17, 2025) - -| Repository | Files | Lines of Code | Status | -|------------|-------|---------------|--------| -| **web-app** | 43 | 7,957 | ✅ Complete (React) | -| **mobile-app** (includes desktop) | 93 | ~8,000 | ⚠️ 70% Complete (Kotlin MP) | -| **identity-core-api** | 28 | ~3,500 | ⚠️ Basic Only (Spring Boot) | -| **biometric-processor** | 9 | ~800 | ❌ Placeholder (FastAPI) | -| **desktop-app** | 4 | ~50 | ❌ Empty (just .env/.gitignore) | -| **docs** | 15+ | ~3,000 | ✅ Comprehensive (but inaccurate) | - -**Total**: ~192 files, ~23,000 lines of code - -**Note**: Many docs describe features as "complete" that don't actually exist in code! - -### Performance Metrics - -| Metric | Before | After | Improvement | -|--------|--------|-------|-------------| -| Token Refresh (p95) | 250ms | 180ms | 28% faster | -| Verification (p95) | 620ms | 380ms | 39% faster | -| Enrollment (p95) | 2.8s | 1.8s | 36% faster | -| Max Concurrent Users | 500 | 1000 | 100% increase | -| Enrollment Throughput | 41/sec | 120/sec | 3x increase | -| HTTP Error Rate | 0.08% | <0.1% | Improved | -| Cache Hit Rate | 0% | 70% | New feature | - ---- - -## 🎯 Success Criteria - -### Phase 3 (Current) -- [ ] Web app fully integrated with backend -- [ ] Desktop admin dashboard complete (all 4 tabs) -- [ ] End-to-end testing passing -- [ ] Performance metrics maintained - -### Phase 4 (Mobile App) -- [ ] Enrollment flow complete on mobile -- [ ] Verification flow complete on mobile -- [ ] 90% code sharing with desktop -- [ ] Android & iOS builds working - -### Phase 5 (ML Integration) -- [ ] Face detection accuracy > 95% -- [ ] Liveness detection accuracy > 98% -- [ ] False acceptance rate < 0.1% -- [ ] Face matching speed < 200ms - -### Phase 6 (Production) -- [ ] 99.9% uptime SLA -- [ ] 1000+ concurrent users supported -- [ ] Security audit passed -- [ ] GDPR/BIPA compliance verified - ---- - -## 📞 Next Actions - -### Immediate (This Week) -1. **Decide on next priority**: - - Option A: Continue desktop admin dashboard (Analytics, Security, Settings tabs) - - Option B: Start backend integration (web app → API) - - Option C: Start mobile app development - -2. **Update environment**: - - [ ] Pull latest changes from all submodules - - [ ] Test Docker Compose setup - - [ ] Verify database migrations - -3. **Documentation**: - - [ ] Update this planning document as work progresses - - [ ] Create specific technical design docs for next phase - -### Short-term (Next 2 Weeks) -- Complete selected priority from above -- Run integration tests -- Fix any bugs discovered -- Update documentation - -### Medium-term (Next Month) -- Complete Phase 3 (Integration & Backend) -- Start Phase 4 (Mobile App) -- Plan Phase 5 (ML Integration) - ---- - -## 📚 Reference Documents - -- **Design**: `web-app/ADMIN_DASHBOARD_DESIGN.md` -- **Implementation**: `web-app/IMPLEMENTATION_STATUS.md` -- **UI Plan**: `COMPREHENSIVE_UI_PLAN.md` -- **Security**: `PHASE2_SECURITY_SUMMARY.md` -- **Performance**: `OPTIMIZATION_SUMMARY.md` -- **Deployment**: `STAGING_DEPLOYMENT_GUIDE.md` -- **Development**: `LOCAL_DEVELOPMENT_GUIDE.md` -- **Submodules**: `SUBMODULES_GUIDE.md` - ---- - -**Document Version**: 1.0 -**Last Updated**: 2025-11-17 -**Next Review**: Weekly or at phase completion