# Admin Dashboard — Feature Checklist

**Date:** 2026-03-04
**Audience:** Senior software engineers, project stakeholders

---

## How to Read This Document

Features are grouped into **MVP** (required for launch) and **Post-MVP** (phased rollout). Within each group, features are ordered by implementation priority.

**Legend:**

| Symbol | Meaning |
|--------|---------|
| `[ ]` | Not started |
| `[~]` | Backend exists, admin UI needed |
| `[x]` | Complete |
| **BE** | Backend work required (new Convex functions) |
| **UI** | Admin frontend work only |
| **3P** | Third-party integration required |

---

## MVP

### 1. Authentication & Authorization

| # | Feature | Status | Notes |
|---|---------|--------|-------|
| 1.1 | Clerk sign-in page (branded, in-app) | `[x]` UI | Replace hosted sign-in redirect |
| 1.2 | Admin user sync (Convex record on sign-in) | `[x]` UI | Wire existing `useStoreUserEffect` hook |
| 1.3 | Role-based auth gate (block non-admin users) | `[x]` UI | `AdminAuthGate` component, query `users.current` |
| 1.4 | Access denied page for customers | `[x]` UI | Sign-out button + storefront link |
| 1.5 | Admin layout shell (header with `UserButton`) | `[x]` UI | Persistent header with session management |
| 1.6 | Route group structure (`(auth)` vs `(dashboard)`) | `[x]` UI | Separate sign-in from protected routes |

> Full implementation plan: [05-admin-auth-implementation-plan.md](./05-admin-auth-implementation-plan.md)

---

### 2. Navigation & Layout

| # | Feature | Status | Notes |
|---|---------|--------|-------|
| 2.1 | Sidebar navigation | `[x]` UI | Collapsible; links to all admin sections |
| 2.2 | Breadcrumbs | `[x]` UI | Context-aware breadcrumb trail |
| 2.3 | Mobile-responsive admin shell | `[x]` UI | Hamburger menu on mobile, full sidebar on `lg:` |
| 2.4 | Active route highlighting | `[x]` UI | Visual indicator for current section |

---

### 3. Product Management (Inventory)

| # | Feature | Status | Notes |
|---|---------|--------|-------|
| 3.1 | Product list page | `[x]` UI | Backend: `products.list` (paginated, filterable by status/category). Build table with search, filters, pagination. |
| 3.2 | Create product form | `[x]` UI | Backend: `products.create`. Form: name, slug, description, status, category, tags. |
| 3.3 | Edit product form | `[x]` UI | Backend: `products.update`. Pre-populated form with all fields. |
| 3.4 | Archive/restore product | `[x]` UI | Backend: `products.archive`. Confirmation dialog. Restore via edit status field. |
| 3.5 | Product image upload | `[x]` BE+UI | Cloudinary server-side upload via Next.js API route (`/api/upload-image`). Background removal (Image Processing API) with dual upload: processed or original. Structured `public_id` + `asset_folder` per product. |
| 3.6 | Image gallery management | `[x]` UI | Drag-and-drop reorder (`@dnd-kit`) with `reorderImages` mutation. Per-image delete with AlertDialog. "Add more" tile. Search-driven product selection with auto-clear. |
| 3.7 | Variant management | `[x]` UI | Variants page with table, create/edit/preview dialogs, activate/deactivate, delete with AlertDialog. |
| 3.8 | Stock quantity editing | `[x]` UI | `stockQuantity` editable in full variant edit dialog. |
| 3.9 | Price and compare-at-price editing | `[x]` UI | `price` and `compareAtPrice` (behind On Sale toggle) editable in variant form. |
| 3.10 | Product SEO fields (title, description) | `[x]` UI | `seoTitle`, `seoDescription`, `canonicalSlug` in collapsible Advanced/SEO section. |
| 3.11 | Product search within admin | `[x]` UI | Debounced search bar on list page; switches between `products.list` and `products.search`. |
| 3.12 | Bulk status change (draft → active, etc.) | `[ ]` BE+UI | New mutation: `products.bulkUpdateStatus`. Multi-select in table. |

