face-recognition-svc/architecture-diagram.md

Face Recognition Service - Architecture Diagram

graph TB
    %% External Layer
    User[👤 User] --> GradioUI[🖥️ Gradio Web Interface]
    
    %% Presentation Layer
    subgraph "Presentation Layer"
        GradioUI --> |Web Requests| GradioApp[gradio_app.py]
    end
    
    %% Application Layer
    subgraph "Application Layer"
        GradioApp --> RegisterUC[📝 RegisterFaceUseCase]
        GradioApp --> VerifyUC[🔍 VerifyFaceUseCase]
        GradioApp --> IdentifyUC[🔎 IdentifyFaceUseCase]
        
        RegisterUC --> FaceService[⚙️ FaceRecognitionService]
        VerifyUC --> FaceService
        IdentifyUC --> FaceService
    end
    
    %% Domain Layer
    subgraph "Domain Layer"
        FaceService --> Face[👤 Face Entity]
        FaceService --> User[👨‍💼 User Entity]
        FaceService --> VResult[✅ VerificationResult]
        FaceService --> IResult[🎯 IdentificationResult]
        
        FaceRepo[📊 FaceRepository Interface]
        VectorStore[🗂️ VectorStore Interface]
    end
    
    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        %% ML Components
        subgraph "ML Components"
            RetinaFace[📷 RetinaFaceDetector]
            SFaceRec[🧠 SFaceRecognizer]
        end
        
        %% Storage Components
        subgraph "Storage Components"
            MongoDB[🗄️ MongoDBFaceRepository]
            ChromaDB[🔗 ChromaDBVectorStore]
            FileSystem[📁 FileSystemStorage]
        end
        
        %% Configuration & Logging
        subgraph "Cross-cutting Concerns"
            Config[⚙️ Settings]
            Logger[📋 Logging System]
        end
    end
    
    %% External Systems
    subgraph "External Systems"
        MongoDBServer[(🗄️ MongoDB Database)]
        ChromaDBServer[(🔗 ChromaDB Vector DB)]
        FileStorage[(📁 File System)]
        ONNXModel[🧠 SFace ONNX Model]
    end
    
    %% Service Dependencies
    FaceService --> RetinaFace
    FaceService --> SFaceRec
    FaceService --> FaceRepo
    FaceService --> VectorStore
    FaceService --> FileSystem
    
    %% Repository Implementations
    FaceRepo -.->|implements| MongoDB
    VectorStore -.->|implements| ChromaDB
    
    %% External Connections
    MongoDB --> MongoDBServer
    ChromaDB --> ChromaDBServer
    FileSystem --> FileStorage
    SFaceRec --> ONNXModel
    
    %% Use Case Dependencies
    RegisterUC --> UserRepo[👨‍💼 MongoDBUserRepository]
    VerifyUC --> UserRepo
    IdentifyUC --> UserRepo
    UserRepo --> MongoDBServer
    
    %% Logging Dependencies
    RetinaFace -.-> Logger
    SFaceRec -.-> Logger
    FaceService -.-> Logger
    
    %% Configuration Dependencies
    FaceService -.-> Config
    MongoDB -.-> Config
    ChromaDB -.-> Config
    
    %% Styling
    classDef presentation fill:#e1f5fe
    classDef application fill:#f3e5f5
    classDef domain fill:#e8f5e8
    classDef infrastructure fill:#fff3e0
    classDef external fill:#ffebee
    
    class GradioUI,GradioApp presentation
    class RegisterUC,VerifyUC,IdentifyUC,FaceService application
    class Face,User,VResult,IResult,FaceRepo,VectorStore domain
    class RetinaFace,SFaceRec,MongoDB,ChromaDB,FileSystem,Config,Logger,UserRepo infrastructure
    class MongoDBServer,ChromaDBServer,FileStorage,ONNXModel external

Architecture Overview

Layers Description

1. Presentation Layer: Gradio-based web interface for user interaction
2. Application Layer: Use cases and business logic orchestration
3. Domain Layer: Core business entities and repository interfaces
4. Infrastructure Layer: Technical implementations and external service adapters

Key Components

• Face Detection: RetinaFace for accurate face detection and landmark extraction
• Face Recognition: SFace ONNX model for embedding extraction and similarity calculation
• Storage: MongoDB for metadata, ChromaDB for vector similarity search, filesystem for images
• Web Interface: Gradio provides registration, verification, and identification capabilities

Data Flow

1. User uploads images through Gradio interface
2. Use cases orchestrate the business logic
3. FaceRecognitionService processes images using ML models
4. Data is persisted in MongoDB, ChromaDB, and filesystem
5. Results are returned to the user through the web interface