NexaByte Electronics Store

Architecture

The project runs two separate processes:

Directory Structure

nexabyte/
├── app/                    Next.js App Router pages
│   ├── _zustand/           Global Zustand store (cart, wishlist)
│   ├── (dashboard)/        Admin dashboard (role-gated)
│   ├── about-us/
│   ├── actions/            Next.js server actions
│   ├── api/                Internal Next.js API routes (NextAuth etc.)
│   ├── cart/
│   ├── checkout/
│   ├── contact-us/
│   ├── faq/
│   ├── feedback/
│   ├── forgot-password/
│   ├── login/
│   ├── notifications/
│   ├── privacy-policy/
│   ├── product/            Single product page [slug]
│   ├── register/
│   ├── reset-password/
│   ├── search/
│   ├── shop/               Product listing / category [[...slug]]
│   ├── terms-of-service/
│   ├── terms-of-use/
│   ├── verify-email/
│   ├── error.tsx
│   ├── globals.css
│   ├── layout.tsx          Root layout (metadata, providers)
│   ├── not-found.tsx
│   └── page.tsx            Homepage
├── components/             Shared React components
├── helpers/                Utility helpers (is-browser, is-small-screen)
├── hooks/                  Custom React hooks
├── lib/                    Auth options, API client, sanitize, utils
├── prisma/                 Root-level Prisma schema (Next.js generate target)
├── public/                 Static assets
├── server/                 Express.js API server
│   ├── controllers/        Business logic for every resource
│   ├── logs/               Request / error log files
│   ├── middleware/         Rate limiting, request logging
│   ├── prisma/             Server-side Prisma schema + migrations
│   ├── routes/             Express route definitions
│   ├── scripts/            Utility / seed scripts
│   ├── services/           Email service (nodemailer / OAuth2)
│   ├── tests/              API test files
│   ├── utils/              Server-side utility helpers
│   ├── app.js              Entry point (port 3001)
│   ├── createAdminUser.js  CLI — create a new admin user
│   ├── makeUserAdmin.js    CLI — promote existing user to admin
│   ├── listUsers.js        CLI — list all registered users
│   └── package.json
├── types/                  Shared TypeScript type definitions
├── utils/                  Frontend utility functions
├── middleware.ts            Next.js route protection middleware
├── next.config.mjs
├── tailwind.config.ts
└── package.json

unzip nexabyte.zip
cd nexabyte

# Install Next.js / frontend dependencies
npm install

# Install Express API server dependencies
cd server && npm install && cd ..

# Push the Prisma schema to your MySQL database
npm run db:push

# Generate Prisma client types
npm run db:generate

node server/createAdminUser.js [email protected] yourpassword

# Option A — built-in concurrent script
npm run start:all

# Option B — two separate terminals
node server/app.js          # terminal 1 → port 3001
npm run dev                 # terminal 2 → port 3000

Available npm Scripts

# ── Database ─────────────────────────────────────────────
DATABASE_URL=mysql://user:password@host:3306/nexabyte

# ── NextAuth ─────────────────────────────────────────────
NEXTAUTH_URL=http://localhost:3000

# ── CORS & base paths ────────────────────────────────────
FRONTEND_URL=https://your-production-domain.com

# ── Gmail OAuth2 (for transactional emails) ───────────────
GMAIL_USER=[email protected]
OAUTH_CLIENT_ID=xxxx.apps.googleusercontent.com
OAUTH_CLIENT_SECRET=GOCSPX-xxxxx
OAUTH_REFRESH_TOKEN=1//xxxxx

# ── S3 / MinIO ───────────────────────────────────────────
NEXT_PUBLIC_S3BUCKET=https://your-s3-endpoint
AWS_BUCKET=your-bucket-name
AWS_ACCESS_KEY_ID=your-access-key-id
AWS_SECRET_ACCESS_KEY=your-secret-access-key
AWS_REGION=ap-southeast-1

Setting up Gmail OAuth2 for email

Creating the MySQL database

CREATE DATABASE nexabyte CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'nexabyte_user'@'%' IDENTIFIED BY 'your_strong_password';
GRANT ALL PRIVILEGES ON nexabyte.* TO 'nexabyte_user'@'%';
FLUSH PRIVILEGES;

Applying the schema

# Push schema to DB (creates/alters tables)
npm run db:push

# Or use migrations for production
npx prisma migrate deploy --schema server/prisma/schema.prisma

Database Models

Prisma Studio (visual DB browser)

npm run db:studio   # opens at http://localhost:5555

1 — Create a brand-new admin user

node server/createAdminUser.js <email> <password>

# Example:
node server/createAdminUser.js [email protected] MyS3cure!Pass

This script will:

• Check if the email is already registered — exits if it is
• Hash the password with bcrypt (10 rounds)
• Create the user with role: "admin" and a UUID
• Print the credentials to the console

2 — Promote an existing user to admin

