🧠 SKUWise - AI-Powered E-Commerce Intelligence Platform

Every product decision, intelligently guided.

Features • Tech Stack • Installation • Architecture • Screenshots

📖 Table of Contents

Overview
Features
Tech Stack
System Architecture
API Documentation
Security Features
Performance Metrics
Deployment Guide
Troubleshooting
Database Schema
User Workflows
Installation
Environment Variables
Screenshots
Upcoming Features
Contributing
License

🌟 Overview

SKUWise is an advanced AI-powered e-commerce intelligence platform that transforms how businesses analyze products, inventory, and market strategies. Built with cutting-edge AI technology, SKUWise provides real-time insights, predictive analytics, and intelligent recommendations to optimize your e-commerce operations.

🎯 Key Highlights

AI Business Analyst - ChatGPT-style conversational interface for business queries
AI_Vision_Matrix (v7.0) - Multimodal asset extraction from Invoices, PDFs, and Excel
Vector Search - Semantic product search powered by Qdrant
Real-time Analytics - Instant insights on inventory, margins, and trends
Multi-Mode AI - Quick Analysis, Deep Research, Thinking Mode, Shopping Research
Conversation History - Save and resume analysis sessions
Data Sources - Transparent AI responses with source citations

✨ Features

🤖 AI-Powered Analysis

Conversational Interface - Natural language queries for business insights
Multiple AI Modes:
- 🚀 Quick Analysis - Fast insights for immediate decisions
- 🧠 Thinking Mode - Deep reasoning for complex problems
- 🔬 Deep Research - Comprehensive analysis with multiple sources
- 🛒 Shopping Research - Product comparison and recommendations
Context-Aware Responses - AI understands your business context
Source Citations - Every insight backed by data sources

💬 Chat System

ChatGPT-Style UI - Clean, modern chat interface
Conversation Management:
- Create new conversations
- Search conversation history
- Delete old conversations
- Resume previous sessions
Message Features:
- Metric Cards - Automatic heuristic detection of key data patterns
- Strategic Directives - High-visibility callouts for critical AI recommendations
- Dynamic Citations - AI responses with source citations
- Clarification suggestions - Context-aware follow-up question prompts
- Auto-scroll to latest message
Sidebar Navigation:
- Collapsible sidebar
- Recent conversations list
- Search functionality
- Active conversation highlighting

🔍 Search & Discovery

Semantic Search - Find products by meaning, not just keywords
Vector Embeddings - Powered by Google Gemini embeddings
Qdrant Integration - Lightning-fast vector similarity search
Intelligent Ranking - Results ranked by relevance

📊 Analytics & Insights

Gap Analysis - AI-driven diagnosis of market price disparities & revenue leakage
Inventory Liquidity - Intelligent reorder points and stock velocity tracking
Margin Analysis - Profit margins, cost breakdowns, and pricing optimization
Category Normalization - Unified filter system with automated case-insensitive matching
Trend Detection - Identify high-risk inventory and growth opportunities
Predictive Analytics - Machine-learning based demand and trend forecasting

🎨 User Experience

Clean UI - Modern, professional design
Dark/Light Mode - Theme toggle for user preference
Responsive Design - Works on desktop, tablet, and mobile
No Navbar in Chat - Full-screen chat experience
Settings Modal - Easy access to preferences
Smooth Animations - Framer Motion for fluid transitions

🛠️ Tech Stack

Frontend

Framework: Next.js 15.1 (React 19.0)
Styling: TailwindCSS 3.4
Animations: Framer Motion
Icons: Lucide React
Markdown: React Markdown
Theme: next-themes

Backend

Runtime: Node.js
API Routes: Next.js API Routes
Database ORM: Prisma 6.2
Database: PostgreSQL (Neon)
Vector Database: Qdrant
Caching: In-memory + File-based

AI & ML

LLM: Google Gemini 2.0 Flash
Embeddings: Google Gemini text-embedding-004
Vector Search: Qdrant similarity search
Prompt Engineering: Custom system prompts for business analysis

