# harsh251singh/visual-product-manager architecture

> Architecture diagram of the GitHub repository harsh251singh/visual-product-manager, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harsh251singh/visual-product-manager
- Repository: https://github.com/harsh251singh/visual-product-manager

## Overview

##### Project Type and Purpose
- This is a **full-stack web application** for finding visually similar products.
- Frontend: React + Vite SPA
- Backend: Node.js + Express API
- Database: MongoDB
- Core functionality: image upload/URL input → image processing (Sharp + vector similarity) → search/filter/store results.

##### File Structure
- Top-level folders:
- `frontend/`: React app (components, routes, assets, CSS)
- `backend/`: Express server (config, models, controllers, routes)
- Backend follows an MVC‐style organization (`model/`, `src/controllers/`, `src/routes/`).
- Config/environment (`backend/config/db.js`, `.env` expected).
- Build & startup scripts: `package.json`, `vite.config.js`.

##### README for Architecture Insights
- Authentication (JWT).
- Image processing pipeline using Sharp.
- Cosine similarity computations against precomputed vectors (Kaggle dataset).
- Responsive, Bootstrap‐styled UI.

##### Main Components & Their Roles
A. Client (Browser)
- Hosts React SPA, issues HTTP requests to backend.
- UI Components: Auth, Upload, Processing, Result, Sidebar.

B. Frontend Application (React + Vite)
- Routes (SPA): defined in `frontend/src/routes/index.jsx`.
- API layer: fetch wrappers or direct `fetch`/`axios` calls to backend endpoints.

C. API Gateway / Backend Server (Node.js + Express)
- Entry point: `backend/index.js`
- Routes: `src/routes/index.js` maps URLs (e.g., `/api/auth`, `/api/images`) to controllers.
- Controllers:
- AuthController (`login`, `register`, JWT issuance).
- ImageController (`searchAndStoreSimilarImages`, `getImageResults`, `getUserUploadedImages`).
- Services/Utilities:
- Image processing (Sharp transforms).
- Similarity engine (cosine similarity against stored vectors).
- Database models: `UserModel`, `ImageModel` (via Mongoose).

D. Database (MongoDB)
- Collections: `users`, `images` (stores metadata, vectors, reference to file storage or URLs).

E. External Data / Storage
- Kaggle dataset of random images (preloaded or stored in a cloud bucket/local FS).
- (Optional) Cloud file storage or local disk for uploaded images.

##### Relationships & Data Flows
1. User uploads an image (or inputs URL) → Frontend POST `/api/images/search`.
2. Backend Controller receives request → passes image to Sharp for resizing/formatting.
3. Processed image → vectorized (embedding) → compared (cosine similarity) against vectors in MongoDB.
4. Top-N similar results fetched → stored in `images` collection if user “saves.”
5. Response JSON (image URLs, metadata, similarity scores) → returned to Frontend.
6. Frontend renders results in `Result.jsx`, allows filtering/saving.

Authentication flow: React login/register → POST `/api/auth/login|register` → JWT returned → stored in localStorage → attached to subsequent API requests (Authorization header).

##### Architectural Patterns & Principles
- **Separation of Concerns**: UI vs. API vs. Data layer.
- **MVC (lightweight)** on backend: routers → controllers → models.
- **Stateless API** with JWT auth.
- **Modularization**: distinct controllers for auth vs. image logic.
- **Scalability**: image processing and similarity computations can be extracted into microservices or serverless functions later.

