VOID Admin Dashboard Documentation

This document describes the administration and metrics portal for the VOID platform. It provides analytical tools, stock management, customer controls, and system configurations.

---

1. Technical Stack & Key Libraries

• Framework: Next.js v16.1.6 (App Router) & React 19.
• Styling & Theme:
  • Tailwind CSS v4: Theme styling.
  • Radix UI Primitives: Modular primitives for accessible dialog modals, custom selects, and tabs.
  • Next-Themes: Custom light/dark theme toggles.
• Data Fetching & Cache Management:
  • TanStack React Query (v5): Handles client-side query caching, asynchronous state updates, and automatic cache invalidations.
  • Axios: Configured client with interceptors for API calls.
• Data Visualization:
  • Recharts: Renders responsive SVG charts (area, line, bar, donut, funnel) for store analytics.
• Form Management:
  • React Hook Form: Handles inventory forms, configuration changes, and modal inputs.
• Invoicing:
  • React-To-Print: Prints browser documents for invoice slips.

---

2. Admin Dashboards & Features

A. Dashboard Overview Landing (app/page.tsx)

Displays key performance indicators (KPIs) and summaries:

• Metrics Cards: Displays Total Revenue, Pending Orders, Total Customers, Net Profit, Active Sessions (last 15 min), and Total Visits.
• Recent Orders List: A table of recent checkout transactions.
• Quick Charts: Displays sales charts, top-performing items, and geodistribution graphs.

B. Analytics Center (app/analytics)

Provides deep insights into store performance and visitor behavior:

• Sales & Expense Trends: Renders an area chart showing revenues against operating costs and shipping overheads over selected time ranges (7 days, 30 days, 1 year).
• Conversion Funnel: A funnel chart tracking visitor drop-offs (Visits -> Add to Cart -> Initiate Checkout -> Placed Order).
• UTM Traffic Analysis: Analyzes campaigns and marketing links (utm_source, utm_medium, utm_campaign) to identify top traffic drivers.
• Demographics Chart: Analyzes gender distribution and age ranges.
• Devices & OS Logs: Tracks browser specifications and device types.
• Geographic Distribution: Renders a bar chart showing order volumes by Egyptian governorate.

C. Product Management (app/products)

• Inventory Grid: Tracks stock levels and offers search filters.
• Product Form: Allows staff to modify prices, discount tags, localized descriptions (English/Arabic), size charts, and SEO meta tags.
• Variant Grid Manager: Configures color hex codes, size selections, individual SKUs, and stock allocations for each item.

D. Order Operations (app/orders)

• Order Log Table: Offers search and filter capabilities by delivery status.
• Customer Profiles & Location: Displays visitor IP locations, user-agent details, UTM tags, and payment details.
• Status Workflows: Update order status (Pending -> Processing -> Shipped -> Delivered -> Cancelled).
• Instapay Validation: Verifies reference numbers for Instapay bank transfers.

E. Customer Directory (app/customers)

• Logs customer registration details, IP history, and purchase records.
• Customer Tags: Allows admins to flag customers (e.g. VIP or Risky).
• Internal Admin Notes: Saves notes and annotations directly to customer profiles.

F. Global Settings (app/settings)

Provides control over storefront configurations:

• Store Configuration: Edit store metadata, currencies, and tax rates.
• Low Stock Thresholds: Configures triggers for dashboard notifications.
• Store Maintenance Modes: Toggles storefront states (active, loading, down, maintenance).
• Governorate Shipping database: Manage shipping fees by location.
• Announcement bar text: Configures dynamic announcement text arrays.

G. Operational Bookkeeping (app/expenses)

• Records and categorizes business expenses (materials, advertising, hosting).
• Integrates with the net profit calculators.

H. Staff Settings (app/team)

• Admin dashboard user manager.
• Allocates authorization roles:
  • Admin: Full write and access permissions.
  • Moderator: Manage catalog, orders, and messages.
  • User: Standard read and write permissions.
  • Viewer: Read-only access to charts and tables.

---

3. Data Visualization & Recharts Configuration

The analytics panels transform raw API JSON arrays into charts using Recharts components:

A. Sales & Expense Chart (SalesChart.tsx)

• Type: Composite / Area Chart.
• Data Structure:

  [
    { "date": "2026-07-01", "revenue": 15000, "expense": 5000, "profit": 10000 }
  ]

• Visualization: Shows revenue as a shaded gradient area, expense as a flat bars overlay, and profit as a dynamic line path.

B. Conversion Funnel Chart (ConversionFunnel.tsx)

• Type: Custom Bar Chart representing funnel progression.
• Data Structure:

  [
    { "name": "Visits", "value": 10000, "fill": "#3b82f6" },
    { "name": "Add to Cart", "value": 3500, "fill": "#f59e0b" },
    { "name": "Checkout", "value": 1200, "fill": "#8b5cf6" },
    { "name": "Purchase", "value": 450, "fill": "#10b981" }
  ]

• Visualization: Renders vertical progression blocks to show visitor conversion stages.

C. Geographic Distribution (GeoDistributionChart.tsx)

• Type: Horizontal Bar Chart.
• Data Structure:

  [
    { "name": "Cairo", "value": 120 },
    { "name": "Giza", "value": 95 }
  ]

• Visualization: Displays the top 10 regions by order volume.

---

4. State Management with React Query

The dashboard uses React Query to keep administrative views in sync with the backend.

A. Core Query Keys

• ["adminStats"]: Fetches stats cards and KPI metrics.
• ["productsPerformance"]: Fetches product performance lists.
• ["salesChartData", range]: Fetches sales and expense charts.
• ["orderStatusStats"]: Fetches order status breakdowns.
• ["customerGrowthData"]: Fetches signup growth lines.

B. Mutations & Cache Invalidation

When an administrator modifies a record (e.g. updating an order status or editing inventory levels), the mutation triggers cache invalidation:

const queryClient = useQueryClient();

const updateOrderStatusMutation = useMutation({
  mutationFn: async ({ orderId, status }) => {
    return (await api.put(`/orders/${orderId}/admin`, { status })).data;
  },
  onSuccess: () => {
    // Invalidate queries to trigger background refreshes
    queryClient.invalidateQueries({ queryKey: ["orders"] });
    queryClient.invalidateQueries({ queryKey: ["adminStats"] });
  }
});

---

5. Invoicing & Printing Operations

• Invoice Component: /components/invoice/InvoiceLayout.tsx
• Logic:
  • Displays customer metadata, order items, coupon discounts, shipping costs, and payment reference numbers.
  • Integrates with react-to-print to send print commands directly to the browser.
• Output Styling:
  • Uses CSS media queries @media print to hide navigation headers and sidebars.
  • Generates clear, monochromatic typography optimized for physical printers.

---

6. Axios Request Interceptor (lib/api.ts)

The dashboard connects to the backend API using an Axios client:

• Host configurations: Reads NEXT_PUBLIC_API_URL, falling back to http://localhost:5000/api in development.
• Request Interceptor: Automatically appends the staff authorization token to headers:

  api.interceptors.request.use((config) => {
    if (typeof window !== "undefined") {
      const token = localStorage.getItem("adminToken");
      if (token) {
        config.headers.Authorization = `Bearer ${token}`;
      }
    }
    return config;
  });

• Query Cache Validation: Extends React Query caching states to automatically refetch datasets (like active orders) when mutations are completed.