DevOps & Tools

Version Control: Git & GitHub
Package Manager: npm
Environment: dotenv
Linting: ESLint
Formatting: Prettier

🏗️ System Architecture

flowchart TD
    User([User Operator]) <-->|Interface| FE[Next.js Frontend]
    FE <-->|Neural API| BE[API Gateway]
    BE --> DB[(PostgreSQL Database)]
    BE --> VDB[(Qdrant Vector DB)]
    BE <--> AI{Gemini AI Node}
    AI -.->|Embeddings| VDB

    style FE fill:#4F46E5,stroke:#333,stroke-width:2px,color:#fff
    style BE fill:#38B2AC,stroke:#333,stroke-width:2px,color:#fff
    style DB fill:#336791,stroke:#333,stroke-width:2px,color:#fff
    style VDB fill:#DC382C,stroke:#333,stroke-width:2px,color:#fff
    style AI fill:#4285F4,stroke:#333,stroke-width:2px,color:#fff

Data Flow

User Query → Frontend (Next.js)
API Request → Backend API Routes
Vector Search → Qdrant (semantic search)
Database Query → PostgreSQL (structured data)
AI Processing → Google Gemini (analysis & insights)
Response → Frontend (formatted display)

Component Architecture

flowchart LR
    subgraph Frontend["Client Space"]
        H[Homepage] --> CR[Chat Route]
        CR --> CS[Sidebar]
        CR --> MD[Message Display]
    end
    
    subgraph Backend["API Matrix"]
        AR[API Routes] --> AC[AI Logic]
        AR --> DC[Data Flow]
    end
    
    subgraph Data["Intelligence Layer"]
        PR[Prisma] --> PS[(PostgreSQL)]
        QC[Qdrant] --> VDB[(Vector DB)]
        GC[Gemini] --> AI_API[Google AI]
    end
    
    CR ----> AR
    AR ----> Data

    style Frontend fill:#4F46E5,stroke:#333,stroke-width:1px,color:#fff
    style Backend fill:#38B2AC,stroke:#333,stroke-width:1px,color:#fff
    style Data fill:#2D3748,stroke:#333,stroke-width:1px,color:#fff

Technology Integration

Frontend Stack:

Next.js 15.1 with App Router
React Server Components for optimal performance
Client Components for interactivity
TailwindCSS for styling
Framer Motion for animations

Backend Stack:

Next.js API Routes (serverless functions)
Prisma ORM for type-safe database access
Qdrant SDK for vector operations
Google Generative AI SDK

AI Pipeline:

User query → Embedding generation (Gemini)
Vector search → Qdrant similarity search
Context retrieval → Top-k relevant products
Prompt construction → System + User + Context
LLM generation → Gemini 2.0 Flash
Response formatting → Markdown + Sources

📡 API Documentation

Chat Endpoint

POST /api/chat

Processes user queries and returns AI-generated insights.

// Request
{
  "query": string,
  "mode": "quick" | "thinking" | "deep" | "shopping",
  "conversationId"?: string
}

// Response
{
  "answer": string,
  "sources": Array<{id: string, name: string, relevance: number}>,
  "clarifications": string[],
  "conversationId": string
}

Conversations Endpoints

GET /api/conversations

List all conversations.

// Response
{
  "conversations": Array<{
    id: string,
    title: string,
    mode: string,
    createdAt: string,
    updatedAt: string,
    totalQueries: number
  }>
}

POST /api/conversations

Create new conversation.

// Request
{
  "title": string,
  "mode": string,
  "persona"?: string
}

// Response
{
  "conversation": {
    id: string,
    title: string,
    mode: string,
    createdAt: string
  }
}

GET /api/conversations/[id]

Get conversation with messages.

// Response
{
  "conversation": {
    id: string,
    title: string,
    messages: Array<{
      id: string,
      role: "user" | "assistant",
      content: string,
      sources?: any[],
      clarifications?: string[],
      createdAt: string
    }>
  }
}

DELETE /api/conversations/[id]

Delete conversation.

