# ShopDesk Admin Dashboard — Complete User Guide

**Version:** 1.0 (aligned with ShopDesk codebase)  
**Audience:** Administrators, operators, support staff, and integrators who use the web dashboard or need API context.

---

## Table of contents

1. [Introduction](#1-introduction)
2. [How to access the dashboard](#2-how-to-access-the-dashboard)
3. [Top bar: themes, store, docs, currency](#3-top-bar-themes-store-docs-currency)
4. [Navigation map (sidebar)](#4-navigation-map-sidebar)
5. [Section-by-section guide](#5-section-by-section-guide)
6. [Roles and permissions](#6-roles-and-permissions)
7. [Commerce extra access (per staff)](#7-commerce-extra-access-per-staff)
8. [Business operators (restricted dashboard)](#8-business-operators-restricted-dashboard)
9. [Immutable Super Admin (system account)](#9-immutable-super-admin-system-account)
10. [API reference (quick)](#10-api-reference-quick)
11. [Figures and screenshots](#11-figures-and-screenshots)
12. [Related files in the repository](#12-related-files-in-the-repository)

---

## 1. Introduction

The **ShopDesk Admin Dashboard** is the control center for your storefront operations: products, stock, orders, vendors, compliance, commission, tax, notifications, security, and audit. It is served from the ShopDesk web app (typically `index.html` after sign-in).

This guide describes:

- What each **sidebar section** is for  
- Which **permission keys** gate visibility and actions  
- **Primary HTTP APIs** used by each area (for support and integrations)

> **Bookkeeping note:** Many amounts are stored in **USD** on the server. The dashboard can **display** converted amounts using the **Currency** selector in the top bar; that affects labels and formatted numbers, not necessarily the raw API field names.

---

## 2. How to access the dashboard

1. Open the ShopDesk **admin** URL (same host as your API, e.g. `http://127.0.0.1:3000/`).  
2. Sign in with an account that has **`role: admin`**.  
3. The server issues a **Bearer JWT** (stored in session). Subsequent API calls send `Authorization: Bearer <token>`.

| Requirement | Detail |
|-------------|--------|
| Login API | `POST /api/auth/login` |
| Session | `GET /api/auth/me` returns the current user, permissions, and admin role |
| Logout | `POST /api/auth/logout` |

If your account is a **customer** (`role: customer`), you only get a limited view (e.g. product management read-only hints); full governance sections require an **admin** account.

---

## 3. Top bar: themes, store, docs, currency

| Control | Purpose |
|---------|---------|
| **Theme** | Visual theme for the dashboard (Operations, cream, midnight, etc.). |
| **Open store** | Opens the public storefront (`store.html`). |
| **Dashboard docs** | Link to Markdown documentation under `/docs/`. |
| **Currency** | Chooses **display currency** for USD-based amounts (rate from `/api/currencies`). Preference is stored in the browser (`localStorage`) and stays aligned with the storefront when applicable. |
| **Notifications** | In-app notification center (polling). |
| **Chain / tier badges** | Optional UI indicators when blockchain or commission tier features are active. |
| **Sign out** | Ends the session. |

**Illustrative figures** (overview layout and permissions concept) are in [§11](#11-figures-and-screenshots).

---

## 4. Navigation map (sidebar)

The sidebar is grouped into **Overview**, **Governance**, **Commerce**, and **Security & audit**. Each item maps to a **section id** (`data-section`) used in `public/index.html`.

| Group | Section | `data-section` | Typical permission / rule |
|-------|---------|------------------|---------------------------|
| Overview | Dashboard overview | `overview` | `dashboard.read`; KPIs often need `platform.read` |
| Governance | Admin management | `admins` | `staff.read` (Super Admin for create/update/delete) |
| Governance | Roles & permissions | `roles` | `roles.read` |
| Governance | Compliance center | `compliance` | `vendors.read` / `vendors.approve` |
| Governance | Commission settings | `commission` | `commission.read` (writes often Super Admin) |
| Commerce | Vendor management | `vendors` | `vendors.read` / `vendors.write` |
| Commerce | Shop profile | `shop-profile` | Super Admin or `commerce.shop_profile` |
| Commerce | Product management | `products` | `products.read` / `products.write` |
| Commerce | Stock management | `stock` | `inventory.read` / `inventory.adjust` |
| Commerce | Catalog & payments | `catalog` | `catalog.*` / `payments.*` or commerce |
| Commerce | Order management | `orders` | `orders.read` / `orders.write` |
| Commerce | Financial management | `financial` | `platform.read` or `commerce.financial` |
| Commerce | Tax settings | `tax-settings` | `platform.read` or `commerce.tax` |
| Commerce | Notifications | `notifications` | `platform.read` or `commerce.notifications` |
| Commerce | Communications (Deskia) | `communications` | `platform.read` or `commerce.communications` |
| Security & audit | Security center | `security` | `security.read` |
| Security & audit | Audit trail | `audit` | `audit.read` / `audit.export` |
| Security & audit | Blockchain | `blockchain` | **Super Admin** (nav visibility) |
| Security & audit | Account management | `account-management` | **Super Admin** (nav visibility) |

**Body-only sections** (not always in the sidebar) may include **Commission & billing** (`commission-billing`) and **Team chat** (`team-chat`). Team chat may be shown when the app wires it; permissions follow `platform.read` patterns in code.

---

## 5. Section-by-section guide

### 5.1 Dashboard overview

**Purpose:** Cross-cutting KPIs (orders, revenue, customers, stock, admins), **admin wallet** snapshot and ledger preview, and **distance** from the configured store (Haversine).

**Permissions:** Shell: `dashboard.read`. Wallet KPIs / geo: often `platform.read`. Wallet adjust: **Super Admin**.

**Key APIs:**

- `GET /api/admin/platform-overview`  
- `GET /api/admin/wallet/me` — `GET /api/admin/wallet/me/transactions`  
- `GET /api/admin/wallet/:userId` / `transactions` — `wallet.read` or Super Admin  
- `POST /api/admin/wallet/adjust` — Super Admin  
- `GET /api/geo/store` — public; `GET/POST /api/geo/distance`  
- `GET /api/admin/store-geo` (`platform.read`) — `PUT /api/admin/store-geo` (Super Admin)

---

### 5.2 Admin management

**Purpose:** List staff, create admins, change roles (Super Admin), **commerce section overrides**, suspend, reset password, delete. **Immutable Super Admin** (see [§9](#9-immutable-super-admin-system-account)) is hidden from other users and cannot be demoted via API.

**Permissions:** List: `staff.read`. Mutations: **Super Admin**.

**Key APIs:** `GET/POST/PATCH/DELETE /api/admin/staff`, `POST .../reset-password`, `DELETE /api/admin/revoke-role`

---

### 5.3 Roles & permissions

**Purpose:** View role definitions, your effective permissions, **assign role by user ID** (Super Admin), permission glossary, and **Admin API RBAC matrix** (which endpoints require which permission).

**Permissions:** `roles.read`; assign role: **Super Admin**.

**Key APIs:** `GET /api/admin/roles`, `PUT /api/admin/assign-role`, `POST /api/admin/permissions/check`  
**Fallback static files:** `/permission-glossary.json`, `/admin-api-rbac.json`, `GET /api/catalog`

---

### 5.4 Compliance center

**Purpose:** Vendor KYC queue, approvals, suspensions, profile updates.

**Permissions:** List: `vendors.read`; approve/reject: `vendors.approve`; writes: `vendors.write` where applicable.

**Key APIs:** `GET /api/vendor/pending-verification`, `GET /api/admin/vendors`, `POST /api/vendor/approve`, `POST /api/vendor/reject`, `POST/PATCH /api/admin/vendors/...`

---

### 5.5 Commission settings

**Purpose:** Default commission and **per-category** rules.

**Permissions:** Read: `commission.read`; many writes: **Super Admin** routes.

**Key APIs:** `GET/POST /api/admin/commission`, category rules `GET/POST/DELETE .../category-rules`

---

### 5.6 Vendor management

**Purpose:** Register a vendor (KYC pending).

**Permissions:** `vendors.write` to register; `vendors.read` for lists.

---

### 5.7 Shop profile

**Purpose:** Store label, coordinates, contact, social links, logo, etc.

**Permissions:** `GET /api/admin/store-geo` with `platform.read`; `PUT` often **Super Admin** or **Operations** per server rules.

---

### 5.8 Product management

**Purpose:** Full product CRUD, images, pricing, discounts, measurements.

**Permissions:** `products.read`, `products.write`, `products.delete` (as applicable).

**Key APIs:** `GET/POST /api/products`, `GET/PUT/PATCH/DELETE /api/products/:id`

---

### 5.9 Stock management

**Purpose:** Inventory summary, low-stock emphasis, **adjust** stock.

**Permissions:** `inventory.read`, `inventory.adjust`

**Key APIs:** `GET /api/admin/inventory/summary?threshold=` — `PATCH /api/admin/inventory/products/:id/stock`  
Note: `—` (em dash) means **unlimited / not tracked**.

---

### 5.10 Catalog & payments

**Purpose:** Category **overlay** tree and **payment method** catalogue.

**Permissions:** `catalog.read` / `catalog.write`, `payments.read` / `payments.write`

**Key APIs:** `GET/POST/DELETE /api/admin/catalog-categories`, `GET/POST/PUT/DELETE /api/admin/payment-methods`, `POST .../reset-catalog`

---

### 5.11 Order management

**Purpose:** List/filter orders, **status** updates.

**Permissions:** `orders.read`, `orders.write`

**Key APIs:** `GET /api/orders`, `GET /api/orders/:orderNumber`, `PATCH /api/admin/orders/:orderNumber/status`

---

### 5.12 Financial management

**Purpose:** Revenue-oriented cards and order summaries (role-dependent).

**Permissions:** `platform.read`; wallet reads as in overview.

---

### 5.13 Tax settings

**Purpose:** Tax/VAT behaviour for storefront preview.

**Permissions:** Read: `platform.read`; update: **Super Admin** (typical).

**Key APIs:** `GET/PUT /api/admin/tax-settings` — public preview: `GET /api/public/tax/config`, `POST /api/public/tax/preview`

---

### 5.14 Notifications

**Purpose:** Admin notification settings and customer announcements.

**Permissions:** `platform.read`; announcements/settings: **Super Admin** (typical).

---

### 5.15 Communications (Deskia)

**Purpose:** Deskia telephony/SMS and related admin tools (when enabled).

**Permissions:** `platform.read` or `commerce.communications` for nav; handlers under `lib/deskia/`.

---

### 5.16 Security center

**Purpose:** Login events, active sessions, revoke.

**Permissions:** `security.read`; revoke session: **Super Admin** routes.

**Key APIs:** `GET /api/admin/security/login-events`, `GET /api/admin/security/sessions`, `DELETE /api/admin/security/sessions/:id`

---

### 5.17 Audit trail

**Purpose:** Immutable audit log with filters and export.

**Permissions:** `audit.read`, `audit.export`

**Key APIs:** `GET /api/admin/audit-log`, `GET /api/admin/audit-log/export?format=json|ndjson`

---

### 5.18 Blockchain

**Purpose:** Client-side ledger / blockchain diagnostics UI.

**Visibility:** Super Admin only (sidebar).

---

### 5.19 Account management

**Purpose:** Extended account/security tooling (e.g. multisig, mobile payments browser when present).

**Visibility:** Super Admin only (sidebar).

---

### 5.20 Commission & billing (section)

**Purpose:** Business commission tier and billing UX (often with `businessCommission.js`).

**Permissions:** Tied to orders/financial read patterns.

---

## 6. Roles and permissions

Canonical definitions live in **`lib/platformRoles.js`**. Effective permissions are merged with **`permissionOverrides`** (commerce keys) for staff.

| Role slug | Label | Permissions (summary) |
|-----------|--------|------------------------|
| `super_admin` | Super Admin | `*` (full access) |
| `finance_admin` | Finance Admin | Dashboard, platform, commission, orders read, financial, wallet read, audit, reports export |
| `operations_admin` | Operations Admin | Orders (`orders.*`), vendors read, products write, inventory adjust, security read, etc. |
| `product_admin` | Product Admin | Products/categories/catalog/payments/inventory/orders read |
| `customer_support_admin` | Customer Support Admin | Orders (`orders.*`), customers, product/inventory read |
| `compliance_admin` | Compliance Admin | Vendors (`vendors.*`), compliance (`compliance.*`), audit export |
| `inventory_admin` | Inventory Admin | Inventory adjust, products read, catalog read, orders read |

**Wildcards:** `*` = all; `orders.*` = any permission starting with `orders.`.

---

## 7. Commerce extra access (per staff)

Super Admins can grant **commerce section keys** (e.g. `commerce.products`) to a staff member via **Admin management → Sections** panel. That merges with their base role and can unlock **Commerce** sidebar entries without granting full super admin.

---

## 8. Business operators (restricted dashboard)

`operations_admin` users with a **business profile** may land on **Product management** and only see **allowed sections** (shop profile, stock, orders, financial per configuration). See `OPERATOR_ALLOWED_SECTIONS` in `public/admin.js`.

---

## 9. Immutable Super Admin (system account)

The deployment may define a **built-in** Super Admin email (default `safeutil@gmail.com`, override via `SHOPDESK_IMMUTABLE_SUPER_ADMIN_EMAIL`). That account:

- Cannot be demoted or deleted via normal admin APIs  
- Is **omitted** from the staff list for other users (still visible to yourself when logged in as that account)  
- **Super Admin** role in **create** / **assign** dropdowns may only be grantable by that immutable account when the UI is configured accordingly

---

## 10. API reference (quick)

For a longer endpoint-by-endpoint breakdown, see:

- `docs/shopdesk-admin-dashboard-api-reference.md` (in repo)  
- **Roles** tab in the dashboard: Admin API matrix + `GET /api/catalog`

Operational quick reference:

- **Wallet**: `GET /api/admin/wallet/me`, `GET /api/admin/wallet/me/transactions`  
  Staff lookup: `GET /api/admin/wallet/:userId/transactions` (requires `wallet.read` or Super Admin).
- **Wallet adjust**: `POST /api/admin/wallet/adjust` (Super Admin) with `userId`, `amountUSD`, optional `note`.
- **Geo**: `GET /api/geo/store`, `GET /api/geo/distance?lat=&lng=`, `POST /api/geo/distance` (`lat/lng` or `latitude/longitude`).
- **Store origin admin**: `GET /api/admin/store-geo` (`platform.read`), `PUT /api/admin/store-geo` (`shop_profile_editor`: Super Admin or Operations Admin).
- **Roles and matrix**: `GET /api/admin/roles` (permission glossary + API matrix), fallback static files:
  - `/permission-glossary.json`
  - `/admin-api-rbac.json`
- **Inventory**: `GET /api/admin/inventory/summary?threshold=`, `PATCH /api/admin/inventory/products/:id/stock` (`inventory.adjust`).
- **Catalog and payments**:
  - Categories overlay: `GET/POST/DELETE /api/admin/catalog-categories`
  - Payment methods: `GET/POST /api/admin/payment-methods`, `PUT/DELETE /api/admin/payment-methods/:id`, `POST /api/admin/payment-methods/reset-catalog`
- **Audit**: `GET /api/admin/audit-log` (`audit.read`), `GET /api/admin/audit-log/export` (`audit.export`, `format=json|ndjson`).

Regenerate static snapshots (optional):

```bash
npm run catalog:permission-glossary
npm run catalog:admin-api-rbac
```

---

## 11. Figures and screenshots

### 11.1 Illustrative figures (included)

These images are **diagram-style illustrations** to help orientation. Replace or supplement with **real screenshots** of your environment if you publish externally.

| Figure | File |
|--------|------|
| Dashboard KPI cards (illustrative) | `images/dashboard-overview-illustration.png` |
| Sidebar / navigation concept | `images/sidebar-structure-illustration.png` |
| Permissions / access concept | `images/permissions-concept-illustration.png` |

![Dashboard overview (illustrative)](images/dashboard-overview-illustration.png)

![Sidebar structure (illustrative)](images/sidebar-structure-illustration.png)

![Permissions concept (illustrative)](images/permissions-concept-illustration.png)

### 11.2 Capturing your own screenshots

1. Sign in to the dashboard.  
2. Use your OS screenshot tool (e.g. **Print Screen**, **Snipping Tool**, **macOS ⇧⌘4**).  
3. Save under `Documentation/images/` with clear names, e.g. `screenshot-overview.png`, `screenshot-staff.png`.  
4. Reference them in a custom appendix or internal wiki.

---

## 12. Related files in the repository

| Topic | Path |
|-------|------|
| Admin UI | `public/index.html`, `public/admin.js` |
| Roles | `lib/platformRoles.js` |
| API catalog (RBAC matrix source) | `lib/apiCatalog.js` |
| Users / staff | `lib/usersStore.js` |
| Immutable super admin | `lib/immutableSuperAdmin.js` |
| Legacy markdown (mirror) | `docs/shopdesk-admin-dashboard-documentation.md` |

---

*End of ShopDesk Admin Dashboard — Complete User Guide*