---

### 4. Category Management

| # | Feature | Status | Notes |
|---|---------|--------|-------|
| 4.1 | Category list / tree view | `[~]` UI | Backend: `categories.list` (supports `parentId`). Show hierarchical tree. |
| 4.2 | Create category | `[~]` UI | Backend: `categories.create`. Form: name, slug, parent, top-category slug, SEO. |
| 4.3 | Edit category | `[~]` UI | Backend: `categories.update`. |
| 4.4 | Category image upload | `[ ]` BE+UI | Schema has `imageUrl`. Need file upload flow. |

---

### 5. Order Processing

| # | Feature | Status | Notes |
|---|---------|--------|-------|
| 5.1 | Order list page | `[~]` UI | Backend: `orders.listAll` (paginated, filterable by status/paymentStatus). |
| 5.2 | Order detail page | `[~]` UI | Backend: `orders.getById` (returns items, addresses, payment info). |
| 5.3 | Update order status | `[~]` UI | Backend: `orders.updateStatus`. Dropdown or status stepper. |
| 5.4 | Cancel order (admin-initiated) | `[ ]` BE+UI | New mutation: `orders.adminCancel` — cancel regardless of customer rules, update Stripe if paid, restore stock. |
| 5.5 | Create shipping label (Shippo) | `[ ]` BE+UI+3P | New action: `shippo.createLabel` — calls Shippo Transactions API. Store `trackingNumber`, `trackingUrl`, `labelUrl` on order. |
| 5.6 | Print shipping label | `[ ]` UI+3P | Fetch label PDF URL from Shippo, open in new tab / trigger print dialog. |
| 5.7 | Track shipment status | `[ ]` BE+3P | New: Shippo tracking webhook → update order `status` and `trackingUrl`. Or poll Shippo Tracking Status API. |
| 5.8 | Refund order (full) | `[ ]` BE+UI+3P | New action: `stripe.refundPayment` — calls Stripe Refunds API. Update `paymentStatus` to `"refunded"`, `status` to `"refunded"`. |
| 5.9 | Partial refund | `[ ]` BE+UI+3P | Same Stripe Refunds API with `amount` parameter. |
| 5.10 | Return processing | `[ ]` BE+UI | New: `returns` table or status sub-flow. Accept return request → inspect → refund or reject. |
| 5.11 | Send order update email | `[ ]` BE+3P | New: email service integration (Resend or SendGrid). Triggered on status changes: confirmed, shipped (with tracking), delivered, cancelled, refunded. |
| 5.12 | Send order update SMS | `[ ]` BE+3P | New: SMS integration (Twilio or similar). Triggered on key status changes: shipped, delivered. |
| 5.13 | Order notes (internal) | `[~]` UI | Schema has `notes` field. Admin can add/edit internal notes. |
| 5.14 | Order search / filters | `[ ]` BE+UI | Search by order number, customer email, date range. May need new indexes. |
| 5.15 | Batch label creation | `[ ]` BE+UI+3P | Select multiple orders → create labels via Shippo Batches API. |

---

### 6. Customer Management (MVP-lite)

| # | Feature | Status | Notes |
|---|---------|--------|-------|
| 6.1 | Customer list page | `[~]` UI | Backend: `users.listCustomers` (paginated). |
| 6.2 | Customer detail page | `[ ]` BE+UI | New query: `users.getCustomerDetail` — user + orders + addresses. |
| 6.3 | View customer orders | `[ ]` UI | Link from customer detail to filtered order list. |

---

## Post-MVP

### 7. Dashboard & Analytics