node server/makeUserAdmin.js <email>

# Example:
node server/makeUserAdmin.js [email protected]

Updates the existing user's role field from "user" to "admin". Safe to run if the user is already an admin — it will just report the current status.

3 — List all registered users

node server/listUsers.js

Prints a table of all users with their ID, email, role, and email verification status. Useful for finding a user's email before calling makeUserAdmin.js.

Authentication Flow

Authentication uses NextAuth.js v4 with a custom Credentials provider.

Dashboard Overview /admin

The main dashboard shows:

• Stats cards — Total revenue, orders, products, and users with trend indicators
• Chart — Revenue/orders trend chart (weekly / monthly / yearly toggle) powered by ApexCharts
• Quick-action cards — One-click links to Products, Orders, Users, Categories, Settings, FAQs, Merchants, and Static Pages

Products /admin/products

Categories /admin/categories

Create, edit, and delete product categories. Each category has a name and an optional icon name (used by the CategoryIcon component to render SVG icons on the storefront).

Orders /admin/orders

Users /admin/users

View all registered customers. See role, email verification status, and join date. Create users, edit their details, or delete accounts. Promote a user to admin from within the UI.

Merchants /admin/merchant

Manage suppliers and merchants that are linked to products. Each merchant has a name, optional email, phone, address, description, and a status (ACTIVE / INACTIVE). Products can be filtered by merchant on the product list.

FAQs /admin/faq

Add, edit, order, and toggle visibility of FAQ items. Each item has a question, answer, category tag, and an order number for display sequence. FAQs appear on the public /faq page.

Feedback /admin/feedbacks

View all customer feedback submissions. Displays name, email, star rating, message, read/unread status, and date. Mark as read or delete. The notification bell shows unread count.

Messages /admin/messages

Inbox for all contact form submissions from the /contact-us page. View full message in a side panel, mark read, or delete. Unread count shown in the notification bell.

Static Pages /admin/static-pages

Edit the rich-text content for:

• Privacy Policy — displayed at /privacy-policy
• Terms of Service — displayed at /terms-of-service
• Terms of Use — displayed at /terms-of-use
• About Us — structured editor for the hero, story, values, stats, and CTA sections at /about-us

All page content is stored in the Setting table with keys prefixed page_*.

Settings /admin/settings

See the Settings Reference section for a complete breakdown of all configurable options.

Notifications Bell

The top-right bell icon in the admin header shows a combined unread count from both Feedback and Contact Messages. Clicking it opens a dropdown with the latest unread items and links to their respective pages.

General Group

Billing Group

Inventory Group

Social Group

Image-type Settings

The following settings accept image uploads directly in the admin UI. Old images are automatically deleted from S3 when replaced.

Static Page Keys

These keys hold rich-text HTML content and are edited via the Static Pages editor in the admin dashboard.

Products

Product Gallery Images

Image Upload

The request must use multipart/form-data with the file field named uploadedFile. Returns { fileUrl }.

Categories

Users

Orders

Settings

Stats (Dashboard)

Authentication (email flows)

Other Endpoints

Rate Limiting

The Express server applies layered rate limiting to protect against abuse:

Storage Structure

All images are stored in S3/MinIO under the bucket defined by AWS_BUCKET. The path structure is:

nexabyte/{folder}/{nanoid}-{timestamp}.ext

# Product images (main + gallery):
nexabyte/products/abc123-1716545600000.jpg

# Site images (logos, hero, favicon):
nexabyte/general/xyz789-1716545600000.png

The public URL for any image is:

{NEXT_PUBLIC_S3BUCKET}/{AWS_BUCKET}/nexabyte/{folder}/filename.ext

Allowed File Types

File Size Limit

Maximum file size: 5 MB per upload.

Automatic S3 Cleanup

Old images are automatically deleted from S3 in these scenarios:

Using MinIO (self-hosted S3)

Set NEXT_PUBLIC_S3BUCKET to your MinIO endpoint (e.g., http://192.168.1.10:9000). The S3 client is already configured with forcePathStyle: true, which is required for MinIO.

Configuring next.config.mjs for images

This is a critical step. Next.js blocks all external images by default. Any domain you serve images from (your S3 endpoint, MinIO host, CDN, etc.) must be explicitly whitelisted in next.config.mjs or <Image> components will throw a runtime error.

const nextConfig = {
  basePath: '', // no base path prefix — app is served at the root

  images: {
    // Set to false if you want Next.js built-in image optimization (recommended for production).
    // Keep true only if you are serving pre-optimized images or using an external CDN.
    unoptimized: true,

    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'your-s3-or-minio-hostname.com', // ← replace with your actual S3/MinIO domain
        port: '',
      },
      {
        protocol: 'https',
        hostname: 'placehold.co', // placeholder images — keep this
        port: '',
      },
      // Add more patterns here for any other external image host you use
    ],
  },

  env: {
    NEXT_PUBLIC_API_BASE_URL: process.env.NEXT_PUBLIC_API_BASE_URL,
  },

  // Security headers — already configured, do not remove
  async headers() {
    return [
      {
        source: '/(.*)',
        headers: [
          { key: 'X-Frame-Options',       value: 'DENY' },
          { key: 'X-Content-Type-Options', value: 'nosniff' },
          { key: 'X-XSS-Protection',      value: '1; mode=block' },
        ],
      },
    ];
  },
};

