# ShopDesk Admin Dashboard Documentation

> **Updated guide (recommended):** see the **`Documentation/`** folder — browser hub at **`/Documentation/`** with figures and the consolidated **`SHOPDESK_ADMIN_DASHBOARD_GUIDE.md`**. This file remains a concise mirror.

This document describes the full ShopDesk admin dashboard: sections, permissions, and major API endpoints.

## Access and Authentication

- Login endpoint: `POST /api/auth/login`
- Token type: Bearer JWT
- Admin dashboard requires `role=admin`
- Some actions require Super Admin (`adminRole=super_admin`) or specific permission keys

## Dashboard Navigation Map

The dashboard is organized by sidebar groups and sections:

1. Dashboard overview
2. Admin management
3. Roles and permissions
4. Compliance center
5. Commission settings
6. Vendor management
7. Shop profile
8. Product management
9. Stock management
10. Catalog and payments
11. Order management
12. Financial management
13. Tax settings
14. Notifications
15. Communications (Deskia)
16. Security center
17. Audit trail
18. Blockchain
19. Account management
20. Commission and billing (section available in dashboard body)

## 1) Dashboard Overview

Purpose:
- Cross-cutting KPIs (orders, revenue, customers, stock, commission, admins)
- Wallet snapshot/activity
- Geo distance from configured store coordinates

Permissions:
- View section shell: `dashboard.read`
- KPI cards and store-geo admin endpoints: `platform.read`

APIs:
- `GET /api/admin/platform-overview`
- `GET /api/admin/wallet/me`
- `GET /api/admin/wallet/me/transactions`
- `GET /api/admin/wallet/:userId/transactions` (for other staff: `wallet.read` or Super Admin)
- `POST /api/admin/wallet/adjust` (Super Admin)
- `GET /api/geo/store`
- `GET /api/geo/distance?lat=&lng=`
- `POST /api/geo/distance` with JSON `lat` and `lng` (or `latitude` and `longitude`)
- `GET /api/admin/store-geo` (`platform.read`)
- `PUT /api/admin/store-geo` (Super Admin)

## 2) Admin Management

Purpose:
- Create/list/update/suspend/delete staff admins
- Reset staff passwords
- Toggle staff 2FA flag

Permissions:
- Read list: `staff.read`
- Create/update/delete/reset/suspend: Super Admin

Primary APIs:
- `GET /api/admin/staff`
- `POST /api/admin/staff`
- `PATCH /api/admin/staff/:id`
- `DELETE /api/admin/staff/:id`
- `POST /api/admin/staff/:id/reset-password`
- `DELETE /api/admin/revoke-role`

## 3) Roles and Permissions

Purpose:
- Display role definitions and permission patterns
- Check permission access for current admin
- Assign role by user ID (Super Admin)
- Show permission glossary
- Show admin API RBAC matrix

Permissions:
- Section access: `roles.read`
- Assign role: Super Admin

Primary APIs:
- `GET /api/admin/roles`
- `POST /api/admin/permissions/check`
- `PUT /api/admin/assign-role`

Fallback data sources in UI:
- Permission glossary fallback: `/permission-glossary.json`
- Admin API RBAC matrix fallback: `/admin-api-rbac.json`
- Secondary matrix source: `GET /api/catalog`

## 4) Compliance Center

Purpose:
- Work KYC queue and vendor compliance status
- Approve/reject/suspend vendors

Permissions:
- Queue/list: `vendors.read`
- Approve/reject/suspend: `vendors.approve`
- Profile edits/TIN/tax flag updates: `vendors.write`

Primary APIs:
- `GET /api/vendor/pending-verification`
- `GET /api/admin/vendors`
- `POST /api/vendor/approve`
- `POST /api/vendor/reject`
- `POST /api/admin/vendors/:id/suspend`
- `PATCH /api/admin/vendors/:id`

## 5) Commission Settings

Purpose:
- Configure default commission
- Configure per-category overrides

Permissions:
- Read: `commission.read`
- Writes: Super Admin routes

Primary APIs:
- `GET /api/admin/commission`
- `POST /api/admin/commission`
- `GET /api/admin/commission/category-rules`
- `POST /api/admin/commission/category-rules`
- `DELETE /api/admin/commission/category-rules/:category`

## 6) Vendor Management

Purpose:
- Register vendor records (KYC starts pending)

Permissions:
- Register: `vendors.write`
- KYC queue view: `vendors.read`
- Approve/reject/suspend: `vendors.approve`

Primary APIs:
- `POST /api/admin/vendors`
- `GET /api/vendor/pending-verification`
- `POST /api/vendor/approve`
- `POST /api/vendor/reject`
- `POST /api/admin/vendors/:id/suspend`

## 7) Shop Profile

Purpose:
- Manage seller identity and store pickup/location profile data

Permissions:
- Edit: Super Admin
- Read data endpoint in admin: `platform.read`

Primary APIs:
- `GET /api/geo/store` (public read)
- `GET /api/admin/store-geo`
- `PUT /api/admin/store-geo`

## 8) Product Management

