face-recognition-svc/docs/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 S3 as S3ObjectStorage
    participant TaskPub as TaskPublisher
    participant MQ as RabbitMQ
    participant StatusRepo as TaskStatusRepository
    participant Worker as FaceWorker
    participant Detector as RetinaFaceDetector
    participant Recognizer as SFaceRecognizer
    participant FaceRepo as MongoDBFaceRepository
    participant VectorStore as ChromaDBVectorStore
    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->>S3: put_object(image)
        S3-->>RegisterUC: s3_uri

        RegisterUC->>TaskPub: publish_register_task(user_id, s3_uri)
        TaskPub->>MQ: enqueue(task)
    end

    RegisterUC->>StatusRepo: wait/poll for task_ids status
    StatusRepo-->>RegisterUC: Completed/Failed + results

    alt All tasks completed
        RegisterUC->>StatusRepo: get_mean_embedding(user_id) / or compute later
        RegisterUC-->>GradioUI: Success message + stats
    else Some tasks failed
        RegisterUC-->>GradioUI: Partial success + failed items
    end
    GradioUI-->>User: Registration result (async aware)

    %% Worker side
    loop Worker Pool
        MQ-->>Worker: task(user_id, s3_uri)
        Worker->>S3: get_object(s3_uri)
        Worker->>Detector: detect_faces(image)
        Detector-->>Worker: faces

        alt No faces or low quality
            Worker->>StatusRepo: update(task_id, failed_reason)
        else Face OK
            Worker->>Detector: align_face(image, landmarks)
            Detector-->>Worker: aligned_face

            Worker->>Recognizer: extract_embedding(aligned_face)
            Recognizer-->>Worker: embedding

            Worker->>FaceRepo: save(face_entity)
            FaceRepo->>MongoDB: insert face record
            MongoDB-->>FaceRepo: ok

            Worker->>VectorStore: add(face_id, embedding, metadata)
            VectorStore->>ChromaDB: store vector
            ChromaDB-->>VectorStore: ok

            Worker->>StatusRepo: update(task_id, success, embedding_id)
        end
    end

2. Face Verification Flow

sequenceDiagram
    participant User
    participant GradioUI as Gradio Interface
    participant VerifyUC as VerifyFaceUseCase
    participant UserRepo as MongoDBUserRepository
    participant S3 as S3ObjectStorage
    participant TaskPub as TaskPublisher
    participant MQ as RabbitMQ
    participant StatusRepo as TaskStatusRepository
    participant Worker as FaceWorker
    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)
        GradioUI-->>User: result
    else User found
        VerifyUC->>S3: put_object(image)
        S3-->>VerifyUC: s3_uri

        VerifyUC->>TaskPub: publish_verify_task(user_id, s3_uri)
        TaskPub->>MQ: enqueue(task)
        VerifyUC->>StatusRepo: wait/poll task_id
        StatusRepo-->>VerifyUC: (is_verified, score)

        VerifyUC-->>GradioUI: VerificationResult
        GradioUI-->>User: result
    end

    %% Worker side
    MQ-->>Worker: task(user_id, s3_uri)
    Worker->>S3: get_object(s3_uri)
    Worker->>Detector: detect_faces(image)
    Detector-->>Worker: faces

    alt No faces
        Worker->>StatusRepo: update(task_id, false, 0.0)
    else
        Worker->>Detector: align_face(image, landmarks)
        Detector-->>Worker: aligned

        Worker->>Recognizer: extract_embedding(aligned)
        Recognizer-->>Worker: query_embedding

        Worker->>FaceRepo: get_by_user_id(user_id)
        FaceRepo->>MongoDB: query faces
        MongoDB-->>FaceRepo: records
        FaceRepo-->>Worker: embeddings

        Worker->>Recognizer: calculate_similarity(query_embedding, user_embeddings)
        Recognizer-->>Worker: max_score

        Worker->>StatusRepo: update(task_id, max_score>=threshold, max_score)
    end

3. Face Identification Flow