How to find your hostname

Your hostname is the domain part of your NEXT_PUBLIC_S3BUCKET environment variable — everything between https:// and the first /.

# If your NEXT_PUBLIC_S3BUCKET is:
NEXT_PUBLIC_S3BUCKET=https://storage.mycompany.com

# Then your remotePatterns entry is:
{ protocol: 'https', hostname: 'storage.mycompany.com', port: '' }

Using unoptimized: true vs built-in optimization

Brand Colors

The primary color palette is Tailwind's indigo with a custom yellow accent. To change the primary color, update these files:

theme: {
  extend: {
    colors: {
      // Change this to your brand accent color
      'custom-yellow': '#FED700',
    }
  },
},

For the primary indigo color, replace Tailwind's indigo-* classes in components with your chosen color. The main files to update are:

• components/Hero.tsx — Hero section background and CTA button
• components/DashboardSidebar.tsx — Sidebar active states
• app/globals.css — Range slider color (#3B82F6)
• components/Header.tsx — Cart badge and navigation

Site Name, Logo, and Favicon

These are all configurable via the Admin → Settings → General tab without touching any code:

• Site Name — Updates the browser title dynamically via generateMetadata()
• Site Logo / Footer Logo — Upload via the image upload button next to the setting
• Favicon — Upload an ICO, PNG, or SVG and it becomes the browser tab icon immediately

Homepage Sections

The homepage renders sections as independent components. To hide a section, remove it from app/page.tsx:

// Remove any line below to hide that section:
<Hero />
<IntroducingSection />
<CategoryMenu />
<ProductsSection />
<Testimonial />
{!session && <MemberCTA />}

Adding a New Product Category Icon

Category icons are rendered by the CategoryIcon component. To add a new icon:

Changing the Base Path

If you do need a sub-path, all four places below must be updated in sync:

Currency

Change the currency symbol across the entire site from Admin → Settings → General. Set currency (e.g., EUR) and currency_symbol (e.g., €). All price displays use the useSiteSettings() hook which reads from the settings API.

Testimonials

Testimonials are dynamic — they come from the database, not hardcoded text. Logged-in users can submit feedback with a star rating via the site. The storefront homepage automatically fetches and displays the top 5 highest-rated feedbacks as testimonials using components/Testimonial.tsx.

To manage feedback, go to Admin → Feedback where you can view, read, and delete submitted entries.

Footer Links and Content

Edit components/Footer.tsx to change footer columns, links, and social icons. Social media URLs are pulled from settings (social_facebook, social_instagram, social_twitter).

Production Build

# 1. Generate Prisma client and build Next.js
npm run build

# 2. Start Next.js in production mode
npm start   # port 3000

# 3. Start Express server
node server/app.js   # port 3001

Production Environment Variables

Update the following for production:

Using a Process Manager (PM2)

npm install -g pm2

# Start Express API
pm2 start server/app.js --name nexabyte-api

# Start Next.js
pm2 start npm --name nexabyte-web -- start

# Save process list (survives reboots)
pm2 save
pm2 startup

Nginx Reverse Proxy Example

server {
  listen 80;
  server_name yourdomain.com;

  # Express API — must come before / to avoid swallowing API traffic
  location /api/ {
    proxy_pass         http://localhost:3001;
    proxy_http_version 1.1;
    proxy_set_header   Host $host;
    proxy_set_header   X-Real-IP $remote_addr;
    proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
  }

  # Next.js (frontend) — catch-all
  location / {
    proxy_pass         http://localhost:3000;
    proxy_http_version 1.1;
    proxy_set_header   Upgrade $http_upgrade;
    proxy_set_header   Connection 'upgrade';
    proxy_set_header   Host $host;
    proxy_cache_bypass $http_upgrade;
  }
}

Pre-deployment Checklist

• ✅ Both .env files configured with production values
• ✅ NEXTAUTH_SECRET is a long, random, unpredictable string
• ✅ MySQL database created and schema applied (npm run db:push)
• ✅ S3 bucket created with correct permissions
• ✅ Admin user created via CLI
• ✅ Gmail OAuth2 credentials configured and tested
• ✅ npm run build completes without errors
• ✅ Nginx (or other reverse proxy) configured for both ports
• ✅ HTTPS / SSL certificate provisioned (Let's Encrypt recommended)
• ✅ S3 image hostname added to next.config.mjs remotePatterns