# Face Recognition Service - Sequence Diagrams ## 1. Face Registration Flow ```mermaid sequenceDiagram participant User participant GradioUI as Gradio Interface participant RegisterUC as RegisterFaceUseCase participant UserRepo as MongoDBUserRepository participant FaceService as FaceRecognitionService participant Detector as RetinaFaceDetector participant Recognizer as SFaceRecognizer participant FaceRepo as MongoDBFaceRepository participant VectorStore as ChromaDBVectorStore participant FileStorage as FileSystemStorage participant MongoDB as MongoDB Database participant ChromaDB as ChromaDB Vector DB User->>GradioUI: Upload images + username GradioUI->>RegisterUC: execute(username, images) RegisterUC->>UserRepo: get_user_by_name(username) UserRepo->>MongoDB: Query user by name MongoDB-->>UserRepo: User data or null UserRepo-->>RegisterUC: User entity or null alt User doesn't exist RegisterUC->>UserRepo: save(new_user) UserRepo->>MongoDB: Insert new user MongoDB-->>UserRepo: User ID UserRepo-->>RegisterUC: User ID end loop For each image RegisterUC->>FaceService: register_face(user_id, image) FaceService->>Detector: detect_faces(image) Detector-->>FaceService: List of detected faces alt No faces detected FaceService-->>RegisterUC: null else Face detected FaceService->>Detector: calculate_quality_score(best_face) Detector-->>FaceService: Quality score alt Quality too low FaceService-->>RegisterUC: null else Quality acceptable FaceService->>Detector: align_face(image, landmarks) Detector-->>FaceService: Aligned face image FaceService->>Recognizer: extract_embedding(aligned_face) Recognizer-->>FaceService: Face embedding FaceService->>FileStorage: save_image(aligned_face, user_id) FileStorage-->>FaceService: Image path FaceService->>FaceRepo: save(face_entity) FaceRepo->>MongoDB: Insert face record MongoDB-->>FaceRepo: Success FaceRepo-->>FaceService: Success FaceService->>VectorStore: add(face_id, embedding, metadata) VectorStore->>ChromaDB: Store embedding vector ChromaDB-->>VectorStore: Success VectorStore-->>FaceService: Success FaceService-->>RegisterUC: Face ID end end end RegisterUC->>FaceService: update_user_mean_embedding(user_id) FaceService->>FaceRepo: get_by_user_id(user_id) FaceRepo->>MongoDB: Query faces by user_id MongoDB-->>FaceRepo: Face records FaceRepo-->>FaceService: Face entities FaceService-->>RegisterUC: Mean embedding RegisterUC->>UserRepo: update_user(user) UserRepo->>MongoDB: Update user record MongoDB-->>UserRepo: Success UserRepo-->>RegisterUC: Success RegisterUC-->>GradioUI: Success message GradioUI-->>User: Registration result ``` ## 2. Face Verification Flow ```mermaid sequenceDiagram participant User participant GradioUI as Gradio Interface participant VerifyUC as VerifyFaceUseCase participant UserRepo as MongoDBUserRepository participant FaceService as FaceRecognitionService participant Detector as RetinaFaceDetector participant Recognizer as SFaceRecognizer participant FaceRepo as MongoDBFaceRepository participant MongoDB as MongoDB Database User->>GradioUI: Upload image + username GradioUI->>VerifyUC: execute(username, image) VerifyUC->>UserRepo: get_user_by_name(username) UserRepo->>MongoDB: Query user by name MongoDB-->>UserRepo: User data or null UserRepo-->>VerifyUC: User entity or null alt User not found VerifyUC-->>GradioUI: VerificationResult(false, 0.0) else User found VerifyUC->>FaceService: verify_face(user_id, image) FaceService->>Detector: detect_faces(image) Detector-->>FaceService: List of detected faces alt No faces detected FaceService-->>VerifyUC: (false, 0.0) else Face detected FaceService->>Detector: align_face(image, landmarks) Detector-->>FaceService: Aligned face image FaceService->>Recognizer: extract_embedding(aligned_face) Recognizer-->>FaceService: Query embedding FaceService->>FaceRepo: get_by_user_id(user_id) FaceRepo->>MongoDB: Query registered faces MongoDB-->>FaceRepo: Face records FaceRepo-->>FaceService: User's face entities alt No registered faces FaceService-->>VerifyUC: (false, 0.0) else Compare with registered faces loop For each registered face FaceService->>Recognizer: calculate_similarity(query_embedding, face_embedding) Recognizer-->>FaceService: Similarity score end FaceService-->>VerifyUC: (is_verified, max_similarity) end end VerifyUC-->>GradioUI: VerificationResult end GradioUI-->>User: Verification result ``` ## 3. Face Identification Flow ```mermaid sequenceDiagram participant User participant GradioUI as Gradio Interface participant IdentifyUC as IdentifyFaceUseCase participant UserRepo as MongoDBUserRepository participant FaceService as FaceRecognitionService participant Detector as RetinaFaceDetector participant Recognizer as SFaceRecognizer participant VectorStore as ChromaDBVectorStore participant ChromaDB as ChromaDB Vector DB participant MongoDB as MongoDB Database User->>GradioUI: Upload image GradioUI->>IdentifyUC: execute(image) IdentifyUC->>FaceService: identify_face(image) FaceService->>Detector: detect_faces(image) Detector-->>FaceService: List of detected faces alt No faces detected FaceService-->>IdentifyUC: (null, 0.0, []) else Face detected FaceService->>Detector: align_face(image, landmarks) Detector-->>FaceService: Aligned face image FaceService->>Recognizer: extract_embedding(aligned_face) Recognizer-->>FaceService: Query embedding FaceService->>VectorStore: search_similar(query_embedding, top_k=10) VectorStore->>ChromaDB: Vector similarity search ChromaDB-->>VectorStore: Similar face vectors VectorStore-->>FaceService: Similar faces with metadata alt No similar faces above threshold FaceService-->>IdentifyUC: (null, 0.0, []) else Similar faces found note over FaceService: Group by user_id and calculate best scores FaceService-->>IdentifyUC: (best_user_id, confidence, candidates) end end loop For each candidate user_id IdentifyUC->>UserRepo: get_by_id(user_id) UserRepo->>MongoDB: Query user by ID MongoDB-->>UserRepo: User data UserRepo-->>IdentifyUC: User entity end alt User identified IdentifyUC->>UserRepo: get_by_id(best_user_id) UserRepo->>MongoDB: Query identified user MongoDB-->>UserRepo: User data UserRepo-->>IdentifyUC: User entity end IdentifyUC-->>GradioUI: IdentificationResult GradioUI-->>User: Identification result ``` ## 4. System Initialization Flow ```mermaid sequenceDiagram participant Main as main.py participant Config as Settings participant MongoDB as MongoDBFaceRepository participant ChromaDB as ChromaDBVectorStore participant FileStorage as FileSystemStorage participant Detector as RetinaFaceDetector participant Recognizer as SFaceRecognizer participant FaceService as FaceRecognitionService participant UseCases as Use Cases participant GradioApp as Gradio Interface Main->>Config: Load configuration Config-->>Main: Settings object Main->>MongoDB: Initialize with MongoDB URL MongoDB-->>Main: Repository instance Main->>ChromaDB: Initialize with Chroma host/port ChromaDB-->>Main: Vector store instance Main->>FileStorage: Initialize with upload directory FileStorage-->>Main: File storage instance Main->>Detector: Initialize RetinaFace note over Detector: Load ONNX models, prepare ctx Detector-->>Main: Detector instance Main->>Recognizer: Initialize SFace note over Recognizer: Download/load SFace ONNX model Recognizer-->>Main: Recognizer instance Main->>FaceService: Initialize with dependencies FaceService-->>Main: Service instance Main->>UseCases: Initialize use cases with service UseCases-->>Main: Use case instances Main->>GradioApp: create_gradio_interface(use_cases) GradioApp-->>Main: Gradio app instance Main->>GradioApp: launch(server_name, server_port) note over GradioApp: Start web server on port 7860 GradioApp-->>Main: Server running ``` ## Flow Descriptions ### Registration Flow 1. User uploads multiple images with username 2. System checks if user exists, creates if needed 3. For each image: detects faces, validates quality, extracts embeddings 4. Stores face metadata in MongoDB, embeddings in ChromaDB, images in filesystem 5. Updates user with mean embedding for faster verification ### Verification Flow (1:1) 1. User provides image and username to verify against 2. System detects face in query image and extracts embedding 3. Retrieves all registered faces for the specified user 4. Compares query embedding with user's registered face embeddings 5. Returns verification result based on similarity threshold ### Identification Flow (1:N) 1. User provides image without specifying identity 2. System detects face and extracts embedding 3. Performs vector similarity search across all registered faces 4. Groups results by user and calculates confidence scores 5. Returns best match if confidence exceeds threshold ### Initialization Flow System startup involves initializing all dependencies in correct order, loading ML models, and starting the web interface.