# qasimhassan65/vetra architecture

> Architecture diagram of the GitHub repository qasimhassan65/vetra, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/qasimhassan65/vetra
- Repository: https://github.com/qasimhassan65/vetra

## Overview

##### Project Type & Purpose
- This is a browser-extension project (“Vetra”) for Chrome that adds a minimalistic virtual try-on experience on e-commerce sites.
- Core features: product detection (content script), UI popup for photo upload & history, background script for messaging & state, AI integration with Google Gemini.

a. Manifest & Assets (static)
b. Content Script (content.js)
- Injects into e-commerce pages
- Detects products & attaches click handlers
c. Background Script (background.js)
- Acts as a service worker / message broker
- Manages extension-wide state (Chrome storage)
- Opens/closes side panel
d. Popup UI (popup.html, popup.css, popup.js)
- Photo upload widget
- “Try On” button & 3D carousel history
- Reads/writes state via messages to background
e. Configuration (config.js / config.example.js)
- Holds API URL & key templates
f. External Service (Google Gemini API)
- Image upload endpoint
- Generation endpoint
g. Chrome Storage (local & sync)
- Persists uploaded photos & generated results across navigations

##### Relationships & Data Flows
- Popup UI ↔ Background Script
- Message channel for user actions (upload, “Try On”, history requests)
- Content Script ↔ Background Script
- Messaged events when user clicks a product on page
- Payload: product image URL, metadata
- Background Script → Gemini API (HTTPS)
- Sends image & product context to AI
- Receives generated try-on image
- Background Script ↔ Chrome Storage
- Saves user sessions, history entries, last result
- Popup UI ← reads history from Chrome Storage via background messaging
- Content Script injects UI panel on page when instructed by background

##### Architectural Patterns & Principles
- Event-driven messaging (Chrome runtime.sendMessage/onMessage)
- Separation of concerns:
- UI layer (popup)
- DOM Integration layer (content script)
- Orchestration & state layer (background)
- External API isolation: config files drive endpoint & key
- Progressive enhancement: minimal UI, no data collection, secure HTTPS

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Chrome Extension"
        direction TB
        Manifest["manifest.json"]:::extension
        Icons["icons/"]:::extension
        Content["content.js"]:::extension
        Background["background.js"]:::extension
        PopupUI["popup.html<br/>popup.css<br/>popup.js"]:::extension
        Config["config.js<br/>config.example.js"]:::extension
    end

    Storage[(Chrome Storage)]:::storage
    Gemini([Google Gemini API]):::external

    Manifest --> Content
    Manifest --> Background
    Manifest --> PopupUI
    Content <-->|"sendMessage"| Background
    PopupUI <-->|"sendMessage"| Background
    Background -->|chrome.storage.get/set| Storage
    Background -->|HTTP POST: image upload→generateContent→return image| Gemini

    click Manifest "https://github.com/qasimhassan65/vetra/blob/main/manifest.json"
    click Icons "https://github.com/qasimhassan65/vetra/tree/main/icons/"
    click Content "https://github.com/qasimhassan65/vetra/blob/main/content.js"
    click Background "https://github.com/qasimhassan65/vetra/blob/main/background.js"
    click PopupUI "https://github.com/qasimhassan65/vetra/blob/main/popup.html"
    click PopupUI "https://github.com/qasimhassan65/vetra/blob/main/popup.css"
    click PopupUI "https://github.com/qasimhassan65/vetra/blob/main/popup.js"
    click Config "https://github.com/qasimhassan65/vetra/blob/main/config.js"
    click Config "https://github.com/qasimhassan65/vetra/blob/main/config.example.js"

    classDef extension fill:#E0F7FF,stroke:#0066CC,color:#003366
    classDef storage fill:#E0FFE0,stroke:#339933,color:#336633
    classDef external fill:#FFE0B2,stroke:#CC6600,color:#663300
```