##### Essential Elements
- Notation for asynchronous operations (e.g., vector computation).
- Callouts for third-party libraries (Sharp, Mongoose) if desired.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Client
    Browser["Client (Browser)"]:::external

    %% Frontend Layer
    subgraph "Frontend (React SPA)" 
        direction TB
        Main["main.jsx"]:::frontend
        App["App.jsx"]:::frontend
        Routes["routes/index.jsx"]:::frontend
        AuthUI["Auth.jsx"]:::frontend
        UploadUI["Upload.jsx"]:::frontend
        ProcessingUI["Processing.jsx"]:::frontend
        ResultUI["Result.jsx"]:::frontend
        SidebarUI["Sidebar.jsx"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (Express API)" 
        direction TB
        Entry["index.js"]:::backend
        DBConfig["config/db.js"]:::backend
        RoutesDef["routes/index.js"]:::backend
        subgraph "Controllers" 
            direction TB
            AuthCtrl["authController.js"]:::backend
            SearchCtrl["searchAndStoreSimilarImages.js"]:::backend
            ResultsCtrl["getImageResults.js"]:::backend
            UploadsCtrl["getUserUploadedImages.js"]:::backend
        end
        Service["Image Processing & Similarity Service"]:::service
        subgraph "Models"
            direction TB
            UserModel["UserModel.js"]:::backend
            ImageModel["ImageModel.js"]:::backend
        end
    end

    %% Database
    MongoDB["MongoDB\n(users, images)"]:::database

    %% External Data
    Kaggle["Kaggle Dataset (precomputed vectors)"]:::external

    %% Flows
    Browser -->|"load SPA"| Main
    Main --> App
    App --> Routes
    Routes --> AuthUI
    Routes --> UploadUI
    Routes --> ProcessingUI
    Routes --> ResultUI
    Routes --> SidebarUI

    UploadUI -->|"POST /api/images/search"| RoutesDef
    AuthUI -->|"POST /api/auth/login\nPOST /api/auth/register"| RoutesDef
    RoutesDef --> AuthCtrl
    RoutesDef --> SearchCtrl
    RoutesDef --> ResultsCtrl
    RoutesDef --> UploadsCtrl

    AuthCtrl --> DBConfig
    AuthCtrl --> UserModel
    SearchCtrl --> Service
    ResultsCtrl --> Service
    UploadsCtrl --> Service

    Service --> DBConfig
    Service --> UserModel
    Service --> ImageModel

    Service -->|"vector compare"| MongoDB
    Service -->|"load vectors"| Kaggle

    %% Click Events - Frontend
    click Main "https://github.com/harsh251singh/visual-product-manager/blob/main/frontend/src/main.jsx"
    click App "https://github.com/harsh251singh/visual-product-manager/blob/main/frontend/src/App.jsx"
    click Routes "https://github.com/harsh251singh/visual-product-manager/blob/main/frontend/src/routes/index.jsx"
    click AuthUI "https://github.com/harsh251singh/visual-product-manager/blob/main/frontend/src/components/Auth.jsx"
    click UploadUI "https://github.com/harsh251singh/visual-product-manager/blob/main/frontend/src/components/Upload.jsx"
    click ProcessingUI "https://github.com/harsh251singh/visual-product-manager/blob/main/frontend/src/components/Processing.jsx"
    click ResultUI "https://github.com/harsh251singh/visual-product-manager/blob/main/frontend/src/components/Result.jsx"
    click SidebarUI "https://github.com/harsh251singh/visual-product-manager/blob/main/frontend/src/components/Sidebar.jsx"

    %% Click Events - Backend
    click Entry "https://github.com/harsh251singh/visual-product-manager/blob/main/backend/index.js"
    click DBConfig "https://github.com/harsh251singh/visual-product-manager/blob/main/backend/config/db.js"
    click RoutesDef "https://github.com/harsh251singh/visual-product-manager/blob/main/backend/src/routes/index.js"
    click AuthCtrl "https://github.com/harsh251singh/visual-product-manager/blob/main/backend/src/controllers/auth/authController.js"
    click SearchCtrl "https://github.com/harsh251singh/visual-product-manager/blob/main/backend/src/controllers/imageController/searchAndStoreSimilarImages.js"
    click ResultsCtrl "https://github.com/harsh251singh/visual-product-manager/blob/main/backend/src/controllers/imageController/getImageResults.js"
    click UploadsCtrl "https://github.com/harsh251singh/visual-product-manager/blob/main/backend/src/controllers/imageController/getUserUploadedImages.js"
    click UserModel "https://github.com/harsh251singh/visual-product-manager/blob/main/backend/model/UserModel.js"
    click ImageModel "https://github.com/harsh251singh/visual-product-manager/blob/main/backend/model/ImageModel.js"

    %% Styles
    classDef frontend fill:#add8e6,stroke:#000
    classDef backend fill:#90ee90,stroke:#000
    classDef database fill:#ffa500,stroke:#000
    classDef external fill:#d3d3d3,stroke:#000
    classDef service fill:#e6e6fa,stroke:#000
```
