# harmanjeet-kaur-3/smart-shop-ai architecture

> Architecture diagram of the GitHub repository harmanjeet-kaur-3/smart-shop-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harmanjeet-kaur-3/smart-shop-ai
- Repository: https://github.com/harmanjeet-kaur-3/smart-shop-ai

## Overview

#### Purpose and Runtime Entry Points
SmartShop AI is a full-stack product comparison application: users search and compare products, receive AI recommendations, and manage authentication and wishlists. The React/Vite client starts at `src/main.tsx` and renders application routing/UI from `src/App.tsx`. The Node/Express API is entered through `server.ts`.

#### Frontend Application Shell
The client is organized as route-level experiences backed by reusable product and recommendation UI:
- Product discovery/comparison: `src/pages/Home.tsx`, `src/pages/Search.tsx`, `src/components/ProductCard.tsx`
- Authenticated user areas: `src/pages/Dashboard.tsx`, `src/pages/History.tsx`, `src/pages/Wishlist.tsx`
- Authentication and input/upload flows: `src/pages/Auth.tsx`, `src/pages/Upload.tsx`
- Shared navigation and AI presentation: `src/components/Navbar.tsx`, `src/components/AIRecommendation.tsx`

#### Client-to-API Boundary
`src/services/api.ts` centralizes browser calls to the Express backend, while `src/types.ts` defines frontend domain contracts. UI pages invoke this service rather than directly coupling to server routes. The Vite runtime is configured by `vite.config.ts`; `index.html` is its document entry point.

#### HTTP API and Access Control
The Express server divides core capabilities into route modules:
- Identity/session endpoints: `server/routes/auth.ts`
- Product lookup and search orchestration: `server/routes/search.ts`
- Saved-product management: `server/routes/wishlist.ts`
- Usage or product analytics: `server/routes/analytics.ts`

Authentication enforcement is a middleware boundary in `server/middleware/auth.ts`, separating protected user data flows from public API behavior.

#### Product Enrichment and AI Pipeline
Search requests can cross two service boundaries: product acquisition/scraping in `server/services/scraper.ts`, then AI-driven comparison, specification analysis, or recommendations in `server/services/ai.ts`. The AI service is expected to use the externally configured Groq API via `GROQ_API_KEY`, despite the README’s earlier Gemini wording. Results are returned through API routes for rendering by `src/components/AIRecommendation.tsx` and product-oriented pages.

#### Persistence and Infrastructure
The application uses a local JSON-backed data store, represented by `data/db.json` and accessed through `server/db.ts`. This is the persistence boundary for user-associated state such as wishlists and potentially history/analytics; it is not a separately provisioned database service. Runtime infrastructure is TypeScript across client and server, React/Vite in the browser build path, and Node.js/Express for the API process.