Purpose:
- CRUD product catalog in admin

Permissions:
- Read: `products.read`
- Create/update: `products.write`
- Delete: `products.delete`

Primary APIs:
- `GET /api/products`
- `POST /api/products`
- `GET /api/products/:id`
- `PUT /api/products/:id`
- `PATCH /api/products/:id`
- `DELETE /api/products/:id`

## 9) Stock Management

Purpose:
- Inventory KPIs and low-stock list
- Update tracked stock values

Permissions:
- Read summary: `inventory.read`
- Adjust stock: `inventory.adjust`

Primary APIs:
- `GET /api/admin/inventory/summary?threshold=`
- `PATCH /api/admin/inventory/products/:id/stock`

Notes:
- Numeric stock is tracked
- `stock: "—"` means unlimited/not tracked

## 10) Catalog and Payments

Purpose:
- Manage category overlays and payment method catalog

Permissions:
- Category read/write: `catalog.read`, `catalog.write`
- Payment read/write: `payments.read`, `payments.write`

Primary APIs:
- `GET /api/admin/catalog-categories`
- `POST /api/admin/catalog-categories`
- `DELETE /api/admin/catalog-categories`
- `GET /api/admin/payment-methods`
- `POST /api/admin/payment-methods`
- `PUT /api/admin/payment-methods/:id`
- `DELETE /api/admin/payment-methods/:id`
- `POST /api/admin/payment-methods/reset-catalog`

## 11) Order Management

Purpose:
- View orders and update fulfillment status

Permissions:
- Read: `orders.read`
- Update status: `orders.write`

Primary APIs:
- `GET /api/orders`
- `GET /api/orders/:orderNumber`
- `PATCH /api/admin/orders/:orderNumber/status`
- `GET /api/admin/customer-checkout-payments`

## 12) Financial Management

Purpose:
- Financial snapshots and wallet-oriented admin views

Permissions:
- Platform-level cards and settings: `platform.read`
- Wallet reads for other staff: `wallet.read`
- Wallet adjustments: Super Admin

Primary APIs:
- `GET /api/admin/platform-overview`
- `GET /api/admin/wallet/me`
- `GET /api/admin/wallet/:userId`
- `GET /api/admin/wallet/me/transactions`
- `GET /api/admin/wallet/:userId/transactions`
- `POST /api/admin/wallet/adjust`

## 13) Tax Settings

Purpose:
- Configure tax/VAT settings used by storefront tax preview

Permissions:
- Read: `platform.read`
- Update: Super Admin

Primary APIs:
- `GET /api/admin/tax-settings`
- `PUT /api/admin/tax-settings`
- `GET /api/public/tax/config`
- `POST /api/public/tax/preview`

## 14) Notifications

Purpose:
- Configure notification toggles
- Create customer announcements

Permissions:
- Read: `platform.read`
- Update/announce: Super Admin

Primary APIs:
- `GET /api/admin/notification-settings`
- `PUT /api/admin/notification-settings`
- `POST /api/admin/notifications/announce`
- `GET /api/public/notification-context`

## 15) Communications (Deskia)

Purpose:
- Internal communications workflow via Deskia module endpoints

Permissions:
- Uses authenticated admin context and section-level visibility rules

Implementation:
- Server imports Deskia handlers from `lib/deskia/*`
- UI section is rendered in admin dashboard under Communications

## 16) Security Center

Purpose:
- Review login events and active sessions
- Revoke sessions

Permissions:
- Read: `security.read`
- Revoke other session: Super Admin route

Primary APIs:
- `GET /api/admin/security/login-events`
- `GET /api/admin/security/sessions`
- `DELETE /api/admin/security/sessions/:id`

## 17) Audit Trail

Purpose:
- View and export audit logs

Permissions:
- Read: `audit.read`
- Export: `audit.export`

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

Related:
- Public action catalog: `GET /api/meta/audit-action-catalog`

## 18) Blockchain

Purpose:
- Display chain/security state and blockchain-related admin diagnostics

Implementation:
- UI scripts: `public/shopdesk-blockchain-core.js`, `public/shopdesk-admin-security-ui.js`
- Integrated in admin runtime via `public/admin.js`

## 19) Account Management

Purpose:
- Admin account/session related tools exposed in dashboard

Permissions:
- Section visibility follows role and permission rules in `public/admin.js`

## 20) Commission and Billing

Purpose:
- Business tier and commission billing experience shown in dashboard body

Implementation:
- UI logic in `public/businessCommission.js` and `public/admin.js`

## Role and Permission Source of Truth

- Role definitions and permission patterns: `lib/platformRoles.js`
- API catalog + RBAC matrix source: `lib/apiCatalog.js`

Regeneration commands:
- Permission glossary static snapshot:
  - `npm run catalog:permission-glossary`
- Admin API RBAC static snapshot:
  - `npm run catalog:admin-api-rbac`

## Where this documentation is loaded

- This file is served at:
  - `/docs/shopdesk-admin-dashboard-documentation.md`
- It is linked in the admin dashboard top bar as:
  - `Dashboard docs`