// Response
{
  "success": boolean
}

Feedback Endpoint

POST /api/feedback

Submit user feedback for ML training.

// Request
{
  "messageId": string,
  "feedback": "positive" | "negative",
  "comment"?: string
}

// Response
{
  "success": boolean
}

🔒 Security Features

Authentication & Authorization

API Key Protection - Gemini API key stored in environment variables
Database Security - PostgreSQL with SSL/TLS encryption
CORS Configuration - Restricted to allowed origins
Input Validation - Sanitized user inputs to prevent injection attacks

Data Privacy

No PII Storage - User queries are not permanently stored
Conversation Isolation - Each conversation is isolated by ID
Secure Connections - HTTPS in production
Environment Variables - Sensitive data in .env files

Best Practices

Regular dependency updates
Security headers configured
Rate limiting on API routes
Error handling without exposing internals

⚡ Performance Metrics

Frontend Performance

First Contentful Paint (FCP): < 1.5s
Largest Contentful Paint (LCP): < 2.5s
Time to Interactive (TTI): < 3.5s
Cumulative Layout Shift (CLS): < 0.1

Backend Performance

API Response Time:
- Quick Analysis: < 2s
- Deep Research: < 5s
- Vector Search: < 100ms
Database Queries: < 50ms (indexed)
Embedding Generation: < 500ms

Optimization Techniques

Code Splitting - Lazy load components
Image Optimization - Next.js Image component
Caching - Embedding cache for repeated queries
Bundle Size - Optimized with tree shaking
Server Components - Reduced client-side JavaScript

🚀 Deployment Guide

Vercel Deployment (Recommended)

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel

# Production deployment
vercel --prod

Environment Setup

Database - Create Neon PostgreSQL database
Qdrant - Deploy Qdrant Cloud instance
Gemini API - Get API key from Google AI Studio
Environment Variables - Set in Vercel dashboard

Deployment Flow

graph LR
    A[Push to GitHub] --> B[Vercel Detects Change]
    B --> C[Build Process]
    C --> D[Run Tests]
    D --> E{Tests Pass?}
    E -->|Yes| F[Deploy to Production]
    E -->|No| G[Notify Developer]
    F --> H[Live on Vercel]
    
    style A fill:#4F46E5,stroke:#333,stroke-width:2px,color:#fff
    style F fill:#10B981,stroke:#333,stroke-width:2px,color:#fff
    style G fill:#EF4444,stroke:#333,stroke-width:2px,color:#fff
    style H fill:#10B981,stroke:#333,stroke-width:2px,color:#fff

Post-Deployment

Database Migration - Run npx prisma migrate deploy
Qdrant Setup - Run setup script
Health Check - Verify API endpoints
Monitoring - Set up Vercel Analytics

🛠️ Troubleshooting

Common Issues

Issue: Prisma Client not found

# Solution
npx prisma generate

Issue: Qdrant connection failed

# Check Qdrant URL and API key
# Verify Qdrant instance is running
docker ps | grep qdrant

Issue: Gemini API rate limit

# Solution: Implement caching
# Use embedding cache for repeated queries

Issue: Database migration failed

# Reset database (development only)
npx prisma migrate reset

# Or apply pending migrations
npx prisma migrate deploy

Debug Mode

Enable debug logging:

# .env
DEBUG=true
PRISMA_LOG_LEVEL=debug

Performance Issues

Check bundle size: npm run analyze
Profile with React DevTools
Monitor API response times
Optimize database queries with indexes

🗄️ Database Schema

Product Model

model Product {
  id                String   @id @default(cuid())
  sku               String   @unique
  name              String
  category          String?
  subcategory       String?
  brand             String?
  price             Float
  cost              Float
  stock             Int
  reorderPoint      Int?
  supplier          String?
  description       String?
  tags              String[]
  imageUrl          String?
  createdAt         DateTime @default(now())
  updatedAt         DateTime @updatedAt
}

Conversation Model

