face-recognition-svc/docs/architecture-diagram.md

# Face Recognition Service - Architecture Diagram

```mermaid
graph TB
    %% External Layer
    EndUser[👤 User] --> GradioUI[🖥️ Gradio Web Interface]

    %% Presentation Layer
    subgraph "Presentation Layer"
        GradioUI --> |HTTP/Web Requests| GradioApp[gradio_app.py]
    end

    %% Application Layer
    subgraph "Application Layer"
        GradioApp --> RegisterUC[📝 RegisterFaceUseCase]
        GradioApp --> VerifyUC[🔍 VerifyFaceUseCase]
        GradioApp --> IdentifyUC[🔎 IdentifyFaceUseCase]

        %% Асинхронная публикация задач
        RegisterUC --> TaskPublisher[📨 TaskPublisher]
        VerifyUC --> TaskPublisher
        IdentifyUC --> TaskPublisher
        
        %% Хранилище статусов задач (поллинг/вебсокет)
        GradioApp --> TaskStatusRepo[📊 TaskStatusRepository]
    end

    %% Scalability / Async Layer
    subgraph "Scalability Layer (Async, flipped-buffer)"
        TaskPublisher --> RabbitMQ[(🐇 RabbitMQ)]
        FaceWorkerPool[👷‍♂️ FaceWorker Pool - N instances] --> RabbitMQ
        FaceWorkerPool --> TaskStatusRepo
    end

    %% Domain Layer
    subgraph "Domain Layer"
        FaceService[⚙️ FaceRecognitionService] --> Face[👤 Face Entity]
        FaceService --> User[👨‍💼 User Entity]
        FaceService --> VResult[✅ VerificationResult]
        FaceService --> IResult[🎯 IdentificationResult]

        FaceRepo[📊 FaceRepository Interface]
        VectorStore[🗂️ VectorStore Interface]
        UserRepoIface[👨‍💼 UserRepository Interface]
        ObjectStorageIface[📁 ObjectStorage Interface]
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        %% ML Components
        subgraph "ML Components"
            RetinaFace[📷 RetinaFaceDetector]
            SFaceRec[🧠 SFaceRecognizer]
        end
        
        %% Storage Components
        subgraph "Storage Components"
            MongoDBRepo[🗄️ MongoDBFaceRepository]
            MongoUserRepo[👨‍💼 MongoDBUserRepository]
            ChromaDBStore[🔗 ChromaDBVectorStore]
            S3Storage[🪣 S3ObjectStorage]
        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)]
        S3Bucket[(🪣 S3 Bucket)]
        ONNXModel[🧠 SFace ONNX Model]
        RedisOrMongo[(📊 Redis/Mongo for Task Status)]
    end

    %% Service Dependencies (исполняются внутри воркеров)
    FaceWorkerPool --> FaceService
    FaceService --> RetinaFace
    FaceService --> SFaceRec
    FaceService --> FaceRepo
    FaceService --> VectorStore
    FaceService --> ObjectStorageIface

    %% Repository Implementations
    FaceRepo -.->|implements| MongoDBRepo
    VectorStore -.->|implements| ChromaDBStore
    UserRepoIface -.->|implements| MongoUserRepo
    ObjectStorageIface -.->|implements| S3Storage

    %% External Connections
    MongoDBRepo --> MongoDBServer
    MongoUserRepo --> MongoDBServer
    ChromaDBStore --> ChromaDBServer
    S3Storage --> S3Bucket
    SFaceRec --> ONNXModel
    TaskStatusRepo --> RedisOrMongo

    %% Use Case Dependencies (чтение пользователей/статусов)
    RegisterUC --> MongoUserRepo
    VerifyUC --> MongoUserRepo
    IdentifyUC --> MongoUserRepo

    %% Logging Dependencies
    RetinaFace -.-> Logger
    SFaceRec -.-> Logger
    FaceService -.-> Logger
    FaceWorkerPool -.-> Logger
    TaskPublisher -.-> Logger

    %% Configuration Dependencies
    FaceService -.-> Config
    MongoDBRepo -.-> Config
    MongoUserRepo -.-> Config
    ChromaDBStore -.-> Config
    S3Storage -.-> Config
    RabbitMQ -.-> Config
    TaskStatusRepo -.-> Config

    %% Styling
    classDef presentation fill:#e1f5fe
    classDef application fill:#f3e5f5
    classDef domain fill:#e8f5e8
    classDef infrastructure fill:#fff3e0
    classDef external fill:#ffebee
    classDef scalability fill:#ede7f6

    class GradioUI,GradioApp presentation
    class RegisterUC,VerifyUC,IdentifyUC,TaskPublisher,TaskStatusRepo application
    class Face,User,VResult,IResult,FaceRepo,VectorStore,UserRepoIface,ObjectStorageIface,FaceService domain
    class RetinaFace,SFaceRec,MongoDBRepo,ChromaDBStore,S3Storage,Config,Logger,MongoUserRepo infrastructure
    class MongoDBServer,ChromaDBServer,S3Bucket,ONNXModel,RedisOrMongo external
    class RabbitMQ,FaceWorkerPool scalability
```

## 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