sequenceDiagram
    participant User
    participant GradioUI as Gradio Interface
    participant IdentifyUC as IdentifyFaceUseCase
    participant S3 as S3ObjectStorage
    participant TaskPub as TaskPublisher
    participant MQ as RabbitMQ
    participant StatusRepo as TaskStatusRepository
    participant Worker as FaceWorker
    participant Detector as RetinaFaceDetector
    participant Recognizer as SFaceRecognizer
    participant VectorStore as ChromaDBVectorStore
    participant ChromaDB as ChromaDB Vector DB
    participant UserRepo as MongoDBUserRepository
    participant MongoDB as MongoDB Database

    User->>GradioUI: Upload image
    GradioUI->>IdentifyUC: execute(image)

    IdentifyUC->>S3: put_object(image)
    S3-->>IdentifyUC: s3_uri

    IdentifyUC->>TaskPub: publish_identify_task(s3_uri, top_k=10)
    TaskPub->>MQ: enqueue(task)

    IdentifyUC->>StatusRepo: wait/poll task_id
    StatusRepo-->>IdentifyUC: (best_user_id, confidence, candidate_user_ids)

    loop For each candidate_user_id
        IdentifyUC->>UserRepo: get_by_id(user_id)
        UserRepo->>MongoDB: query
        MongoDB-->>UserRepo: user data
        UserRepo-->>IdentifyUC: User entity
    end

    IdentifyUC-->>GradioUI: IdentificationResult
    GradioUI-->>User: result

    %% Worker
    MQ-->>Worker: task(s3_uri)
    Worker->>S3: get_object(s3_uri)
    Worker->>Detector: detect_faces(image)
    Detector-->>Worker: faces

    alt No faces
        Worker->>StatusRepo: update(task_id, null, 0.0, [])
    else
        Worker->>Detector: align_face(image, landmarks)
        Detector-->>Worker: aligned
        Worker->>Recognizer: extract_embedding(aligned)
        Recognizer-->>Worker: query_embedding

        Worker->>VectorStore: search_similar(query_embedding, top_k=10)
        VectorStore->>ChromaDB: search
        ChromaDB-->>VectorStore: results with metadata (face_id, user_id, score)
        VectorStore-->>Worker: candidates

        alt No scores above threshold
            Worker->>StatusRepo: update(task_id, null, 0.0, [])
        else
            note over Worker: Group by user_id, choose best_user_id + confidence
            Worker->>StatusRepo: update(task_id, best_user_id, confidence, candidate_user_ids)
        end
    end

4. System Initialization Flow

sequenceDiagram
    participant Main as main.py (API)
    participant Config as Settings
    participant MongoDBRepo as MongoDBFaceRepository
    participant MongoUserRepo as MongoDBUserRepository
    participant ChromaDB as ChromaDBVectorStore
    participant S3 as S3ObjectStorage
    participant Rabbit as RabbitMQ
    participant StatusRepo as TaskStatusRepository
    participant Publisher as TaskPublisher
    participant GradioApp as Gradio Interface

    participant WorkerMain as worker_main.py (Workers)
    participant WConfig as Settings
    participant WDetector as RetinaFaceDetector
    participant WRecognizer as SFaceRecognizer
    participant WFaceService as FaceRecognitionService
    participant WFaceRepo as MongoDBFaceRepository
    participant WVector as ChromaDBVectorStore
    participant WS3 as S3ObjectStorage
    participant WRabbit as RabbitMQ
    participant WStatusRepo as TaskStatusRepository
    participant WPool as FaceWorkerPool

    %% API init
    Main->>Config: Load configuration
    Config-->>Main: Settings object

    Main->>MongoDBRepo: Initialize with Mongo URL
    Main->>MongoUserRepo: Initialize with Mongo URL
    Main->>ChromaDB: Initialize with host/port
    Main->>S3: Initialize with bucket/creds
    Main->>Rabbit: Connect/create queues
    Main->>StatusRepo: Initialize (Redis/Mongo)
    Main->>Publisher: Initialize with Rabbit
    Main->>GradioApp: create_gradio_interface(use_cases, publisher, status_repo)
    Main->>GradioApp: launch(server_name, port)

    %% Worker init (can be on separate machines)
    WorkerMain->>WConfig: Load configuration
    WConfig-->>WorkerMain: Settings

    WorkerMain->>WRabbit: Connect/subscribe queues
    WorkerMain->>WStatusRepo: Initialize
    WorkerMain->>WDetector: Initialize RetinaFace
    note over WDetector: Load ONNX models, prepare ctx
    WorkerMain->>WRecognizer: Initialize SFace
    note over WRecognizer: Load/Download ONNX model
    WorkerMain->>WFaceRepo: Initialize with Mongo URL
    WorkerMain->>WVector: Initialize with Chroma host/port
    WorkerMain->>WS3: Initialize with bucket/creds
    WorkerMain->>WFaceService: Initialize with dependencies
    WorkerMain->>WPool: Start consuming tasks

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.