🛍️ UnRetail (VaultGrid)

The Decentralized Operating System for Local Thrift, Vintage & Circular Commerce
Unifying fragmented, offline secondhand store inventories into an ultra-fast, real-time online marketplace.

📑 Table of Contents

📌 Project Overview
✨ Key Features
🏗️ System Architecture & Data Flow
🧰 Tech Stack
📂 Monorepo Structure
🚀 Quick Start & Local Setup
📡 API Reference
🔒 Security & Verification Engine
📜 Available NPM Scripts
🤝 Contributing
📄 License

📌 Project Overview

Traditional thrift, vintage, and secondhand fashion retail is constrained by the 1-of-1 single-stock inventory paradox: each item is physically unique, with distinct condition grades, sizing nuances, and offline in-store walk-in sales risks.

UnRetail solves this with a high-concurrency, unified commerce engine:

Real-Time Single-Item State Machine: Eliminates double-booking between in-store cash sales and digital checkouts.
Sub-50ms Search & Faceted Discovery: Instant typo-tolerant queries across eras, condition tiers, styles, and local shop locations.
Zero-Overhead Direct Media Pipeline: Browser-direct signed uploads to Cloudinary without consuming Node.js API server RAM or CPU cycles.
Merchant KYC & Buyer Protection: Anti-fraud electronic device checklists, verified merchant badges, and escrow-backed payment protection.

✨ Key Features

🛍️ Customer Discovery Portal

Instant Search with Meilisearch: Millisecond-level filtering across categories, subcategories, era (Y2K, 90s, 80s, Vintage), condition (LIKE_NEW, GENTLY_USED, FLAWED), and shop city.
Dynamic 1-of-1 Catalog Feed: Curated item drops, store spotlights, and real-time stock availability flags (AVAILABLE, PENDING, SOLD, SOLD_OFFLINE).
Interactive Cart & Razorpay Checkout: Instant order reservation with dynamic INR currency formatting and Razorpay gateway integration.
Order Tracking & Dispute Filing: Buyer order history with carrier tracking codes, delivery status, and direct dispute escalation.

🏪 Merchant Inventory & POS Desk

Rapid Listing Workflow (< 60 Seconds): Mobile-first item onboarding with automatic Cloudinary client-side pre-signed uploads.
Electronics & Retro Tech Fraud Shield: Specialized verification for secondhand gadgets (Power-on status, screen/sensor clarity, charging ports, IMEI/Serial verification, and declared defect logs).
Physical Store POS Sync: 1-tap Mark as Sold Offline toggle to synchronize in-store retail transactions with the live web feed.
Fulfillment & Dispatch Desk: Real-time order dispatch updates with carrier name and tracking ID integration.

🛡️ Admin Governance & Trust Desk

Merchant KYC Verification Desk: Review Indian identity proof documents (Aadhaar Card, PAN Card, Voter ID, Passport) and merchant selfies with one-click Approve / Reject + audit feedback reason.
Shop Verification & Badging: Grant official verified store badges to reputable local thrift merchants.
Dispute Resolution Console: Review customer claims, investigate order timelines, and trigger automated resolutions.
Platform Analytics & GMV Overview: High-level platform health, catalog metrics, and merchant performance metrics.

🏗️ System Architecture & Data Flow

                                +--------------------------------------------------+
                                |                 NEXT.JS FRONTEND                 |
                                |                   (App Router)                   |
                                |  - Customer Feed  - Merchant Portal - Admin Desk |
                                +--------------------------------------------------+
                                         │                                │
                        (Direct Browser Uploads)                  (REST API Requests)
                                         │                                │
                                         ▼                                ▼
                           +--------------------------+     +--------------------------+
                           |      CLOUDINARY CDN      |     |     NODE.JS / EXPRESS    |
                           |                          |     |        BACKEND API       |
                           | - Photo Compression      |     | - Google OAuth & JWT     |
                           | - Mobile Image Cropping  |     | - Order State Machine    |
                           +--------------------------+     | - Role Guards & RBAC     |
                                                            +--------------------------+
                                                                  │        │        │
                                                 ┌────────────────┘        │        └────────────────┐
                                                 │                         │                         │
                                                 ▼                         ▼                         ▼
                                    +-----------------------+  +-----------------------+  +-----------------------+
                                    |   POSTGRESQL (PRISMA) |  |   RAZORPAY GATEWAY    |  |  MEILISEARCH ENGINE   |
                                    |                       |  |                       |  |                       |
                                    | - Relational DB       |  | - Webhook Signatures  |  | - Sub-50ms Search     |
                                    | - Transaction Locks   |  | - Escrow Order Flow   |  | - Faceted Filters     |
                                    +-----------------------+  +-----------------------+  +-----------------------+

Direct Browser Upload Flow

