# mihaidavid05/text-to-image-search architecture

> Architecture diagram of the GitHub repository mihaidavid05/text-to-image-search, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mihaidavid05/text-to-image-search
- Repository: https://github.com/mihaidavid05/text-to-image-search

## Overview

##### Main components
- Frontend/UI Layer: Represented by the Jinja templates found under the “templates” directory. These templates handle the display of the search form (form_template.html), the data report (data_report_template.html), and the images display (images_template.html).
- API Layer / FastAPI Backend: The FastAPI application is kick-started by “service.py” and supports API interactions using request/response schemas defined in “src/schemas.py”. This component receives user queries from the UI.
- Embedding & Search Engine: This includes the algorithms that use the CLIP-ViT-B-32 model to create text and image embeddings. The embedding process (both for text and images) is applied before querying the database. The “utils/search.py” module is responsible for transforming the input text into an embedding and executing an Approximate Nearest Neighbor (ANN) search in Qdrant.
- Data Preparation & Evaluation: Two additional scripts – “prepare.py” and “evaluate.py” – handle data ingestion, report generation, image embedding creation, population of the Qdrant database, and performance evaluation using metrics like precision@k.
- External Vector Database (Qdrant): The project relies on an external Qdrant service (run via Docker) to store image embeddings and perform vector similarity searches.
- Utilities: The “utils” folder (with data.py and utils.py) provides additional support routines to manage data, perform validations, and process other general tasks.

##### Relationships and interactions
- User Interaction: The UI (Jinja templates) captures text queries and displays results. The templates send form data to the FastAPI endpoint.
- API/Backend Processing: When a POST request arrives at the FastAPI endpoint (service.py), it uses the defined schemas (src/schemas.py) to validate and process it.
- Query Handling: The backend calls the search utility (utils/search.py) to embed the input text (using the CLIP model) and performs a vector search against Qdrant.
- Data Flow: For report generation and data updates, the “prepare.py” script uses the “utils/data.py” module to download, organize, and extract relevant data (as well as to build and store the embeddings).
- Evaluation: The “evaluate.py” script ingests labels from the provided file (docs/labels.txt) to test the retrieval accuracy of the system.

##### Architectural patterns and technologies
- Separation of Concerns: The design clearly partitions the user interface (Jinja templates), business logic (FastAPI service and associated schemas), and data processing (utility modules and external service integration).
- Microservice-like Endpoints: Although this is a single project, the distinct scripts (prepare.py, service.py, evaluate.py) act like separate services for data handling, user service, and evaluation.
- External Integration: The use of a Dockerized Qdrant instance for ANN search is a key external dependency.
- Technologies: FastAPI for the backend, Jinja for templating, a CLIP model for generating embeddings, and Qdrant for vector storage and ANN retrieval.

- Clear Labels for Each Component:
- “Jinja Templates (UI)” representing the presentation layer.
- “FastAPI Service (service.py)” as the API endpoint.
- “Schemas (src/schemas.py)” assisting in input/output validation.
- “Search Utilities (utils/search.py)” for embedding and search logic.
- “Data Utilities (utils/data.py & utils/utils.py)” for preprocessing and auxiliary functions.
- “Data Preparation & Report Generation (prepare.py)” for initial data ingestion.
- “Evaluation Service (evaluate.py)” for performance testing.
- “Qdrant Vector Database” showing the external vector storage.
- Differentiate the flow for data preparation (which runs as a separate process) versus the live search queries.
- Additional Annotations:
- Brief notes near each component that reference the key technologies involved (e.g., “CLIP-ViT-B-32 for embeddings”, “Dockerized Qdrant”, etc.).

##### Overall detail
- Maintain a high-level system overview while providing enough granularity (e.g., distinguishing between API endpoints and backend utility modules).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        Form["Form Template (form_template.html)"]:::frontend
        DataReport["Data Report Template (data_report_template.html)"]:::frontend
        Images["Images Template (images_template.html)"]:::frontend
    end

    %% Backend/API Layer
    subgraph "Backend/API Layer"
        API["FastAPI Service (service.py)"]:::backend
        Schemas["Schemas (src/schemas.py)"]:::backend
        API -->|"validates_with"| Schemas
    end

    %% Utilities & Search
    subgraph "Utilities & Search"
        Search["Search Utilities (utils/search.py) <br/>(CLIP-ViT-B-32 Embeddings)"]:::utilities
        DataUtil["Data Utilities (utils/data.py & utils/utils.py)"]:::utilities
    end

    %% Data Processing Scripts
    subgraph "Data Processing"
        Prep["Data Preparation & Report Generation (prepare.py)"]:::script
        Eval["Evaluation Service (evaluate.py)"]:::script
    end

    %% External Service
    Qdrant["Qdrant Vector Database <br/>(Dockerized)"]:::external

    %% Data Flow Connections
    Form -->|"submits_query"| API
    API -->|"calls_search"| Search
    Search -->|"queries_vector_DB"| Qdrant
    Qdrant -->|"returns_results"| Search
    Search -->|"sends_results"| API
    API -->|"displays_report"| DataReport
    API -->|"displays_images"| Images
    API -->|"utilizes"| DataUtil

    %% Data Preparation and Evaluation Flows
    DataUtil -->|"supports_preparation"| Prep
    Prep -->|"populates"| Qdrant
    DataUtil -->|"provides_data"| Eval

    %% Click Events
    click Form "https://github.com/mihaidavid05/text-to-image-search/blob/main/templates/form_template.html"
    click DataReport "https://github.com/mihaidavid05/text-to-image-search/blob/main/templates/data_report_template.html"
    click Images "https://github.com/mihaidavid05/text-to-image-search/blob/main/templates/images_template.html"
    click API "https://github.com/mihaidavid05/text-to-image-search/blob/main/service.py"
    click Schemas "https://github.com/mihaidavid05/text-to-image-search/blob/main/src/schemas.py"
    click Search "https://github.com/mihaidavid05/text-to-image-search/blob/main/utils/search.py"
    click DataUtil "https://github.com/mihaidavid05/text-to-image-search/blob/main/utils/data.py"
    click DataUtil "https://github.com/mihaidavid05/text-to-image-search/blob/main/utils/utils.py"
    click Prep "https://github.com/mihaidavid05/text-to-image-search/blob/main/prepare.py"
    click Eval "https://github.com/mihaidavid05/text-to-image-search/blob/main/evaluate.py"

    %% Style Definitions
    classDef frontend fill:#FFE0F0,stroke:#CC0066,stroke-width:2px;
    classDef backend fill:#E0F7FF,stroke:#0066CC,stroke-width:2px;
    classDef utilities fill:#E0FFE0,stroke:#008000,stroke-width:2px;
    classDef script fill:#FFF0B3,stroke:#FF9900,stroke-width:2px;
    classDef external fill:#FFD6D6,stroke:#CC0000,stroke-width:2px,stroke-dasharray: 5 5;
```
