LLD.md

LLD: AURA // Neural Visual Search System

This Low-Level Design (LLD) document outlines the architecture, data models, exact match detection algorithms, API specifications, and frontend component layout of the AURA Neural Visual Search System.

---

1. Architectural Overview

The system is split into a FastAPI backend running a local CLIP-based embedding engine and a Vanilla HTML/CSS/JS frontend featuring a glassmorphic user interface.

graph TD
    UI[Frontend Client] -->|HTTP POST Image/Text| API[FastAPI App]
    API -->|Raw Text/Image| CLIP[CLIP Embedder]
    CLIP -->|512-dim Normalized Embedding| API
    API -->|Vector + Query Params| DB[In-Memory Vector Store]
    DB -->|Matches & Scores| API
    API -->|Classified Results exact_match + related| UI

---

2. Component Specifications

2.1 Backend Modules

models.py // CLIPEmbedder

• Model: openai/clip-vit-base-patch32
• Execution Target: Auto-detects cuda (if available), falls back to cpu.
• Image Embeddings: Normalizes and runs image pixel values through the CLIP Vision Transformer.
• Text Embeddings: Standardizes input strings, applies sub-word tokenization, and computes CLIP Text Transformer embeddings.
• Normalizing Vector Output: Normalizes outputs to unit length ($L_2$ norm = 1.0) so that dot-product searches compute exact Cosine Similarity: $$\text{Cosine Similarity} = \vec{A} \cdot \vec{B}$$

vector_store.py // InMemoryVectorEngine & VectorStore

• Data Catalog: Serialized as JSON list (catalog.json) containing metadata:
  • id (e.g. prod-15970)
  • title
  • desc
  • price
  • category
  • image_url
• Embeddings Store: Serialized as a .npy NumPy array (embeddings.npy) of dimensions $(N, 512)$.
• Search Execution:
  • Computes the dot product of the search vector with all stored product vectors.
  • Sorts indices in descending order.
  • Returns top $K$ results containing metadata and corresponding cosine similarity score.

---

3. Exact Product Match Classifier Logic

The search classifier differentiates between an Exact Match and Related Recommendations.

flowchart TD
    Start([Receive Query]) --> QueryType{Query Type?}
    
    QueryType -->|Text Query: q| TextExact{Exact Title/ID Match?}
    TextExact -->|Yes| SetExactText[exact_match = Product <br> score = Vector Score / 1.0]
    TextExact -->|No| SetExactNull[exact_match = null]
    
    QueryType -->|Image Upload| VectorSearch[Perform Vector Search]
    VectorSearch --> ImageScore{Top Similarity >= 0.92?}
    ImageScore -->|Yes| SetExactImage[exact_match = Top Product <br> score = Similarity Score]
    ImageScore -->|No| SetExactNull
    
    SetExactText --> FilterRelated[Filter exact_match ID from related_products]
    SetExactImage --> FilterRelated
    SetExactNull --> FilterRelated
    
    FilterRelated --> ReturnJSON([Return exact_match & related_products])

3.1 Text Search Exact Matching

1. The search query q is stripped of leading/trailing spaces and lowercased.
2. The database is checked for a product where: q_clean == product["title"].strip().lower() or q_clean == product["id"].strip().lower().
3. If matched, it is returned as exact_match. If it is present in the vector search results, its calculated score is returned; otherwise, it defaults to a score of 1.0.

3.2 Visual Search Exact Matching

1. The upload image is processed, and its unit-normalized embedding is calculated.
2. The vector index retrieves the top results.
3. If the highest cosine similarity score is $\ge 0.92$ (calibrated for matching identical or slightly transformed images), the top match is classified as the exact_match.
4. Otherwise, no exact match is returned.

3.3 Related Products Resolution

1. Vector search is executed with $K = 7$ to find similar items.
2. If an exact_match was resolved (via text or image check), its corresponding ID is filtered out of the results array.
3. The remaining array is sliced to return the top 6 related_products.

---

4. API Endpoints

4.1 Search Endpoint: /api/search

• Method: POST
• Content-Type: multipart/form-data
• Parameters:
  • q (string, optional)
  • file (binary stream, optional)
• Response Format (application/json):

  {
    "exact_match": {
      "product": {
        "id": "prod-15970",
        "title": "Turtle Check Men Navy Blue Shirt",
        "desc": "Navy Blue Shirts for Men. Designed for casual wear.",
        "price": 64.0,
        "category": "Apparel",
        "image_url": "/static/images/prod-15970.png"
      },
      "score": 0.9998
    },
    "related_products": [
      {
        "product": { ... },
        "score": 0.8431
      }
    ]
  }
  

4.2 Similarity Endpoint: /api/search/similar

• Method: POST
• Content-Type: application/json
• Payload:

  { "product_id": "prod-15970" }
  

• Response: Array of similar products, excluding the queried product itself.

---

5. Frontend Layout & CSS Styling

The page layout consists of a responsive container structured with CSS grids and glassmorphism panels.

5.1 Results Section Layout

• Exact Match Area (#exact-match-section):
  • Border: Dashed accent border with soft glow (hsl(263, 70%, 50%)).
  • Active State: Shows up to 1 card representing the exact match (enhanced with green Exact Match badge).
  • Empty State: Renders a premium banner (🕵️‍♂️ No matching products found) informing the user that no exact match is available in the database.
• Related Recommendations Grid (#related-products-grid):
  • CSS Grid structure: repeat(auto-fill, minmax(260px, 1fr)).
  • Header: Related Products You Might Like.
  • Renders the remaining 6 visual matches.