model Conversation {
  id           String    @id @default(cuid())
  title        String
  persona      String    @default("growth")
  mode         String    @default("quick")
  totalQueries Int       @default(0)
  createdAt    DateTime  @default(now())
  updatedAt    DateTime  @updatedAt
  messages     Message[]
}

Message Model

model Message {
  id              String       @id @default(cuid())
  conversationId  String
  conversation    Conversation @relation(fields: [conversationId], references: [id], onDelete: Cascade)
  role            String       // "user" or "assistant"
  content         String       @db.Text
  sources         Json?
  clarifications  Json?
  createdAt       DateTime     @default(now())
}

🔄 User Workflows

1. Homepage Search Flow

User enters query → Dropdown menu (AI modes) → Select mode → Submit
→ Create conversation → Redirect to /chat/[id] → Display AI response

2. Chat Conversation Flow

User in chat → Type message → Send → API processes query
→ Vector search (Qdrant) → Database query (PostgreSQL)
→ AI analysis (Gemini) → Display response with sources

3. New Chat Flow

User clicks "New Chat" → API creates conversation
→ Redirect to /chat/[new-id] → Empty state → Ready for queries

4. Search Conversations Flow

User types in search → Real-time filtering → Click conversation
→ Load messages → Display chat history

📥 Installation

Prerequisites

Node.js 18+ and npm
PostgreSQL database (Neon recommended)
Qdrant instance (local or cloud)
Google Gemini API key

Step 1: Clone Repository

git clone https://github.com/YASAR300/SKUWise.git
cd SKUWise

Step 2: Install Dependencies

npm install

Step 3: Environment Variables

Create .env file in root directory:

# Database
DATABASE_URL="postgresql://user:password@host:5432/database"

# Qdrant
QDRANT_URL="http://localhost:6333"
QDRANT_API_KEY="your-qdrant-api-key"

# Google Gemini
GEMINI_API_KEY="your-gemini-api-key"

# App
NEXT_PUBLIC_APP_URL="http://localhost:3000"

Step 4: Database Setup

# Generate Prisma Client
npx prisma generate

# Run migrations
npx prisma migrate dev

# Seed database (optional)
node prisma/seed.mjs

Step 5: Qdrant Setup

# Setup Qdrant collections
node prisma/setup-qdrant.mjs

Step 6: Run Development Server

npm run dev

Open http://localhost:3000 in your browser.

🔐 Environment Variables

Variable	Description	Required	Default
`DATABASE_URL`	PostgreSQL connection string	✅	-
`QDRANT_URL`	Qdrant instance URL	✅	`http://localhost:6333`
`QDRANT_API_KEY`	Qdrant API key	❌	-
`GEMINI_API_KEY`	Google Gemini API key	✅	-
`NEXT_PUBLIC_APP_URL`	App URL	❌	`http://localhost:3000`

📸 Screenshots

Homepage - ChatGPT-Style Search

Clean, modern search interface with AI mode selector, file upload, and voice input

📱 Visual Interface Blueprints

Since the platform is optimized for elite Supply Chain operations, these blueprints represent the high-fidelity UI/UX structure currently implemented.

📦 Catalog Dashboard Architecture

flowchart TD
    Header[Neural Header: Search & Status]
    Filters[Horizontal Category Scrollbar: Furniture | Electronics | Office]
    Sorts[Dedicated Sort Row: Recent | Price | Stock]
    Grid[Asset Matrix: High-Density Product Cards]
    
    Header --> Filters
    Filters --> Sorts
    Sorts --> Grid
    
    style Header fill:#111,stroke:#4F46E5,color:#fff
    style Filters fill:#1a1a1a,stroke:#38B2AC,color:#fff
    style Sorts fill:#1a1a1a,stroke:#38B2AC,color:#fff
    style Grid fill:#000,stroke:#333,color:#fff

📊 Strategic Analysis Node