[Client Browser] ──(1. Request Signature)──> [Express API /cloudinary/signature]
[Client Browser] <──(2. Return HMAC Sig)──── [Express API]
[Client Browser] ──(3. POST image + Sig)───> [Cloudinary CDN]
[Client Browser] <──(4. Return CDN URLs)──── [Cloudinary CDN]
[Client Browser] ──(5. Create Item + URLs)──> [Express API /items] ──> [PostgreSQL + Meilisearch]

🧰 Tech Stack

Layer	Technologies
Frontend	Next.js 15 (App Router), React 19, Tailwind CSS, Framer Motion, Lucide React, Axios
Backend	Node.js (ES Modules), Express.js 4, Prisma ORM 5
Database	PostgreSQL (Hosted on Neon / Supabase / Local PostgreSQL)
Search Engine	Meilisearch (Typo-tolerant fast search & faceted indexing)
Media Pipeline	Cloudinary (Direct pre-signed client uploads & on-the-fly transformations)
Payments	Razorpay (Checkout SDK, Orders API, HMAC-SHA256 Webhook verification)
Authentication	Google OAuth 2.0, JWT (JSON Web Tokens), Role-Based Access Control
Security	Helmet-style security headers, Rate Limiting (`express-rate-limit`), CORS whitelist, Input sanitization

📂 Monorepo Structure

Unretail/
├── package.json               # Root monorepo orchestration scripts
├── README.md                  # Project documentation
│
├── client/                    # Next.js 15 Frontend Application
│   ├── app/                   # Next.js App Router
│   │   ├── (customer)/        # Customer portal (feed, search, item, checkout, orders, shops)
│   │   ├── (merchant)/        # Merchant portal (dashboard, listings, new-item, edit-item, orders)
│   │   ├── admin/             # Admin console (dashboard, login, KYC reviews, disputes)
│   │   ├── layout.jsx         # Root layout with navigation & theme wrappers
│   │   └── page.jsx           # Landing page & platform hero
│   ├── components/            # Reusable UI component library
│   ├── lib/                   # Client utilities, API Axios instance, Auth context
│   ├── public/                # Static brand assets and icons
│   ├── tailwind.config.js     # Tailwind CSS theme configuration
│   └── package.json           # Frontend dependencies
│
└── server/                    # Express.js REST API Backend
    ├── config/                # Meilisearch, Cloudinary & database clients
    ├── scripts/               # Seeding, cleanup, indexing & E2E test scripts
    │   ├── seed-curated-products.js
    │   ├── sync-search.js
    │   └── e2e-api-test.js
    ├── src/
    │   ├── app.js             # Express application initialization & middleware stack
    │   ├── controllers/       # Business logic (Auth, Items, Orders, Payments, Merchant, Disputes)
    │   ├── middlewares/       # JWT Auth, RBAC guards, rate limiters, error handling
    │   ├── prisma/
    │   │   ├── schema.prisma  # PostgreSQL Prisma schema & domain models
    │   │   └── client.js      # Singleton Prisma client instance
    │   ├── routes/            # Modular Express route declarations
    │   └── services/          # Meilisearch sync, payment validation & external helpers
    └── package.json           # Backend dependencies & Prisma scripts

🚀 Quick Start & Local Setup

1. Prerequisites

Make sure you have the following installed on your machine:

Node.js >= 18.17.0 (LTS recommended)
PostgreSQL database running locally or a cloud database URL (e.g. Neon, Supabase)
Meilisearch (Local executable or Docker container)
A free Cloudinary account
A Razorpay test mode account

2. Clone & Install Dependencies

Clone the repository and install dependencies for all workspaces:

# Clone the repository
git clone https://github.com/Bala-Git-code/UnRetail.git
cd Unretail

# Install client and server dependencies
cd client && npm install
cd ../server && npm install
cd ..

3. Environment Configuration

Create the .env files in both server/ and client/ directories based on the provided templates.

⚙️ Server Configuration (`server/.env`)

# Server Port & Environment
PORT=5001
NODE_ENV=development

# PostgreSQL Database Connection
DATABASE_URL="postgresql://postgres:password@localhost:5432/unretail?schema=public"

# JWT Secret & Admin Credentials
JWT_SECRET="your_super_secret_random_jwt_key_here"
GOOGLE_CLIENT_ID="your_google_oauth_client_id.apps.googleusercontent.com"
ADMIN_EMAIL="admin@unretail.in"
ADMIN_PASSWORD="your_secure_admin_password"

# Razorpay Payment Gateway (Test Mode)
RAZORPAY_KEY_ID="rzp_test_YourKeyId"
RAZORPAY_KEY_SECRET="YourRazorpaySecret"
RAZORPAY_WEBHOOK_SECRET="YourRazorpayWebhookSecret"

# Cloudinary CDN Configuration
CLOUDINARY_CLOUD_NAME="your_cloud_name"
CLOUDINARY_API_KEY="your_api_key"
CLOUDINARY_API_SECRET="your_api_secret"

