face-recognition-svc/sequence-diagrams.md

Face Recognition Service - Sequence Diagrams

1. Face Registration Flow

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

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

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

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.