# 🌟 Buyzaar — Distributed Microservices E-Commerce Platform with RAG AI > **A high-performance, distributed microservices e-commerce platform featuring an AI shopping assistant powered by RAG, pgvector, and Groq LLM.** [![Microservices](https://img.shields.io/badge/Architecture-Distributed%20Microservices-blue.svg)](https://github.com/) [![FastAPI](https://img.shields.io/badge/Backend-FastAPI%20%7C%20Python-009688.svg)](https://fastapi.tiangolo.com/) [![React](https://img.shields.io/badge/Frontend-React%2019%20%7C%20TypeScript-61DAFB.svg)](https://react.dev/) [![pgvector](https://img.shields.io/badge/Vector%20DB-PostgreSQL%20%2B%20pgvector-336791.svg)](https://github.com/pgvector/pgvector) [![Groq AI](https://img.shields.io/badge/LLM-Groq%20Llama%203.1-f55036.svg)](https://groq.com/) [![Redis](https://img.shields.io/badge/Cache-Redis-DC382D.svg)](https://redis.io/) [![Docker](https://img.shields.io/badge/Deployment-Docker%20Compose-2496ED.svg)](https://www.docker.com/) --- ## 📌 Project Overview **Buyzaar** is an enterprise-grade, distributed microservices e-commerce system built to demonstrate scalable cloud architecture, domain-driven decoupling, and practical Generative AI integration. Unlike traditional monolithic applications, Buyzaar is designed with a strict **database-per-service** pattern across seven independent backend microservices. It features an **Nginx API Gateway**, a **Redis** caching tier implementing the Cache-Aside pattern, asynchronous event-driven pipelines via **Inngest**, and an integrated **Retrieval-Augmented Generation (RAG) Recommendation Service** that allows shoppers to discover products conversationally using natural language and budget constraints. --- ## 🛠️ Technology Stack ```text React 19, TypeScript, Vite, Tailwind CSS v4, Shadcn UI, Radix UI, Redux Toolkit, TanStack Query, Python, FastAPI, Uvicorn, SQLAlchemy, Alembic, PostgreSQL (Neon), pgvector, Redis, Inngest, LangChain, Hugging Face, Groq LLM, Nginx, Docker, Docker Compose, Cashfree Payment Gateway, Cloudinary, JWT Authentication ``` ### Categorized Breakdown | Domain | Technologies | |---|---| | **Frontend & UI** | React 19, TypeScript, Vite, Tailwind CSS v4, Shadcn UI, Radix UI, Redux Toolkit, TanStack Query, Axios, Lucide Icons | | **Backend Microservices** | Python 3.11+, FastAPI, Uvicorn, Pydantic, SQLAlchemy ORM, Alembic Migrations, HTTPX | | **AI, RAG & Vector Search** | Groq AI (`llama-3.1-8b-instant`), LangChain, Hugging Face (`sentence-transformers/all-MiniLM-L6-v2`), pgvector (PostgreSQL), Inngest | | **Databases & Caching** | Neon Serverless PostgreSQL (Database-per-Service), Redis (Cache-Aside pattern) | | **Gateway & Security** | Nginx API Gateway, JWT Authentication (HS256 via HttpOnly Secure Cookies), SHA256 HMAC Webhook Verification | | **Third-Party Integrations** | Cashfree Sandbox Payment Gateway, Cloudinary CDN (Image Management) | | **DevOps & Containerization** | Docker, Docker Compose, Multi-stage builds | --- ## 🏗️ System Architecture Buyzaar decouples domain boundaries into seven autonomous microservices, orchestrated through a centralized reverse proxy gateway and backed by independent serverless databases. ```mermaid flowchart TD subgraph ClientLayer ["Client Layer"] Client["React 19 + TypeScript SPA"] end subgraph GatewayLayer ["Gateway & Edge Layer"] Gateway["Nginx API Gateway (Port 80/443)"] end subgraph Microservices ["Microservices Layer (FastAPI)"] UserSvc["User Service (:8000)"] ProdSvc["Product Service (:8000)"] CartSvc["Cart Service (:8000)"] ReviewSvc["Review Service (:8000)"] OrderSvc["Order Service (:8000)"] PaySvc["Payment Service (:5000)"] RecoSvc["Recommendation Service (:8003)"] end subgraph StorageLayer ["Data & Caching Layer (Database-per-Service)"] UserDB[("Neon Postgres: User DB")] ProdDB[("Neon Postgres: Product DB")] CartDB[("Neon Postgres: Cart DB")] ReviewDB[("Neon Postgres: Review DB")] OrderDB[("Neon Postgres: Order DB")] PayDB[("Neon Postgres: Payment DB")] VectorDB[("PostgreSQL + pgvector: Embeddings DB")] RedisCache[("Redis Caching Tier")] end subgraph ExternalServices ["External Providers & Event Bus"] Cloudinary["Cloudinary CDN"] Cashfree["Cashfree Payment Gateway"] Groq["Groq Cloud (Llama 3.1)"] Inngest["Inngest Event Bus"] end %% Client to Gateway Client <-->|HTTP REST / Cookies| Gateway %% Gateway Routing Gateway -->|/auth/*| UserSvc Gateway -->|/api/products/*| ProdSvc Gateway -->|/api/carts/*| CartSvc Gateway -->|/review/*| ReviewSvc Gateway -->|/orders/*| OrderSvc Gateway -->|/payments/*| PaySvc Gateway -->|/api/rag/* & /api/chat| RecoSvc %% Service to Database UserSvc <--> UserDB ProdSvc <--> ProdDB CartSvc <--> CartDB ReviewSvc <--> ReviewDB OrderSvc <--> OrderDB PaySvc <--> PayDB RecoSvc <--> VectorDB %% Caching ProdSvc <-->|Cache Catalog| RedisCache CartSvc <-->|Cache User Carts| RedisCache ReviewSvc <-->|Cache Reviews| RedisCache RecoSvc <-->|Cache RAG Queries| RedisCache %% External UserSvc -->|Avatar Uploads| Cloudinary ProdSvc -->|Product Images| Cloudinary PaySvc <-->|Create Session & Webhooks| Cashfree RecoSvc <-->|Inference| Groq %% Asynchronous Events ProdSvc -.->|product.created/updated/deleted| Inngest Inngest -.->|Trigger Vector Sync| RecoSvc %% Inter-service calls PaySvc -.->|Update Order Status| OrderSvc PaySvc -.->|Clear Cart on Success| CartSvc ``` --- ## 🤖 AI Shopping Assistant & RAG Pipeline Buyzaar includes a conversational shopping assistant that goes beyond naive keyword search. It converts user queries into dense 384-dimensional vector embeddings, conducts cosine similarity searches within PostgreSQL via `pgvector`, and applies dynamic price filters before synthesizing responses through Groq's high-speed inference engine. ```mermaid sequenceDiagram autonumber actor User as Shopper (Browser) participant Client as React Client participant GW as Nginx Gateway participant RS as Recommendation Service participant HF as HuggingFace (MiniLM-L6-v2) participant DB as pgvector Database participant Groq as Groq LLM (Llama 3.1) User->>Client: "Find a mechanical keyboard under 3000" Client->>GW: POST /api/chat (Query + Session) GW->>RS: Proxy request to Recommendation Service RS->>RS: Extract Price Constraints (max_price = 3000) RS->>HF: Generate 384D Vector for "mechanical keyboard" HF-->>RS: Return dense embedding vector RS->>DB: Cosine Distance Search (<=>) with price <= 3000 DB-->>RS: Return Top-K Ranked Matching Products RS->>Groq: Prompt with User Query + Grounded Context Groq-->>RS: Grounded Natural Response + Product References RS-->>GW: JSON { reply, products: [ { id, title, price, image, rating } ] } GW-->>Client: HTTP 200 OK Client-->>User: Renders AI Chat Message + Interactive Product Cards ``` ### RAG Architecture Highlights: * **Vector Model**: `sentence-transformers/all-MiniLM-L6-v2` produces compact, high-efficiency 384-dimensional vectors. * **Hybrid Budget Filtering**: Natural language parsing extracts budgetary caps (e.g., *"under ₹15,000"*, *"below 500"*) and applies SQL-level `WHERE price <= :budget` conditions to vector matches, eliminating hallucinated out-of-budget recommendations. * **LLM Fallback Cascade**: Primary inference powered by `llama-3.1-8b-instant` with automatic fallback to `llama-3.3-70b-versatile` and `gemma2-9b-it` if rate limits or latency thresholds are hit. * **Real-time Event Synchronization**: Product catalog mutations in the Product Service dispatch `product.created`, `product.updated`, and `product.deleted` events through **Inngest**, triggering immediate vector updates in pgvector without manual administrative intervention. * **Out-of-Catalog Guardrails**: Automatically identifies off-topic or out-of-catalog inquiries and renders an alert banner to preserve conversational relevance. --- ## 💳 Checkout & Cryptographic Payment Flow Payment security is enforced using a webhook-based verification flow with Cashfree Payment Gateway and SHA256 HMAC cryptographic signature validation. ```mermaid sequenceDiagram autonumber actor Customer as Customer participant Client as React App participant GW as Nginx Gateway participant Ord as Order Service participant Pay as Payment Service participant CF as Cashfree Gateway participant Cart as Cart Service Customer->>Client: Click "Proceed to Checkout" Client->>GW: POST /orders/checkout GW->>Ord: Validate cart items and pricing with Product Service Ord->>Pay: POST /payments/create-session Pay->>CF: Create Order Session (Amount, Customer Info) CF-->>Pay: Return payment_session_id Pay-->>Ord: Return session credentials Ord-->>GW: Return order details & payment_session_id GW-->>Client: Forward order & payment session Client->>CF: Mount Cashfree Drop SDK & Complete Payment CF->>GW: POST /webhook/cashfree (Signature + Payload) GW->>Pay: Forward Webhook Payload Pay->>Pay: Verify Cryptographic SHA256 HMAC Signature alt Valid Signature & Payment Success Pay->>Pay: Mark Payment Record as SUCCESS Pay->>Ord: POST /orders/notify (Status: PAID) Ord->>Ord: Transition order to "Processing" Pay->>Cart: DELETE /api/carts/user/{id} Cart->>Cart: Evict cart records from Postgres & Redis Pay-->>CF: HTTP 200 OK else Invalid Signature / Failed Transaction Pay->>Pay: Mark Payment Record as FAILED Pay->>Ord: POST /orders/notify (Status: CANCELLED) Ord->>Ord: Transition order to "Cancelled" end ``` --- ## 🔑 Key Engineering & Architectural Highlights ### 1. Database-Per-Service Pattern Each domain microservice owns its schema in Neon Serverless PostgreSQL. No microservice ever executes queries directly against another service's database. Cross-service data requirements are satisfied through authenticated REST endpoints and asynchronous event triggers. ### 2. High-Performance Redis Caching (Cache-Aside) - **Product Catalog**: Caches frequent catalog listings and category filters, evicting cache entries on inventory updates. - **Shopping Carts**: Rapid read/write memory store for active user baskets, reducing round-trips to the persistent relational database during cart operations. - **RAG Semantic Caching**: Identical recommendation inquiries leverage cached responses to avoid redundant embedding generations and LLM API round-trips. ### 3. Stateless Cookie-Based JWT Security - **Authentication**: User Service issues an `access_token` stored in an `HttpOnly`, `Secure`, `SameSite=None` cookie. - **Zero-Bottleneck Verification**: Services verify user claims locally using a shared cryptographic secret without sending synchronous validation requests back to the User Service. - **Role-Based Access Control (RBAC)**: Enforces distinct access tiers (`USER` vs `ADMIN`) for operations such as vector re-indexing and product catalog management. ### 4. Resilient Nginx API Gateway Acts as a unified reverse proxy shielding internal microservices from external exposure. Handles TLS termination, centralizes CORS headers, and dynamically routes path prefixes to corresponding internal container ports. --- ## 🧩 Microservices Breakdown | Service | Port | Database | Primary Responsibility | |---|---|---|---| | **Nginx API Gateway** | `80`, `443` | — | Single public gateway; reverse proxying; routing; CORS headers. | | **User Service** | `8000` | Postgres (Users) | User registration, login, BCrypt password hashing, JWT creation, profile avatar management. | | **Product Service** | `8000` | Postgres (Products) | Catalog CRUD, brand/category filtering, image uploads (Cloudinary), Redis caching, Inngest event publishing. | | **Cart Service** | `8000` | Postgres (Carts) | Cart management, item quantity bounds checks, pricing sync, Redis cart caching. | | **Review Service** | `8000` | Postgres (Reviews) | Rating submission, review aggregation, average score computation, Redis review cache invalidation. | | **Order Service** | `8000` | Postgres (Orders) | Checkout orchestration, server-side price verification, order state machine (`pending` ➔ `processing` ➔ `shipped`). | | **Payment Service** | `5000` | Postgres (Payments) | Cashfree session creation, webhook ingestion, SHA256 HMAC verification, downstream order & cart updates. | | **Recommendation Service** | `8003` | Postgres + `pgvector` | 384D HuggingFace vector embedding, cosine similarity search, budget filtering, Groq AI RAG chat, admin vector sync console. | ---

Buyzaar

Built with