# Meilisearch Engine
MEILISEARCH_HOST="http://localhost:7700"
MEILISEARCH_ADMIN_KEY="masterKey"

# Client CORS URL
CLIENT_URL="http://localhost:3000"

⚙️ Client Configuration (`client/.env.local`)

# Backend API Base URL
NEXT_PUBLIC_API_URL="http://localhost:5001/api/v1"

# Google OAuth Client ID for Client-Side Login
NEXT_PUBLIC_GOOGLE_CLIENT_ID="your_google_oauth_client_id.apps.googleusercontent.com"

4. Running the Application

You can start both frontend and backend concurrently or in separate terminals:

# Option A: Start both via separate terminals

# Terminal 1: Start Express API Server (Port 5001)
npm run dev:server

# Terminal 2: Start Next.js Frontend (Port 3000)
npm run dev:client

Open your browser and navigate to:

Customer Portal / Landing Page: http://localhost:3000
Merchant Dashboard: http://localhost:3000/dashboard
Admin Governance Desk: http://localhost:3000/admin
Backend API Health Check: http://localhost:5001/health

🔒 Security & Verification Engine

Role-Based Access Control (RBAC): Every sensitive API route is protected by authenticateJwt and requireRole(['CUSTOMER', 'MERCHANT', 'ADMIN']).
Pre-Signed Direct Cloudinary Uploads: Image binary payloads never traverse the Express API server memory, preventing memory leaks, DoS vulnerabilities, and server bandwidth saturation.
HMAC-SHA256 Webhook & Signature Verification: Razorpay payment callbacks and webhook events require cryptographic signature validation prior to database state transitions.
Rate Limiting & Defensive Headers: Automated rate limiting on authentication routes (authRateLimiter) and API endpoints (apiRateLimiter) to prevent brute-force attacks.

📜 Available NPM Scripts

Root Directory

Command	Description
`npm run dev:client`	Starts Next.js development server on `http://localhost:3000`
`npm run dev:server`	Starts Express backend server with nodemon on `http://localhost:5001`
`npm run build`	Builds production Next.js frontend bundle
`npm run sync:search`	Synchronizes PostgreSQL products into Meilisearch index
`npm run test:api`	Executes end-to-end API test suite (`server/scripts/e2e-api-test.js`)

Server Directory (`server/`)

Command	Description
`npm run dev`	Run Express server with Nodemon auto-reload
`npm run start`	Run Express server in production mode
`npm run db:migrate`	Apply Prisma database migrations
`npm run db:generate`	Regenerate Prisma Client types
`npm run seed`	Seed database with demo items, shops, and categories
`npm run sync-search`	Index all items into Meilisearch

🤝 Contributing

Contributions are welcome! Please follow these steps:

Fork the Repository
Create a Feature Branch (git checkout -b feature/AmazingFeature)
Commit your Changes (git commit -m 'feat: Add some AmazingFeature')
Push to the Branch (git push origin feature/AmazingFeature)
Open a Pull Request

_{Built with ❤️ for sustainable circular fashion & local thrift communities.}

Navigation Menu

Repository navigation

About

Repository files navigation

🛍️ UnRetail (VaultGrid)

📑 Table of Contents

📌 Project Overview

✨ Key Features

🛍️ Customer Discovery Portal

🏪 Merchant Inventory & POS Desk

🛡️ Admin Governance & Trust Desk

🏗️ System Architecture & Data Flow

Direct Browser Upload Flow

🧰 Tech Stack

📂 Monorepo Structure

🚀 Quick Start & Local Setup

1. Prerequisites

2. Clone & Install Dependencies

3. Environment Configuration

⚙️ Server Configuration (`server/.env`)

⚙️ Client Configuration (`client/.env.local`)

4. Running the Application

🔒 Security & Verification Engine

📜 Available NPM Scripts

Root Directory

Server Directory (`server/`)

🤝 Contributing

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.vscode		.vscode
client		client
server		server
.gitignore		.gitignore
README.md		README.md
package.json		package.json

Latest commit

History

Folders and files

Repository files navigation

🛍️ UnRetail (VaultGrid)

📑 Table of Contents

📌 Project Overview

✨ Key Features

🛍️ Customer Discovery Portal

🏪 Merchant Inventory & POS Desk

🛡️ Admin Governance & Trust Desk

🏗️ System Architecture & Data Flow

Direct Browser Upload Flow

🧰 Tech Stack

📂 Monorepo Structure

🚀 Quick Start & Local Setup

1. Prerequisites

2. Clone & Install Dependencies

3. Environment Configuration

⚙️ Server Configuration (server/.env)

⚙️ Client Configuration (client/.env.local)

4. Running the Application

🔒 Security & Verification Engine

📜 Available NPM Scripts

Root Directory

Server Directory (server/)

🤝 Contributing

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

⚙️ Server Configuration (`server/.env`)

⚙️ Client Configuration (`client/.env.local`)

Server Directory (`server/`)