# srinidevar/semantic-image-search architecture

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

- Interactive diagram: https://gitdiagram.com/srinidevar/semantic-image-search
- Repository: https://github.com/srinidevar/semantic-image-search

## Overview

##### Project type and purpose
- This is a containerized, full-stack semantic image-search application.
- It ingests images, computes CLIP embeddings, stores them in Milvus (a vector database), and provides a VueJS UI for text-based searches.

##### Main components
a. UI Container (VueJS frontend)
b. API Container (FastAPI service)
c. Image Server Container (uploads, stores, and serves raw images)
d. Vector DB (Milvus)
e. Metadata Store (etcd) and Object Store (MinIO) – Milvus dependencies
f. CLIP Model (loaded inside the API service)

##### Relationships and data flows
1) User → Browser/UI: loads static assets (HTML/CSS/JS).
2) UI → API over HTTP:
– Index Image requests (multipart/form-data uploads)
– Search queries (text)
3) API → Image Server:
– POST new image for storage
– GET image for display
4) API (upon image upload) → CLIP Model → generates embedding → Milvus (vector insert)
5) API (upon search) → CLIP Model → text embedding → Milvus (vector search) → returns matching image IDs
6) API → MinIO/etcd: Milvus’s object store and metadata operations
7) API → Image Server: to retrieve actual image bytes for display in results

##### Architectural patterns & design principles
- Microservices: each major domain (UI, API, image server, vector DB) runs in its own container.
- Separation of concerns:
- UI handles presentation and HTTP calls
- API handles business logic, CLIP model, DB orchestration
- Image Server isolates raw image storage
- Milvus abstracts vector indexing/search
- Docker-Compose for orchestration
- Asynchronous processing model for indexing (uploads → background embedding → DB insert)

##### Technologies & frameworks
- VueJS + Vite → UI
- FastAPI + Python → API
- OpenCLIP model (Python library) → Embedding
- Milvus → Vector database
- etcd, MinIO → Milvus dependencies
- Docker + Docker-Compose → Deployment

##### Detail without over-splitting
- Six top-level containers.
- Inter-container calls and data stores.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actors and Containers
    User["User"]:::actor
    UI["UI Container (VueJS) :3000"]:::frontend
    API["API Container (FastAPI) :8000"]:::backend
    ImageServer["Image Server :9999"]:::imageserver
    Milvus["Milvus (Vector DB)"]:::datastore
    Etcd["etcd (Metadata Store)"]:::datastore
    MinIO["MinIO (Object Store)"]:::datastore

    %% API Sub-components
    subgraph "API Container"
        direction TB
        IndexAPI["index_image_api"]:::router
        SearchAPI["search_api"]:::router
        ImageIndexer["image_indexer"]:::router
        CLIPService["CLIP Embedding Service"]:::service
        MilvusClient["Milvus Client"]:::service
        ObjectStoreClients["MinIO/etcd Clients"]:::service
    end

    %% Relationships
    User -->|"loads UI assets"| UI
    UI -->|"POST /index (multipart/form-data)"| API
    UI -->|"GET /search?q="| API
    API -->|"POST image bytes"| ImageServer
    API -->|"GET image bytes"| ImageServer
    API -->|"calls index_image_api"| IndexAPI
    API -->|"calls search_api"| SearchAPI
    API -->|"calls image_indexer"| ImageIndexer
    IndexAPI -->|"sends image to CLIP"| CLIPService
    ImageIndexer -->|"sends image to CLIP"| CLIPService
    SearchAPI -->|"sends text to CLIP"| CLIPService
    CLIPService -->|"returns embedding"| MilvusClient
    MilvusClient -->|"vector insert/search"| Milvus
    API -->|"object operations"| ObjectStoreClients
    ObjectStoreClients -->|"store/retrieve"| MinIO
    ObjectStoreClients -->|"metadata ops"| Etcd
    Milvus -->|"uses"| Etcd
    Milvus -->|"uses"| MinIO

    %% Click Events
    click UI "https://github.com/srinidevar/semantic-image-search/tree/main/src/ui/"
    click API "https://github.com/srinidevar/semantic-image-search/tree/main/src/api/"
    click IndexAPI "https://github.com/srinidevar/semantic-image-search/blob/main/src/api/app/routers/index_image_api.py"
    click SearchAPI "https://github.com/srinidevar/semantic-image-search/blob/main/src/api/app/routers/search_api.py"
    click ImageIndexer "https://github.com/srinidevar/semantic-image-search/blob/main/src/api/app/routers/image_indexer.py"
    click CLIPService "https://github.com/srinidevar/semantic-image-search/blob/main/src/api/requirements.txt"
    click ImageServer "https://github.com/srinidevar/semantic-image-search/tree/main/src/image_server/"
    click Compose "https://github.com/srinidevar/semantic-image-search/blob/main/deploy/docker-compose.yml"

    %% Styles
    classDef actor fill:#ffffff,stroke:#000,stroke-width:1px
    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:1px
    classDef backend fill:#d4edda,stroke:#155724,stroke-width:1px
    classDef imageserver fill:#f8d7da,stroke:#721c24,stroke-width:1px
    classDef datastore fill:#fff3cd,stroke:#856404,stroke-width:1px
    classDef router fill:#d1ecf1,stroke:#0c5460,stroke-width:1px
    classDef service fill:#e2e3e5,stroke:#383d41,stroke-width:1px
```
