# max-eee/e-commerce-recommender architecture

> Architecture diagram of the GitHub repository max-eee/e-commerce-recommender, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/max-eee/e-commerce-recommender
- Repository: https://github.com/max-eee/e-commerce-recommender

## Overview

This is a Medusa-backed Next.js commerce storefront with an added recommendation demonstration. Its distinctive workflow accepts product and user-behavior data, parses it, scores candidates with a hybrid engine, adds AI explanations and image enrichment, then stores and displays the recommendations. The tree also exposes the standard shopping journey—browse products, inspect details, manage cart, and access an account. Recommendation endpoint and helper relationships are based on sampled source; most storefront page wiring is not sampled, so those links are kept conservative.

Main entry points: [`src/lib/gemini-service.ts`](https://github.com/max-eee/e-commerce-recommender/blob/main/src/lib/gemini-service.ts) (AI Parsing and Explanations), [`src/app/api/recommendations/route.ts`](https://github.com/max-eee/e-commerce-recommender/blob/main/src/app/api/recommendations/route.ts) (Recommendations API), [`src/modules/home/components/input-section/index.tsx`](https://github.com/max-eee/e-commerce-recommender/blob/main/src/modules/home/components/input-section/index.tsx) (Recommendation Input), [`src/modules/store/components/recommendations-section/index.tsx`](https://github.com/max-eee/e-commerce-recommender/blob/main/src/modules/store/components/recommendations-section/index.tsx) (Recommendation Display)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_recommendation_flow["Recommendations"]
  node_input_ui["Recommendation Input<br/>[index.tsx]"]
  node_detect_api["Detect Users API<br/>[route.ts]"]
  node_parse_api["Parse Users API<br/>[route.ts]"]
  node_recommendation_api["Recommendations API<br/>[route.ts]"]
  node_engine["Hybrid Scoring Engine"]
  node_gemini_service["AI Parsing and Explanations<br/>[gemini-service.ts]"]
  node_recommendation_cookie["Recommendation Cookie Utility"]
  node_recommendation_display["Recommendation Display<br/>[index.tsx]"]
  node_recommendations_page["Recommendations Page<br/>[page.tsx]"]
end

subgraph group_commerce_browse["Product Browsing"]
  node_product_pages["Product and Category Pages<br/>[page.tsx]"]
  node_store_pages["Store and Collection Pages<br/>[page.tsx]"]
  node_browse_templates["Browse Templates<br/>[index.tsx]"]
  node_product_template["Product Template<br/>[index.tsx]"]
end

subgraph group_commerce_purchase["Shopping and Account"]
  node_cart_page["Cart Page<br/>[page.tsx]"]
  node_cart_template["Cart Template<br/>[index.tsx]"]
  node_account_pages["Account Pages<br/>[page.tsx]"]
  node_account_template["Account Template<br/>[account-layout.tsx]"]
end

subgraph group_services["External Services"]
  node_medusa[("Medusa Commerce Backend")]
  node_gemini{{"Google Gemini"}}
  node_unsplash{{"Unsplash Image Service"}}
end

subgraph group_commerce_data["Commerce Data"]
  node_catalog_data["Product and Catalog Data<br/>[products.ts]"]
  node_cart_data["Cart Data<br/>[cart.ts]"]
  node_customer_data["Customer Data<br/>[customer.ts]"]
end

node_shopper(("Shopper"))

node_shopper -->|"enters data"| node_input_ui
node_input_ui -->|"detects users"| node_detect_api
node_input_ui -->|"requests recommendations"| node_recommendation_api
node_detect_api -->|"parses input"| node_gemini_service
node_parse_api -->|"parses input"| node_gemini_service
node_recommendation_api -->|"parses data"| node_gemini_service
node_recommendation_api -->|"scores candidates"| node_engine
node_recommendation_api -->|"generates explanations"| node_gemini_service
node_gemini_service -.->|"requests generation"| node_gemini
node_gemini_service -.->|"fetches images"| node_unsplash
node_recommendation_api -->|"returns results"| node_input_ui
node_input_ui -->|"saves results"| node_recommendation_cookie
node_recommendation_display -->|"reads results"| node_recommendation_cookie
node_recommendations_page -->|"renders"| node_recommendation_display
node_recommendation_display -->|"shows suggestions"| node_shopper
node_shopper -->|"browses catalog"| node_store_pages
node_shopper -->|"views product"| node_product_pages
node_store_pages -->|"renders"| node_browse_templates
node_product_pages -->|"renders"| node_product_template
node_browse_templates -->|"loads products"| node_catalog_data
node_product_template -->|"loads product"| node_catalog_data
node_catalog_data -->|"requests catalog"| node_medusa
node_shopper -->|"manages cart"| node_cart_page
node_cart_page -->|"renders"| node_cart_template
node_cart_template -->|"loads cart"| node_cart_data
node_cart_data -->|"requests cart"| node_medusa
node_shopper -->|"manages account"| node_account_pages
node_account_pages -->|"renders"| node_account_template
node_account_template -->|"loads customer"| node_customer_data
node_customer_data -->|"requests customer"| node_medusa

click node_input_ui "https://github.com/max-eee/e-commerce-recommender/blob/main/src/modules/home/components/input-section/index.tsx"
click node_detect_api "https://github.com/max-eee/e-commerce-recommender/blob/main/src/app/api/recommendations/detect-users/route.ts"
click node_parse_api "https://github.com/max-eee/e-commerce-recommender/blob/main/src/app/api/recommendations/parse-users/route.ts"
click node_recommendation_api "https://github.com/max-eee/e-commerce-recommender/blob/main/src/app/api/recommendations/route.ts"
click node_engine "https://github.com/max-eee/e-commerce-recommender/blob/main/src/lib/recommendation-engine.ts"
click node_gemini_service "https://github.com/max-eee/e-commerce-recommender/blob/main/src/lib/gemini-service.ts"
click node_recommendation_cookie "https://github.com/max-eee/e-commerce-recommender/blob/main/src/lib/util/recommendation-cookies.ts"
click node_recommendation_display "https://github.com/max-eee/e-commerce-recommender/blob/main/src/modules/store/components/recommendations-section/index.tsx"
click node_recommendations_page "https://github.com/max-eee/e-commerce-recommender/blob/main/src/app/recommendations/page.tsx"
click node_product_pages "https://github.com/max-eee/e-commerce-recommender/blob/main/src/app/products/%5Bhandle%5D/page.tsx"
click node_store_pages "https://github.com/max-eee/e-commerce-recommender/blob/main/src/app/store/page.tsx"
click node_browse_templates "https://github.com/max-eee/e-commerce-recommender/blob/main/src/modules/store/templates/index.tsx"
click node_product_template "https://github.com/max-eee/e-commerce-recommender/blob/main/src/modules/products/templates/index.tsx"
click node_cart_page "https://github.com/max-eee/e-commerce-recommender/blob/main/src/app/cart/page.tsx"
click node_cart_template "https://github.com/max-eee/e-commerce-recommender/blob/main/src/modules/cart/templates/index.tsx"
click node_account_pages "https://github.com/max-eee/e-commerce-recommender/blob/main/src/app/account/%40dashboard/page.tsx"
click node_account_template "https://github.com/max-eee/e-commerce-recommender/blob/main/src/modules/account/templates/account-layout.tsx"
click node_catalog_data "https://github.com/max-eee/e-commerce-recommender/blob/main/src/lib/data/products.ts"
click node_cart_data "https://github.com/max-eee/e-commerce-recommender/blob/main/src/lib/data/cart.ts"
click node_customer_data "https://github.com/max-eee/e-commerce-recommender/blob/main/src/lib/data/customer.ts"

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_input_ui,node_detect_api,node_parse_api,node_recommendation_api,node_engine,node_gemini_service,node_recommendation_cookie,node_recommendation_display,node_recommendations_page toneBlue
class node_product_pages,node_store_pages,node_browse_templates,node_product_template toneAmber
class node_cart_page,node_cart_template,node_account_pages,node_account_template toneMint
class node_medusa,node_gemini,node_unsplash toneRose
class node_catalog_data,node_cart_data,node_customer_data,node_shopper toneIndigo
```

## Components

### Recommendations

- [Recommendation Input](https://github.com/max-eee/e-commerce-recommender/blob/main/src/modules/home/components/input-section/index.tsx): `src/modules/home/components/input-section/index.tsx`
- [Detect Users API](https://github.com/max-eee/e-commerce-recommender/blob/main/src/app/api/recommendations/detect-users/route.ts): `src/app/api/recommendations/detect-users/route.ts`
- [Parse Users API](https://github.com/max-eee/e-commerce-recommender/blob/main/src/app/api/recommendations/parse-users/route.ts): `src/app/api/recommendations/parse-users/route.ts`
- [Recommendations API](https://github.com/max-eee/e-commerce-recommender/blob/main/src/app/api/recommendations/route.ts): `src/app/api/recommendations/route.ts`
- [Hybrid Scoring Engine](https://github.com/max-eee/e-commerce-recommender/blob/main/src/lib/recommendation-engine.ts): `src/lib/recommendation-engine.ts`
- [AI Parsing and Explanations](https://github.com/max-eee/e-commerce-recommender/blob/main/src/lib/gemini-service.ts): `src/lib/gemini-service.ts`
- [Recommendation Cookie Utility](https://github.com/max-eee/e-commerce-recommender/blob/main/src/lib/util/recommendation-cookies.ts): `src/lib/util/recommendation-cookies.ts`
- [Recommendation Display](https://github.com/max-eee/e-commerce-recommender/blob/main/src/modules/store/components/recommendations-section/index.tsx): `src/modules/store/components/recommendations-section/index.tsx`
- [Recommendations Page](https://github.com/max-eee/e-commerce-recommender/blob/main/src/app/recommendations/page.tsx): `src/app/recommendations/page.tsx`

### Product Browsing

- [Product and Category Pages](https://github.com/max-eee/e-commerce-recommender/blob/main/src/app/products/%5Bhandle%5D/page.tsx): `src/app/products/[handle]/page.tsx`
- [Store and Collection Pages](https://github.com/max-eee/e-commerce-recommender/blob/main/src/app/store/page.tsx): `src/app/store/page.tsx`
- [Browse Templates](https://github.com/max-eee/e-commerce-recommender/blob/main/src/modules/store/templates/index.tsx): `src/modules/store/templates/index.tsx`
- [Product Template](https://github.com/max-eee/e-commerce-recommender/blob/main/src/modules/products/templates/index.tsx): `src/modules/products/templates/index.tsx`

### Shopping and Account

- [Cart Page](https://github.com/max-eee/e-commerce-recommender/blob/main/src/app/cart/page.tsx): `src/app/cart/page.tsx`
- [Cart Template](https://github.com/max-eee/e-commerce-recommender/blob/main/src/modules/cart/templates/index.tsx): `src/modules/cart/templates/index.tsx`
- [Account Pages](https://github.com/max-eee/e-commerce-recommender/blob/main/src/app/account/%40dashboard/page.tsx): `src/app/account/@dashboard/page.tsx`
- [Account Template](https://github.com/max-eee/e-commerce-recommender/blob/main/src/modules/account/templates/account-layout.tsx): `src/modules/account/templates/account-layout.tsx`

### External Services

- **Medusa Commerce Backend**
- **Google Gemini**
- **Unsplash Image Service**

### Commerce Data

- [Product and Catalog Data](https://github.com/max-eee/e-commerce-recommender/blob/main/src/lib/data/products.ts): `src/lib/data/products.ts`
- [Cart Data](https://github.com/max-eee/e-commerce-recommender/blob/main/src/lib/data/cart.ts): `src/lib/data/cart.ts`
- [Customer Data](https://github.com/max-eee/e-commerce-recommender/blob/main/src/lib/data/customer.ts): `src/lib/data/customer.ts`

### Other components

- **Shopper**

## Connections

- Shopper → Recommendation Input: enters data
- Recommendation Input → Detect Users API: detects users
- Recommendation Input → Recommendations API: requests recommendations
- Detect Users API → AI Parsing and Explanations: parses input
- Parse Users API → AI Parsing and Explanations: parses input
- Recommendations API → AI Parsing and Explanations: parses data
- Recommendations API → Hybrid Scoring Engine: scores candidates
- Recommendations API → AI Parsing and Explanations: generates explanations
- AI Parsing and Explanations → Google Gemini: requests generation
- AI Parsing and Explanations → Unsplash Image Service: fetches images
- Recommendations API → Recommendation Input: returns results
- Recommendation Input → Recommendation Cookie Utility: saves results
- Recommendation Display → Recommendation Cookie Utility: reads results
- Recommendations Page → Recommendation Display: renders
- Recommendation Display → Shopper: shows suggestions
- Shopper → Store and Collection Pages: browses catalog
- Shopper → Product and Category Pages: views product
- Store and Collection Pages → Browse Templates: renders
- Product and Category Pages → Product Template: renders
- Browse Templates → Product and Catalog Data: loads products
- Product Template → Product and Catalog Data: loads product
- Product and Catalog Data → Medusa Commerce Backend: requests catalog
- Shopper → Cart Page: manages cart
- Cart Page → Cart Template: renders
- Cart Template → Cart Data: loads cart
- Cart Data → Medusa Commerce Backend: requests cart
- Shopper → Account Pages: manages account
- Account Pages → Account Template: renders
- Account Template → Customer Data: loads customer
- Customer Data → Medusa Commerce Backend: requests customer