| # | Feature | Status | Notes |
|---|---------|--------|-------|
| 7.1 | Dashboard home — key metrics | `[ ]` BE+UI | New queries: total revenue, order count, new customers (time-windowed). `DashboardStats` type already exists in `@repo/types`. |
| 7.2 | Revenue chart (daily/weekly/monthly) | `[ ]` BE+UI | New query: aggregated revenue by period. Chart library (Recharts or similar). |
| 7.3 | Orders chart | `[ ]` BE+UI | Order volume over time. |
| 7.4 | Top-selling products | `[ ]` BE+UI | New query: aggregate `orderItems` by product, sort by quantity. |
| 7.5 | Low stock alerts | `[ ]` BE+UI | New query: variants where `stockQuantity` < threshold. Dashboard widget + notification badge. |
| 7.6 | Recent orders feed | `[~]` UI | Backend: `orders.listAll` with `limit`. Real-time feed on dashboard. |
| 7.7 | Conversion funnel | `[ ]` BE+UI | Track: visits → cart adds → checkouts → completed orders. Requires analytics events. |

---

### 8. Review Management

| # | Feature | Status | Notes |
|---|---------|--------|-------|
| 8.1 | Review list page (all reviews) | `[~]` UI | Backend: `reviews.listForAdmin` (filterable by approval status, product). |
| 8.2 | Approve review | `[~]` UI | Backend: `reviews.approve`. |
| 8.3 | Delete review | `[~]` UI | Backend: `reviews.deleteReview`. |
| 8.4 | Review detail / preview | `[ ]` UI | Show full review content, images, linked product. |
| 8.5 | Bulk approve/delete | `[ ]` BE+UI | New mutations for batch operations. |

---

### 9. Customer Communication

| # | Feature | Status | Notes |
|---|---------|--------|-------|
| 9.1 | Contact form messages inbox | `[ ]` BE+UI | New `messages` table. Storefront contact form → Convex. Admin reads/replies. |
| 9.2 | Reply to customer message | `[ ]` BE+UI+3P | Send reply via email (Resend/SendGrid). Store thread in Convex. |
| 9.3 | Message status (unread/read/resolved) | `[ ]` BE+UI | Status field on messages table. |
| 9.4 | Email templates | `[ ]` BE+3P | Transactional email templates for order updates, review responses, etc. |

---

### 10. Newsletter & Marketing

| # | Feature | Status | Notes |
|---|---------|--------|-------|
| 10.1 | Newsletter subscriber list | `[ ]` BE+UI | New `subscribers` table. Storefront signup → Convex. Admin views list. |
| 10.2 | Export subscribers (CSV) | `[ ]` UI | Client-side CSV generation from subscriber list. |
| 10.3 | Compose & send newsletter | `[ ]` BE+3P | Integration with email provider (Resend/Mailchimp). Template editor. |
| 10.4 | Unsubscribe handling | `[ ]` BE | Unsubscribe link in emails → Convex mutation. |

---

### 11. Promotions & Discounts

| # | Feature | Status | Notes |
|---|---------|--------|-------|
| 11.1 | Coupon/discount code management | `[ ]` BE+UI+3P | New `coupons` table or Stripe Coupons API (already available via MCP). CRUD UI for codes, percentage/fixed amount, expiry, usage limits. |
| 11.2 | Sale tag management | `[~]` UI | Products already have `tags[]`. Admin can add/remove "sale" tag. Backend: `products.update`. |
| 11.3 | Compare-at-price (was/now pricing) | `[~]` UI | Schema has `compareAtPrice` on variants. Editable in variant management. |

---

### 12. Admin User Management

| # | Feature | Status | Notes |
|---|---------|--------|-------|
| 12.1 | Admin/staff list | `[ ]` BE+UI | New query: `users.listAdmins`. |
| 12.2 | Promote user to admin | `[ ]` BE+UI | New mutation: `users.setRole` (super_admin only). |
| 12.3 | Demote admin to customer | `[ ]` BE+UI | Same `users.setRole` mutation. |
| 12.4 | Activity / audit log | `[ ]` BE+UI | New `auditLogs` table. Log admin actions with userId, action, target, timestamp. |

---

### 13. Settings & Configuration