Main entry points: [`server/routes/search.ts`](https://github.com/harmanjeet-kaur-3/smart-shop-ai/blob/main/server/routes/search.ts) (API route modules), [`src/App.tsx`](https://github.com/harmanjeet-kaur-3/smart-shop-ai/blob/main/src/App.tsx) (App routing shell), [`src/pages/Home.tsx`](https://github.com/harmanjeet-kaur-3/smart-shop-ai/blob/main/src/pages/Home.tsx) (Discovery & comparison), [`src/services/api.ts`](https://github.com/harmanjeet-kaur-3/smart-shop-ai/blob/main/src/services/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React/Vite Client"]
  node_vite["Vite document entry<br/>build entry<br/>[index.html]"]
  node_main["React bootstrap<br/>client entry<br/>[main.tsx]"]
  node_app["App routing shell<br/>React application<br/>[App.tsx]"]
  node_discovery["Discovery &amp; comparison<br/>route UI<br/>[Home.tsx]"]
  node_product_card["Product card<br/>shared UI<br/>[ProductCard.tsx]"]
  node_user_areas["User areas<br/>authenticated route UI<br/>[Dashboard.tsx]"]
  node_auth_upload["Auth &amp; upload<br/>route UI<br/>[Auth.tsx]"]
  node_api_client["API client<br/>browser service<br/>[api.ts]"]
  node_ai_ui["AI recommendation UI<br/>shared UI"]
end

subgraph group_api["Express API"]
  node_server{{"Express server<br/>API entry<br/>[server.ts]"}}
  node_routes["API route modules<br/>HTTP routes<br/>[search.ts]"]
  node_auth_middleware["Access control<br/>Express middleware<br/>[auth.ts]"]
  node_db_access["JSON store access<br/>persistence adapter<br/>[db.ts]"]
end

subgraph group_services["Enrichment Services"]
  node_scraper["Product acquisition<br/>scraping service<br/>[scraper.ts]"]
  node_ai_service["AI comparison service<br/>Groq integration<br/>[ai.ts]"]
end

node_db[("Local JSON store<br/>data store<br/>[db.json]")]

node_vite -->|"loads"| node_main
node_main -->|"renders"| node_app
node_app -->|"routes to"| node_discovery
node_app -->|"routes to"| node_user_areas
node_app -->|"routes to"| node_auth_upload
node_discovery -->|"renders"| node_product_card
node_discovery -->|"presents AI results"| node_ai_ui
node_discovery -->|"requests data"| node_api_client
node_user_areas -->|"manages saved state"| node_api_client
node_auth_upload -->|"submits"| node_api_client
node_api_client -->|"HTTP"| node_server
node_server -->|"mounts"| node_routes
node_routes -->|"protects user routes"| node_auth_middleware
node_routes -->|"searches products"| node_scraper
node_scraper -->|"supplies product data"| node_ai_service
node_routes -->|"requests analysis"| node_ai_service
node_routes -->|"reads and writes state"| node_db_access
node_db_access -->|"persists"| node_db

click node_vite "https://github.com/harmanjeet-kaur-3/smart-shop-ai/blob/main/index.html"
click node_main "https://github.com/harmanjeet-kaur-3/smart-shop-ai/blob/main/src/main.tsx"
click node_app "https://github.com/harmanjeet-kaur-3/smart-shop-ai/blob/main/src/App.tsx"
click node_discovery "https://github.com/harmanjeet-kaur-3/smart-shop-ai/blob/main/src/pages/Home.tsx"
click node_product_card "https://github.com/harmanjeet-kaur-3/smart-shop-ai/blob/main/src/components/ProductCard.tsx"
click node_user_areas "https://github.com/harmanjeet-kaur-3/smart-shop-ai/blob/main/src/pages/Dashboard.tsx"
click node_auth_upload "https://github.com/harmanjeet-kaur-3/smart-shop-ai/blob/main/src/pages/Auth.tsx"
click node_api_client "https://github.com/harmanjeet-kaur-3/smart-shop-ai/blob/main/src/services/api.ts"
click node_ai_ui "https://github.com/harmanjeet-kaur-3/smart-shop-ai/blob/main/src/components/AIRecommendation.tsx"
click node_server "https://github.com/harmanjeet-kaur-3/smart-shop-ai/blob/main/server.ts"
click node_routes "https://github.com/harmanjeet-kaur-3/smart-shop-ai/blob/main/server/routes/search.ts"
click node_auth_middleware "https://github.com/harmanjeet-kaur-3/smart-shop-ai/blob/main/server/middleware/auth.ts"
click node_scraper "https://github.com/harmanjeet-kaur-3/smart-shop-ai/blob/main/server/services/scraper.ts"
click node_ai_service "https://github.com/harmanjeet-kaur-3/smart-shop-ai/blob/main/server/services/ai.ts"
click node_db_access "https://github.com/harmanjeet-kaur-3/smart-shop-ai/blob/main/server/db.ts"
click node_db "https://github.com/harmanjeet-kaur-3/smart-shop-ai/blob/main/data/db.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_vite,node_main,node_app,node_discovery,node_product_card,node_user_areas,node_auth_upload,node_api_client,node_ai_ui toneBlue
class node_server,node_routes,node_auth_middleware,node_db_access toneAmber
class node_scraper,node_ai_service toneMint
class node_db toneNeutral
```

## Components

### React/Vite Client

- [Vite document entry](https://github.com/harmanjeet-kaur-3/smart-shop-ai/blob/main/index.html): build entry · `index.html`
- [React bootstrap](https://github.com/harmanjeet-kaur-3/smart-shop-ai/blob/main/src/main.tsx): client entry · `src/main.tsx`
- [App routing shell](https://github.com/harmanjeet-kaur-3/smart-shop-ai/blob/main/src/App.tsx): React application · `src/App.tsx`
- [Discovery & comparison](https://github.com/harmanjeet-kaur-3/smart-shop-ai/blob/main/src/pages/Home.tsx): route UI · Home and search experiences render product comparisons. · `src/pages/Home.tsx`
- [Product card](https://github.com/harmanjeet-kaur-3/smart-shop-ai/blob/main/src/components/ProductCard.tsx): shared UI · `src/components/ProductCard.tsx`
- [User areas](https://github.com/harmanjeet-kaur-3/smart-shop-ai/blob/main/src/pages/Dashboard.tsx): authenticated route UI · Dashboard, history, and wishlist views. · `src/pages/Dashboard.tsx`
- [Auth & upload](https://github.com/harmanjeet-kaur-3/smart-shop-ai/blob/main/src/pages/Auth.tsx): route UI · Authentication and upload flows. · `src/pages/Auth.tsx`
- [API client](https://github.com/harmanjeet-kaur-3/smart-shop-ai/blob/main/src/services/api.ts): browser service · Centralizes browser calls to Express. · `src/services/api.ts`
- [AI recommendation UI](https://github.com/harmanjeet-kaur-3/smart-shop-ai/blob/main/src/components/AIRecommendation.tsx): shared UI · `src/components/AIRecommendation.tsx`

### Express API

- [Express server](https://github.com/harmanjeet-kaur-3/smart-shop-ai/blob/main/server.ts): API entry · `server.ts`
- [API route modules](https://github.com/harmanjeet-kaur-3/smart-shop-ai/blob/main/server/routes/search.ts): HTTP routes · Auth, search, wishlist, and analytics endpoints. · `server/routes/search.ts`
- [Access control](https://github.com/harmanjeet-kaur-3/smart-shop-ai/blob/main/server/middleware/auth.ts): Express middleware · Protects user-associated API flows. · `server/middleware/auth.ts`
- [JSON store access](https://github.com/harmanjeet-kaur-3/smart-shop-ai/blob/main/server/db.ts): persistence adapter · `server/db.ts`

### Enrichment Services

- [Product acquisition](https://github.com/harmanjeet-kaur-3/smart-shop-ai/blob/main/server/services/scraper.ts): scraping service · `server/services/scraper.ts`
- [AI comparison service](https://github.com/harmanjeet-kaur-3/smart-shop-ai/blob/main/server/services/ai.ts): Groq integration · Analyzes specifications and produces recommendations using GROQ_API_KEY. · `server/services/ai.ts`

### Other components

- [Local JSON store](https://github.com/harmanjeet-kaur-3/smart-shop-ai/blob/main/data/db.json): data store · Stores user-associated state such as wishlists and history. · `data/db.json`

## Connections

- Vite document entry → React bootstrap: loads
- React bootstrap → App routing shell: renders
- App routing shell → Discovery & comparison: routes to
- App routing shell → User areas: routes to
- App routing shell → Auth & upload: routes to
- Discovery & comparison → Product card: renders
- Discovery & comparison → AI recommendation UI: presents AI results
- Discovery & comparison → API client: requests data
- User areas → API client: manages saved state
- Auth & upload → API client: submits
- API client → Express server: HTTP
- Express server → API route modules: mounts
- API route modules → Access control: protects user routes
- API route modules → Product acquisition: searches products
- Product acquisition → AI comparison service: supplies product data
- API route modules → AI comparison service: requests analysis
- API route modules → JSON store access: reads and writes state
- JSON store access → Local JSON store: persists