flowchart LR
    Metrics[Summary Matrix: Gap Analysis | Risk Assets | Sector Map]
    Diagnosis[Root Cause Panel: Diagnostic Report Flow]
    Trend[Disparity Map: Interactive Asset List]
    
    Metrics --> Trend
    Trend --> Diagnosis
    
    style Metrics fill:#111,stroke:#4285F4,color:#fff
    style Trend fill:#1a1a1a,stroke:#DC382C,color:#fff
    style Diagnosis fill:#111,stroke:#38B2AC,color:#fff

💬 Neural Chat Interface

flowchart TB
    Sidebar[Neural History: Saved Sessions & Search]
    Chat[Dynamic Workspace: Message Flow]
    Input[Thinking Input: Neural Modes Selector]
    
    subgraph Response[Elite Response Rendering]
        M_Cards[Metric Cards: Revenue / Stock]
        S_Dir[Strategic Directive Callouts]
    end
    
    Chat --> Response
    Input --> Chat
    Sidebar <--> Chat
    
    style Sidebar fill:#111,stroke:#333,color:#fff
    style Chat fill:#0a0a0a,stroke:#4F46E5,color:#fff
    style Response fill:#111,stroke:#38B2AC,color:#fff

UI/UX Highlights

Modern Design System:

Clean, professional interface with consistent spacing and typography
Glassmorphism effects with backdrop blur
Smooth gradients and subtle shadows
Premium color palette with primary/secondary variants

Responsive Layout:

Mobile-first design approach
Adaptive layouts for desktop, tablet, and mobile
Touch-friendly interactive elements
Optimized for all screen sizes

Theme System:

Dark and Light mode support
System preference detection
Persistent theme selection
Smooth theme transitions

Animations & Interactions:

Framer Motion for fluid animations
Hover states on all interactive elements
Loading states with spinners
Smooth page transitions
Auto-scroll behavior

Accessibility:

Semantic HTML structure
Keyboard navigation support
ARIA labels for screen readers
Focus indicators
Color contrast compliance

Performance:

Optimized bundle size
Lazy loading for images
Code splitting
Fast page loads
Smooth 60fps animations

🚀 Upcoming Features

Phase 1: Enhanced AI Capabilities

Conversation Memory - Context-aware multi-turn dialogue
File Upload (v7.0) - Analyze PDF/Excel/Images via AI Vision Matrix
Source Citations - Transparent data-backed AI insights
Streaming Responses - Real-time AI response streaming
Voice Input - Speech-to-text for business queries
Image Recognition - Pure visual product identification

Phase 2: Advanced Analytics

Custom Dashboards - Personalized analytics views
Report Generation - Automated business reports
Data Visualization - Interactive charts and graphs
Export Functionality - Download insights as PDF/CSV
Scheduled Reports - Automated email reports

Phase 3: Collaboration Features

Team Workspaces - Shared conversations and insights
User Roles - Admin, Analyst, Viewer permissions
Comments & Annotations - Collaborate on insights
Shared Dashboards - Team-wide analytics views

Phase 4: Integration & Automation

Shopify Integration - Direct product sync
WooCommerce Integration - WordPress e-commerce
API Webhooks - Real-time data updates
Slack Integration - Insights in Slack
Email Notifications - Alert on critical insights

Phase 5: Mobile Experience

Progressive Web App (PWA) - Installable mobile app
Mobile-Optimized UI - Touch-friendly interface
Offline Mode - View cached conversations offline
Push Notifications - Mobile alerts

🤝 Contributing

We welcome contributions! Please follow these steps:

Fork the repository
Create a feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

Development Guidelines

Follow existing code style
Write meaningful commit messages
Add comments for complex logic
Test thoroughly before submitting PR
Update documentation if needed

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

📞 Contact & Support

Team Leader: Yasar Khan
GitHub: YASAR300
Repository: SKUWise

Built with ❤️ by the SKUWise Team

Name		Name	Last commit message	Last commit date
prisma		prisma
public		public
src		src
.gitignore		.gitignore
README.md		README.md
build_fix_status.txt		build_fix_status.txt
eslint.config.mjs		eslint.config.mjs
jsconfig.json		jsconfig.json
next.config.mjs		next.config.mjs
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs

Latest commit

History

Folders and files

Repository files navigation