Admin System Quick Start Guide

Last Updated: November 20, 2025 Status: ✅ Ready to Use

🚀 Getting Started

1. Create Admin User

The user must have role: "ADMIN" in the database.

Option A: Use Admin Panel (if available)

1. Navigate to admin settings
2. Create new user with ADMIN role

Option B: Direct Database Update

UPDATE users SET role = 'ADMIN' WHERE email = 'admin@example.com';

2. Login as Admin

1. Navigate to /signin
2. Enter email and password
3. Login
4. Should see "Admin" menu in navigation (after "Blogs")

3. Access Admin Dashboard

Click "Admin" in navigation to see submenu:

• Products → /admin/products
• Categories → /admin/categories
• Images → /admin/images
• Dashboard → /admin

📝 Common Tasks

Add a New Product

1. Go to Admin → Products
2. Click "+ Add Product" button
3. Fill in product details:
   • Title (required)
   • Description (optional)
   • Price (required)
   • Discounted Price (optional)
   • Stock (optional)
   • SKU (optional, e.g., SKU-000001)
   • Category (required)
4. Click "Create Product"
5. You'll be redirected to edit page
6. Upload images:
   • Drag & drop or click to select
   • Choose "Preview" (800x800px) or "Thumbnail" (200x200px)
   • Upload completes automatically
7. Images appear below in a gallery
8. Click "Delete" to remove unwanted images

Edit Existing Product

1. Go to Admin → Products
2. Click "Edit" on the product
3. Update details as needed
4. Add or remove images
5. Click "Update Product"

Delete Product

1. Go to Admin → Products
2. Find the product
3. Click "Delete" button
4. Confirm deletion
5. Product removed from system

Search Products

1. Go to Admin → Products
2. Use search box: "Search by title or SKU..."
3. Type to search (works in real-time)
4. Click "Clear" to reset search
5. Results show with pagination

Manage Categories

1. Go to Admin → Categories
2. View existing categories in tree structure:
   • Parent categories (blue)
   • Child categories indented

Add Category:

1. Click "+ Add Category"
2. Fill in:
   • Title (required)
   • Slug (required, URL-friendly)
   • Image URL (optional)
   • Description (optional)
   • Parent (optional, for subcategories)
3. Click "Create Category"

Edit Category:

1. Click "Edit" on category
2. Update details
3. Click "Update Category"

Delete Category:

1. Click "Delete" on category
2. Confirm (products stay in system)

View Image Audit

1. Go to Admin → Images
2. See report of:
   • Complete products (with images)
   • Partial products (missing some images)
   • Missing products (no images)
3. Shows completion percentage
4. Shows how many files in directory

🖼️ Image Management

Image Naming Convention

All images follow this pattern:

product-{id}-{type}-{index}.webp

product-5-bg-1.webp    → Product 5, Preview image 1
product-5-sm-1.webp    → Product 5, Thumbnail image 1
product-5-bg-2.webp    → Product 5, Preview image 2

Image Types

Image Upload

Supported Formats:

• JPG / JPEG
• PNG
• WebP
• GIF

Requirements:

• Max size: 10MB
• Automatically converted to WebP
• Automatically resized to correct dimensions
• Center-cropped if needed

Upload Process:

1. Select image type (Preview or Thumbnail)
2. Drag image onto dropzone OR click to select
3. Progress bar shows upload status
4. Image appears in gallery when complete
5. Can upload multiple images per product

⚙️ Admin Menu Navigation

Menu Structure

Popular
├── Link to home

Shop
├── Link to shop

Contact
├── Link to contact

Pages
├── Shop pages
├── Checkout
├── Wishlist
├── Account
└── Other pages

Blogs
├── Blog Grid
├── Blog Details
└── Archive

Admin ⭐ (ONLY for ADMIN users)
├── Products
│   └── Add/edit/delete products
├── Categories
│   └── Create category hierarchy
├── Images
│   └── View audit report
└── Dashboard
    └── Admin overview

🔒 Security Features

Who Can Access?

What's Protected?

All admin routes are protected:

• ✅ /admin/products
• ✅ /admin/products/new
• ✅ /admin/products/[id]
• ✅ /admin/categories
• ✅ All API endpoints under /api/admin/*

Automatic Redirects

Non-logged-in user tries /admin/products
→ Redirected to /signin

Non-admin user tries /admin/products
→ Redirected to / (home page)

Admin user accesses /admin/products
→ Full access granted ✅

📊 API Reference

Products API

List Products

GET /api/admin/products?page=1&limit=20&search=keyword

Create Product

POST /api/admin/products
{
  "title": "Product Name",
  "description": "Description",
  "price": 99.99,
  "discountedPrice": 79.99,
  "stock": 10,
  "sku": "SKU-000001",
  "categoryId": 1
}

Update Product

PUT /api/admin/products/[id]
{
  "title": "Updated Title",
  ...
}

Delete Product

DELETE /api/admin/products/[id]

Images API

Upload Image

POST /api/admin/products/images
FormData:
  - file: File
  - productId: number
  - type: "THUMBNAIL" | "PREVIEW"

Delete Image

DELETE /api/admin/products/images?id=imageId

Image Audit Report

GET /api/admin/images/audit

Categories API

List Categories

GET /api/admin/categories

Create Category

POST /api/admin/categories
{
  "title": "Category Name",
  "slug": "category-name",
  "description": "Description",
  "parentId": null  // Optional, for subcategories
}

Update Category

PUT /api/admin/categories/[id]
{
  "title": "Updated Title",
  ...
}

Delete Category

DELETE /api/admin/categories/[id]

🆘 Troubleshooting

Admin Menu Not Showing

Problem: "Admin" menu item doesn't appear after login

Solutions:

1. Verify user role is "ADMIN" in database
2. Logout and login again (refresh session)
3. Check browser console for errors
4. Verify NextAuth session includes role

Images Not Uploading

Problem: Image upload fails

Solutions:

1. Check file is valid image format (JPG, PNG, WebP, GIF)
2. Verify file size < 10MB
3. Check directory public/images/products/ exists and is writable
4. Check server logs for Sharp errors

Can't Access Admin Pages

Problem: Redirected when trying to access /admin/products

Solutions:

1. Verify you're logged in
2. Verify your user has role = "ADMIN"
3. Clear browser cache and login again
4. Check middleware.ts is loaded (no errors in logs)

Product Not Saving

Problem: Form submission fails

Solutions:

1. Verify all required fields filled (Title, Price, Category)
2. Check price is a valid number
3. Check category is selected
4. Look for error message in red box
5. Check browser console for errors

💡 Tips & Best Practices

Product Management

• ✅ Always provide meaningful product titles
• ✅ Use descriptive SKU codes for inventory tracking
• ✅ Add both preview and thumbnail images
• ✅ Write detailed descriptions for better SEO
• ✅ Set realistic prices and discounts
• ✅ Keep stock numbers accurate

Image Management

• ✅ Use high-quality source images (original size)
• ✅ Consistency matters - use similar crops/angles
• ✅ Upload preview (big) image first, then thumbnail (small)
• ✅ WebP conversion happens automatically
• ✅ Images are accessible via /images/products/{filename}

Category Management

• ✅ Use clear, descriptive category names
• ✅ Keep hierarchy shallow (1-2 levels max)
• ✅ Use consistent slug format (lowercase, hyphens)
• ✅ Parent categories group related products
• ✅ Delete empty categories to keep clean

Search & Navigation

• ✅ Users can search by product title
• ✅ Users can search by SKU
• ✅ Category filtering works automatically
• ✅ Product counts update in real-time

📞 Support Resources

Documentation Files:

• docs/plans/PLAN_12_ADMIN_PRODUCT_IMAGE_MANAGEMENT.md
• docs/plans/PLAN_12_SUPPLEMENT_ADMIN_NAVIGATION.md
• docs/implementation/PLAN_12_IMPLEMENTATION_SUMMARY.md
• docs/implementation/ADMIN_NAVIGATION_IMPLEMENTATION.md

Code References:

• Product components: src/components/features/admin/ProductForm/*
• Category components: src/components/features/admin/CategoryList/*
• Image widget: src/components/features/admin/ProductForm/ImageUploadWidget/*
• API routes: src/app/api/admin/*
• Utilities: src/lib/image-processing.ts, src/lib/file-naming.ts, src/lib/validators.ts

✅ Verification Checklist

After setup, verify:

• Admin user created with role = "ADMIN"
• Can login successfully
• "Admin" menu appears in navigation
• Can click "Admin" and see submenu
• Can access /admin/products
• Can access /admin/categories
• Can create a test product
• Can upload images to product
• Can edit existing products
• Can delete products
• Non-admin users can't see Admin menu
• Non-admin users redirected from /admin routes

🎉 You're Ready!

The admin system is fully functional. Start managing your products and categories!

Quick Access:

• Products: Click Admin → Products
• Categories: Click Admin → Categories
• Images: Click Admin → Images
• Dashboard: Click Admin → Dashboard

Last Updated: November 20, 2025 Version: 1.0 Status: Production Ready