| # | Feature | Status | Notes |
|---|---------|--------|-------|
| 13.1 | Store settings (name, logo, contact info) | `[ ]` BE+UI | New `storeSettings` table (singleton). |
| 13.2 | Shipping configuration | `[ ]` BE+UI | Default parcel dimensions, weight limits, carrier preferences. Currently hardcoded in `model/shippo.ts`. |
| 13.3 | Tax configuration | `[ ]` BE+UI | Tax rates by region. Currently `tax` is passed manually on order creation. |
| 13.4 | Email notification preferences | `[ ]` BE+UI | Which status changes trigger emails/SMS. |
| 13.5 | Payment settings (Stripe config) | `[ ]` UI | Display Stripe connection status, webhook health. |

---

### 14. Data & Export

| # | Feature | Status | Notes |
|---|---------|--------|-------|
| 14.1 | Export orders (CSV) | `[ ]` UI | Client-side CSV from `orders.listAll`. |
| 14.2 | Export products (CSV) | `[ ]` UI | Client-side CSV from `products.listAll`. |
| 14.3 | Export customers (CSV) | `[ ]` UI | Client-side CSV from `users.listCustomers`. |
| 14.4 | Import products (CSV) | `[ ]` BE+UI | Parse CSV → batch `products.create` calls. |

---

## MVP Scope Summary

| Section | Features | New Backend Work | Third-Party |
|---------|----------|------------------|-------------|
| 1. Auth & Authorization | 6 | None | — |
| 2. Navigation & Layout | 4 | None | — |
| 3. Product Management | 12 | File upload, bulk status | — |
| 4. Category Management | 4 | File upload | — |
| 5. Order Processing | 15 | Cancel, refund, label, tracking, return, email, SMS, search, batch | Shippo, Stripe, Resend/SendGrid, Twilio |
| 6. Customer Management | 3 | Customer detail query | — |
| **Total MVP** | **44** | | |

---

## Third-Party Integration Summary

| Service | Purpose | MVP? | Existing? |
|---------|---------|------|-----------|
| **Clerk** | Authentication | Yes | Yes — sign-in, JWT, webhooks |
| **Convex** | Backend, real-time DB | Yes | Yes — full schema + functions |
| **Stripe** | Payments, refunds | Yes | Partial — checkout exists, refunds needed |
| **Shippo** | Shipping labels, tracking | Yes | Partial — rates/validation exist, labels/tracking needed |
| **Resend** or **SendGrid** | Transactional email | Yes | No — not integrated |
| **Twilio** or **SNS** | SMS notifications | Yes | No — not integrated |
| **Recharts** or **Chart.js** | Dashboard charts | Post-MVP | No |

---

## Recommended Implementation Order (MVP)

```
Phase 1 ─ Auth & Layout (1-2 days)
  ├─ 1.1–1.6  Authentication & authorization
  └─ 2.1–2.4  Navigation & layout shell

Phase 2 ─ Product Management (3-4 days)
  ├─ 3.1–3.4  Product list, create, edit, archive
  ├─ 3.5–3.6  Image upload & gallery
  ├─ 3.7–3.9  Variant CRUD, stock, pricing
  ├─ 3.10–3.11  SEO fields, search
  └─ 4.1–4.4  Category management

Phase 3 ─ Order Processing — Core (2-3 days)
  ├─ 5.1–5.3  Order list, detail, status update
  ├─ 5.4      Admin cancel
  ├─ 5.13–5.14  Order notes, search

Phase 4 ─ Shipping & Labels (2-3 days)
  ├─ 5.5–5.6  Create & print labels (Shippo)
  ├─ 5.7      Track shipments
  └─ 5.15     Batch label creation

Phase 5 ─ Refunds & Returns (1-2 days)
  ├─ 5.8–5.9  Full & partial refund (Stripe)
  └─ 5.10     Return processing

Phase 6 ─ Notifications (1-2 days)
  ├─ 5.11     Order update emails
  └─ 5.12     Order update SMS

Phase 7 ─ Customer Management (1 day)
  └─ 6.1–6.3  Customer list, detail, orders
```

Total estimated MVP effort: **11–17 days** for a senior engineer.