MegaMart

An AI-powered, full-stack e-commerce platform featuring semantic product search, personalized recommendations, an LLM shopping concierge, transactional checkout, and vector similarity search.

Live Demo

MegaMart combines a modern Next.js storefront with an Express API, PostgreSQL/pgvector, Hugging Face embeddings, and Groq tool calling. The application is designed as a deployment-friendly monorepo and does not require a self-hosted machine-learning server.

Highlights

• Semantic product search using natural-language queries
• Personalized recommendations based on purchase history
• AI shopping concierge capable of searching products, managing a cart, and checking out
• JWT authentication with bcrypt password hashing
• Transactional order creation and inventory updates
• PostgreSQL cosine similarity search using pgvector
• Graceful text-search fallback when the embedding provider is unavailable
• Detailed backend request, Hugging Face, and semantic-search logs
• Deployment-ready frontend and backend with validated environment configuration

Architecture

flowchart LR
    User[User Browser]
    Frontend[Next.js Frontend]
    API[Express API]
    Neon[Neon PostgreSQL + pgvector]
    HF[Hugging Face Inference]
    Groq[Groq LLM]

    User --> Frontend
    Frontend -->|"REST + Bearer JWT"| API
    API --> Neon
    API -->|"384-dimensional embeddings"| HF
    API -->|"Tool-calling chat"| Groq

Layer	Technology	Responsibility
Frontend	Next.js 16, React 19, TypeScript, Tailwind CSS v4	Storefront, auth UI, catalog, dashboard, search, orders, and chat
Core API	Node.js, Express 5, TypeScript	Authentication, products, orders, AI orchestration, and business logic
Database	Neon PostgreSQL, Prisma, pgvector	Users, products, carts/orders, inventory, and product embeddings
Embeddings	Hugging Face Inference API, all-MiniLM-L6-v2	Converts search and recommendation text into 384-dimensional vectors
Chat agent	Groq API with function calling	Product discovery, cart actions, and checkout through natural language

The legacy FastAPI service in backend/backend_python/ is retained for local ML experimentation only. It is not required to run or deploy MegaMart.

Core Features

Authentication

• Register with name, email, and password
• Passwords hashed using bcrypt
• Login returns a one-hour JWT
• Protected order, dashboard, and chat routes
• Backend refuses to start when critical environment variables are missing

Product Catalog and Orders

• Browse the complete catalog
• View product details, specifications, reviews, and supplier information
• Create completed orders through the REST API
• Maintain a pending order as the AI-managed shopping cart
• Validate stock and calculate totals using database prices
• Use Prisma transactions for checkout and inventory updates

Semantic Search

1. The user submits a natural-language query such as device for coding.
2. Node sends the text to Hugging Face.
3. all-MiniLM-L6-v2 returns a normalized 384-dimensional vector.
4. PostgreSQL compares it with stored product vectors using cosine distance.
5. The closest products are returned with similarity scores.

If Hugging Face is unavailable or rate-limited, the API falls back to case-insensitive matching against product names, descriptions, and categories.

Personalized Recommendations

1. The dashboard loads the categories from a user's previous orders.
2. Those categories are combined and embedded through Hugging Face.
3. pgvector finds the most semantically similar products.
4. New users receive the latest products as a cold-start fallback.

AI Shopping Concierge

Groq provides the conversational layer and can invoke these backend tools:

• searchCatalog
• viewCart
• addToCart
• checkoutCart

If GROQ_API_KEY is absent or Groq fails, MegaMart uses a local rule-based fallback agent so the chat feature remains usable.

Project Structure

MegaMart/
├── frontend/
│   ├── app/
│   │   ├── dashboard/
│   │   ├── chat/
│   │   ├── login/
│   │   ├── orders/
│   │   ├── products/
│   │   ├── register/
│   │   └── search/
│   └── utils/api.ts
├── backend/
│   ├── backend_node/
│   │   ├── prisma/
│   │   │   ├── schema.prisma
│   │   │   ├── seed.ts
│   │   │   └── update_vectors.ts
│   │   └── src/
│   │       ├── config/
│   │       ├── controllers/
│   │       ├── middlewares/
│   │       ├── routes/
│   │       └── services/
│   └── backend_python/        # Optional legacy/local ML service
└── README.md

API Overview

All Node routes are mounted below /api.

Method	Endpoint	Authentication	Purpose
POST	/api/auth/register	Public	Create an account
POST	/api/auth/login	Public	Authenticate and return a JWT
GET	/api/products	Public	List products
GET	/api/products/:id	Public	Get product details
GET	/api/search?q=...	Public	Semantic product search
POST	/api/orders	JWT	Create a completed order
GET	/api/orders	JWT	Get the user's orders and pending cart
GET	/api/dashboard	JWT	Order statistics and personalized recommendations
POST	/api/chat	JWT	Use the AI shopping concierge

Data Model

• User — account identity and hashed credentials
• Product — catalog data, inventory, description, and vector(384) embedding
• Order — pending cart or completed purchase
• OrderItem — quantity and price snapshot linked to a product

Product vectors are generated from category, name, and description. The same all-MiniLM-L6-v2 model must be used for both stored product vectors and live queries.

Local Setup

Prerequisites

• Node.js and npm
• A PostgreSQL database with the pgvector extension (Neon recommended)
• A Hugging Face token with Make calls to Inference Providers permission
• A Groq API key if real LLM chat is required

여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