Gravity-Shop

Commerce

• Stripe Checkout Sessions — Server-side session creation with line items from database
• Webhook Fulfillment — Automatic order status transition and inventory decrement on payment
• Atomic Transactions — MongoDB transactions wrap fulfillment to prevent partial updates
• Idempotent Processing — Duplicate webhook deliveries are safely ignored

Tech Stack

Architecture

graph TB
    subgraph Client
        Browser["Browser"]
        R3F["React Three Fiber"]
        Zustand["Zustand Store"]
    end

    subgraph Edge
        MW["Middleware (jose JWT)"]
    end

    subgraph "Next.js Server"
        Pages["App Router Pages"]
        API["API Routes"]
        Auth["Auth API"]
        Checkout["Checkout API"]
        Webhook["Stripe Webhook"]
        AdminAPI["Admin API"]
    end

    subgraph "External Services"
        MongoDB["MongoDB Atlas"]
        Stripe["Stripe"]
        Cloudinary["Cloudinary"]
        Redis["Upstash Redis"]
    end

    Browser --> MW
    MW --> Pages
    MW --> API
    Browser --> R3F
    Browser --> Zustand

    Auth --> MongoDB
    AdminAPI --> MongoDB
    AdminAPI --> Cloudinary
    Checkout --> Stripe
    Checkout --> MongoDB
    Webhook --> MongoDB
    API --> Redis

Project Structure

gravity-shop/
├── app/
│   ├── (admin)/                  # Admin route group
│   │   ├── analytics/page.tsx    # Revenue & sales dashboard
│   │   ├── inventory/page.tsx    # Stock management
│   │   ├── orders/page.tsx       # Order management
│   │   ├── products/page.tsx     # Product CRUD
│   │   ├── settings/page.tsx     # Store configuration
│   │   ├── users/page.tsx        # User management
│   │   ├── layout.tsx            # Admin sidebar layout
│   │   └── page.tsx              # Admin dashboard home
│   ├── (user)/
│   │   ├── account/page.tsx      # User profile & orders
│   │   └── layout.tsx
│   ├── api/
│   │   ├── admin/
│   │   │   ├── analytics/        # GET aggregated stats
│   │   │   ├── inventory/        # GET/PATCH stock levels
│   │   │   ├── orders/           # GET/PATCH orders
│   │   │   ├── products/         # GET/POST products
│   │   │   ├── settings/         # GET/PUT store settings
│   │   │   ├── upload/           # POST file uploads
│   │   │   └── users/            # GET users, PATCH user by ID
│   │   ├── auth/
│   │   │   ├── login/            # POST credentials
│   │   │   └── register/         # POST new account
│   │   ├── checkout/             # POST Stripe session
│   │   ├── health/               # GET service status
│   │   ├── products/             # GET public products
│   │   ├── search/               # GET search results
│   │   └── webhooks/stripe/      # POST Stripe events
│   ├── product/[id]/page.tsx     # Product detail page
│   ├── layout.tsx                # Root layout
│   ├── page.tsx                  # Homepage
│   ├── robots.ts                 # SEO robots
│   └── sitemap.ts                # SEO sitemap
├── components/
│   ├── admin/                    # AdminSidebar, ProductDataGrid, ProductUploadModal, GlowingChart
│   ├── animations/               # CartFlyAnimation
│   ├── auth/                     # AuthModal
│   ├── canvas/                   # Scene, FloatingProduct, Environment
│   ├── cart/                     # CartDrawer, CartItemCard, CartScene, CartSummary
│   ├── product/                  # ProductCard3D, ProductGrid, ProductDetails, ProductViewer, etc.
│   └── ui/                       # Navbar, Hero, SearchPalette, GlassPanel, MagneticCursor, FloatingGradientBackground
├── lib/
│   ├── db/connect.ts             # MongoDB connection singleton
│   ├── models/
│   │   ├── User.ts               # User schema (name, email, password, role, isActive)
│   │   ├── Product.ts            # Product schema (name, slug, price, stock, images, model3d)
│   │   ├── Order.ts              # Order schema (items, status, stripeSessionId)
│   │   └── Setting.ts            # Settings schema (key-value store by category)
│   ├── api-error.ts              # Structured error handling
│   ├── cloudinary.ts             # Upload helper
│   ├── env.ts                    # Environment validation
│   ├── logger.ts                 # Server-side logger
│   └── rate-limit.ts             # Upstash rate limiter
├── store/
│   └── useAppStore.ts            # Zustand store (cart, auth, UI state)
├── middleware.ts                 # Edge JWT verification for /admin routes
├── next.config.mjs
├── tailwind.config.ts
├── tsconfig.json
└── package.json

Installation

# Clone the repository
git clone https://github.com/ashish7802/Gravity-Shop.git
cd Gravity-Shop

# Install dependencies
npm install --legacy-peer-deps

Note: The --legacy-peer-deps flag is required due to peer dependency conflicts between React 18 and @react-three/drei.

Environment Variables

Create a .env.local file in the project root with the following variables:

# MongoDB
MONGODB_URI=

# Authentication
JWT_SECRET=

# Stripe
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=
STRIPE_SECRET_KEY=
STRIPE_WEBHOOK_SECRET=

# Cloudinary
CLOUDINARY_CLOUD_NAME=
CLOUDINARY_API_KEY=
CLOUDINARY_API_SECRET=

# Upstash Redis
UPSTASH_REDIS_REST_URL=
UPSTASH_REDIS_REST_TOKEN=

⚠️ Important: Never commit .env.local to version control. The .gitignore already excludes it.

Running Locally

# Start the development server
npm run dev

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

Production Build

# Build for production
npm run build

# Start the production server
npm start

Stripe Setup

1. Create a Stripe account.
2. Copy your Publishable Key and Secret Key from the Stripe Dashboard → Developers → API Keys.
3. Set up a webhook endpoint pointing to https://your-domain.com/api/webhooks/stripe.
4. Subscribe to the checkout.session.completed event.
5. Copy the Webhook Signing Secret and add it to STRIPE_WEBHOOK_SECRET.

# For local testing with Stripe CLI
stripe listen --forward-to localhost:3000/api/webhooks/stripe

Cloudinary Setup

1. Create a Cloudinary account.
2. Navigate to Dashboard → Settings → Access Keys.
3. Copy Cloud Name, API Key, and API Secret into your environment variables.
4. Product images upload to gravity-shop/images/.
5. 3D models (GLB files) upload to gravity-shop/models/.

MongoDB Setup

1. Create a MongoDB Atlas cluster.
2. Create a database user with read/write permissions.
3. Whitelist your IP address (or use 0.0.0.0/0 for development).
4. Copy the connection string into MONGODB_URI.
5. The application automatically creates these collections on first use:
   • users
   • products
   • orders
   • settings

Admin Dashboard

Access the admin dashboard at /admin after logging in with an admin account.

To create the first admin user, register a normal account and then update the role directly in MongoDB:

db.users.updateOne(
  { email: "your-email@example.com" },
  { $set: { role: "admin" } }
)

Admin Pages

API Routes