TorbatYar/docs/frontend-ux-audit-report.md

# Frontend UX Audit Report — TorbatYar Commercial Usability

> **Audit only.** No code changes. No new products. No roadmap phases.  
> Date: 2026-07-28  
> Sources: `docs/project-status.yaml`, Experience FE snapshot, Commercial Foundation contracts, existing `frontend/app/**` pages  
> Note: `docs/service-snapshots/frontend*.yaml` — **not found** (gap)

**Verdict:** The frontend is **not yet commercially usable end-to-end**. Wave-1 onboarding UX exists, but the customer journey **breaks after workspace creation** — no trial/subscription/license activation UI, dashboard is a stub launcher, and commercial rules (trial limits, feature locking, domain gating) are largely absent from tenant-facing UI.

---

## 1. Frontend UX Audit Report

| Area | Finding | Status |
| --- | --- | --- |
| **Landing / Home** | Platform host → Business Onboarding home (`frontend/app/page.tsx`): intent grid + recommended bundle + CTA. Tenant host → `TenantSitePage` + `AppStoreGrid` (app launcher). | PARTIAL |
| **Home** | Commercially oriented copy; 8 intents only (not full 17 business types). Pricing hints are static FE strings. | PARTIAL |
| **Dashboard** | `/dashboard` shows tenant name, plan/subscription fields (often empty), domains list, and **4 “به‌زودی” cards with no links**. No product launcher, no setup checklist, no upgrade CTA. | SCAFFOLD |
| **Onboarding** | `/onboarding` AuthGuard wizard: business → branding → domain → review → complete. Creates tenant via Core API; shows FE bundle preview; does **not** activate entitlements/subscription/trial. | PARTIAL |
| **Signup** | `/register` → `AuthPanel` signup mode. | READY (auth) |
| **Login** | `/login` → `AuthPanel` / SSO. Header “ورود” uses `useAuth().login()`. | READY (auth) |
| **Workspace selection** | `TenantSwitcher` on dashboard only when `memberships.length > 1`. No dedicated workspace picker page. | PARTIAL |
| **Tenant creation** | Onboarding `createTenant` + admin `/admin/tenants/new`. Tenant-facing path exists. | PARTIAL |
| **Business selection** | Home + onboarding select from `BUSINESS_INTENTS` (8). Canonical catalog has 17 types. | PARTIAL |
| **Service catalog** | `PLATFORM_APPS` + `AppStoreGrid` on tenant site only (not platform home). Mixed available/coming_soon. | PARTIAL |
| **Bundle selection** | Preview only from FE mirror of bundles; no multi-bundle compare, no API select event. | SCAFFOLD |
| **Subscription flow** | Tenant UI: **missing**. Admin tenant detail can create/view subscription via Core API. | SCAFFOLD / missing tenant |
| **Trial flow** | API types include `trialing` / `trial_ends_at`; **no tenant trial UX**. | SCAFFOLD |
| **Profile completion** | `/dashboard/settings` → `AccountSettings` (account). Vertical-specific profiles (beauty/healthcare) exist separately. No commercial profile (industry/country/currency) in platform onboarding. | PARTIAL |
| **Empty states** | DS `EmptyState` exists; platform dashboard does not use rich empty/setup states. Experience CRUD uses list empty patterns. | PARTIAL |
| **Navigation** | Global `SiteHeader` only (logo, login/dashboard/admin). **No app sidebar** on platform dashboard. Service portals have their own nav (Experience, Payment, etc.). | PARTIAL |
| **Sidebar** | Platform: none. Per-module portals: yes (varies). | PARTIAL |
| **Responsive** | Home/onboarding/dashboard use responsive grids; RTL root layout. | PARTIAL / OK for MVP |
| **Accessibility** | Experience DS claims WCAG smoke; platform home uses buttons/labels but no systematic a11y audit evidence in this pass. | PARTIAL |
| **Dark mode** | `ColorModeProvider` present; **no global toggle in SiteHeader**. Experience design-system supports light/dark. | PARTIAL |
| **Loading states** | Text “در حال بارگذاری…” common; Button `loading` props; Experience `loading.tsx` route shells. Few skeletons on platform pages. | PARTIAL |
| **Error states** | Inline red banners; Experience `error.tsx` + DS ErrorState; API 422 formatting improved for Experience. | PARTIAL |
| **Skeletons** | DS `Skeleton` exists; platform dashboard/onboarding rarely use it. | PARTIAL |
| **Search** | DS toolbar search placeholder; **no global product/workspace search**. | SCAFFOLD / missing |
| **Notifications** | No platform notification center. Loyalty has notifications page (module-specific). | SCAFFOLD / missing |

---

## 2. Scaffold Inventory

Legend: **READY** · **PARTIAL** · **SCAFFOLD** · **BROKEN**

### Platform commercial surface

| Page / surface | Mark | Evidence |
| --- | --- | --- |
| `/` Business Onboarding Home | PARTIAL | Intent + bundle preview work; no activation backend; incomplete type set |
| `/` Tenant host site | PARTIAL | App launcher grid; not commercial OS |
| `/login`, `/register` | READY | AuthPanel |
| `/onboarding` | PARTIAL | Real tenant create/branding/domain/complete APIs; no trial/bundle/license activation |
| `/dashboard` | SCAFFOLD | Quick links all “به‌زودی”, no hrefs; plan/subscription display-only |
| `/dashboard/settings` | PARTIAL | Account settings; not commercial billing |
| `SiteHeader` | PARTIAL | Minimal; no catalog/apps/billing |
| Bundle catalog FE (`business-bundles.ts`) | SCAFFOLD as SoT | Documented as temporary mirror; not codegen |

### Admin (platform operator — not customer journey)

| Page | Mark | Evidence |
| --- | --- | --- |
| `/admin/tenants`, `/admin/tenants/[id]` | PARTIAL | Subscription create/get exists for admins |
| `/admin/tenants/new` | PARTIAL | Admin tenant create |

### Product hubs (application launchers / ops)

| Area | Mark | Notes |
| --- | --- | --- |
| `/experience/hub` + studio routes | PARTIAL → many READY CRUD | FE-11.5 list CRUD hardened; hub is thin launcher; FE-11.6 registry UI absent (expected) |
| `/payment/hub` + admin routes | PARTIAL / READY for MVP ops | Payment operator UI, not customer checkout/subscription storefront |
| `/hospitality/hub`, `/delivery/*`, `/crm/hub`, `/loyalty/*`, `/communication`, `/accounting`, `/sports-center/*`, `/healthcare/*`, `/beauty/*` | PARTIAL | Vertical depth varies; not wired to commercial activation pipeline |
| Coming-soon apps in `PLATFORM_APPS` | SCAFFOLD | ecommerce, restaurant duplicate, etc. |

### Scaffold patterns still present

- Dashboard quick-link cards: **buttons/cards without action**
- Bundle “activation” copy without entitlement API calls
- Static monthly hints in FE catalog
- No fake charts found on platform dashboard (good); Payment KPIs claimed live in prior audit
- Experience secondary forms: still “field polish” open per snapshot
- Global search / notifications: missing shells

---

## 3. Commercial Journey Report

Target journey vs actual:

| Step | Expected | Actual | Break? |
| --- | --- | --- | --- |
| Visitor | Public landing | Platform home OK | — |
| Landing | Business-oriented | Home onboarding OK | — |
| Business Type Selection | Full catalog | 8 intents only | Soft break |
| Needs Assessment | Rule engine inputs (size, needs flags…) | Intent click only | **Break** |
| Recommended Products | Product Registry | Service links from FE bundle | Soft break |
| Recommended Bundle | Catalog SoT | FE `primaryBundle` | Soft break |
| Create Workspace | Tenant + workspace | Onboarding createTenant | — |
| Trial Activation | Subscription trialing + license | **Missing tenant UI + no auto-activation** | **HARD BREAK** |
| Workspace Dashboard | Operating system / setup | Stub “به‌زودی” cards | **HARD BREAK** |
| Product Setup | Guided entitle → hub | Manual link to first required service href | Soft break |
| Upgrade | Upgrade prompts | Missing | **HARD BREAK** |
| Subscription | Tenant subscribe/pay | Admin-only subscription tools | **HARD BREAK** |
| Payment | Customer billing / Torbat Pay activation | Payment hub is PSP ops, not journey step | **HARD BREAK** |
| Domain | Subdomain before pay; custom after active sub | Onboarding allows **optional custom domain anytime**; no subscription gate | **HARD BREAK** (rules) |
| Production | Ready state | No production checklist / domain verify UX on dashboard | **Break** |

**Primary break point:** after `onboarding.complete` → first service hub. No trial, license, entitlement grant, or commercial dashboard generation.

---

## 4. Missing Pages

| Missing page (reuse/extend preferred) | Purpose |
| --- | --- |
| `/pricing` or `/plans` | Public / post-login plan compare |
| `/subscribe` or `/billing` | Tenant subscription + trial start |
| `/licenses` or billing entitlements view | Show licensed products/capabilities |
| `/upgrade` | Upgrade prompts from locked features |
| `/apps` or dashboard apps panel | Entitled service launcher (reuse `PLATFORM_APPS` + entitlements) |
| `/onboarding/needs` | Size, employees, goals, flags (recommendation inputs) |
| `/onboarding/bundle` | Explicit bundle confirm (not only preview) |
| `/domains` (tenant) | Subdomain vs custom domain policy UI |
| `/setup` checklist | Post-trial product setup wizard |
| Global notifications page/center | Cross-product alerts |
| Global search | Workspace/apps/resources |

---

## 5. Missing Components

| Component | Need |
| --- | --- |
| `EntitlementGate` / `FeatureLock` | Hide/lock UI by feature check API |
| `UpgradePrompt` modal/banner | Upsell when locked |
| `TrialBanner` | Trial countdown / limits |
| `BundlePicker` | Multi-bundle select from SoT |
| `NeedsAssessmentForm` | RecommendationRequest fields |
| `PlanCard` / `PricingTable` | Pricing catalog display |
| `SubscriptionStatusCard` | Active/trialing/past_due actions |
| `AppsLauncherGrid` (entitlement-aware) | Replace dead dashboard cards |
| `SetupChecklist` | Activation → production steps |
| `DomainPolicyGuard` | Block custom domain until subscription active |
| Header `ColorModeToggle` | Expose existing provider |
| Platform `Sidebar` / command nav | Business OS navigation |
| Notification bell | Alerts |

---

## 6. Broken Navigation

| Issue | Detail |
| --- | --- |
| Dashboard dead ends | Four module cards have **no `href` / onClick** |
| Home → product hubs | Deep-links to hubs without entitlement check — may open empty/unauthorized modules |
| No path Home → Pricing → Subscribe | Missing routes |
| Header lacks Apps / Billing / Setup | Only Dashboard / Account / Admin |
| Onboarding complete → arbitrary first service | Skips dashboard OS; user may never see workspace summary |
| Tenant vs platform dual home | AppStoreGrid only on tenant host — platform users lose catalog after login unless they hunt URLs |
| Bundle service “باز کردن” before workspace | Can navigate to hubs pre-tenant |

---

## 7. API Gaps (frontend consumption)

| Capability | Backend/API note | FE usage |
| --- | --- | --- |
| Onboarding create/branding/domain/complete | Core APIs exist | Used |
| Tenant context (plan_name, subscription_status) | Returned | Display only; often empty |
| Subscriptions CRUD | `api.subscriptions.*` | **Admin only** |
| Plans list | `api.plans.list` | **Admin only** |
| Feature check | `features/check` | **Not used in tenant UI gates** |
| Commercial Foundation registries | Docs only — **no APIs** | N/A (expected) |
| Bundle select / license request / activation events | Contracts only | **No FE** |
| Recommendation evaluator | Contracts only | FE static map |
| Payment customer checkout for subscription | Not same as Payment hub MVP | Missing journey |
| Entitlement-aware apps list | Partial Core features | Missing |

---

## 8. Recommended execution order

1. **Dashboard rescue** — replace “به‌زودی” cards with entitlement-aware app launcher (reuse `PLATFORM_APPS` + `TenantSwitcher` + links already in bundles).
2. **Onboarding commercial bridge** — after tenant create: explicit bundle confirm; call existing subscription/trial APIs if available; else clear “manual activation” state + admin path.
3. **Domain policy UX** — subdomain default; gate custom domain until `subscription_status=active` (or document temporary override).
4. **Feature locking + upgrade prompts** — wire `features/check` into hub entry and key actions.
5. **Needs assessment + type catalog alignment** — expand intents toward business-type catalog; collect size/goals flags (still FE/rules-local until evaluator exists).
6. **Billing pages** — tenant subscribe/trial/upgrade using existing Core plan/subscription endpoints (reuse admin patterns).
7. **Setup checklist** — guided links into Experience/Payment/… hubs.
8. **Shell polish** — header nav, dark mode toggle, skeletons, empty states, notifications shell.
9. **Codegen bundles from YAML** — when commercial FE phase registered (out of scope until authorized).

---

## 9. Priority list

### Critical

- Dashboard dead links / non-OS behavior
- Missing trial/subscription activation after onboarding (journey hard break)
- No feature/capability locking on product entry
- Custom domain allowed without active subscription (policy break)

### High

- Entitlement-aware apps launcher on dashboard
- Tenant billing/subscribe/trial UI (reuse Core APIs used by admin)
- Upgrade prompts
- Bundle confirm step + post-complete routing to dashboard (not random hub)
- Align business types with catalog (at least cafe split, missing types)

### Medium

- Needs assessment fields (size, employees, goals, flags)
- Domain management page
- Setup checklist / production readiness
- Header navigation (Apps, Billing, Setup)
- Loading skeletons + richer empty states on platform pages
- Dark mode toggle exposure

### Low

- Global search
- Notifications center
- a11y deep pass
- FE bundle codegen from commercial YAML
- Full 17-type marketing polish

---

## 10. Phased implementation plan (reuse existing pages)

> Do **not** replace Home / Onboarding / Dashboard. Extend them.

### Phase A — Dashboard as launcher (reuse `/dashboard`)

- Keep tenant summary card.
- Replace `QUICK_LINKS` with linked tiles from `PLATFORM_APPS` filtered by membership/features when available; fallback: bundle-recommended services for current tenant type.
- Add CTA: “تکمیل راه‌اندازی” → checklist section on same page.
- Add link to settings + billing placeholder route.

### Phase B — Onboarding bridge (reuse `/onboarding`)

- Keep 4 steps; insert or extend **review** with: confirmed bundle, trial checkbox, subdomain display.
- On complete: prefer `router.push("/dashboard")` then deep-links; optionally start trial via `api.subscriptions` if plan IDs known.
- Persist `businessType` / intent on tenant metadata if API allows; else localStorage bridge for dashboard recommendations.

### Phase C — Commercial rules (reuse dashboard + onboarding domain step)

- Domain step: emphasize subdomain; custom domain disabled with upgrade message unless subscription active.
- Wrap hub entry links with feature check (shared guard component).
- Trial banner on dashboard when `trialing`.

### Phase D — Billing UI (new routes, reuse admin subscription forms)

- Extract admin subscription form patterns into tenant `/billing`.
- Plans from `api.plans.list`; subscribe/trial; show license/plan on dashboard cards (already have fields).

### Phase E — Needs + catalog alignment (reuse `/` assess section + onboarding business step)

- Expand `BUSINESS_INTENTS` toward `business-type-catalog` codes (map IDs carefully).
- Add optional needs fields (employees, branches, website/delivery/crm flags) feeding local recommendation sort — still no new backend engine.

### Phase F — Shell (reuse `SiteHeader`, `ColorModeProvider`, DS)

- Header: Dashboard, Apps (`/dashboard#apps`), Billing, Account, theme toggle.
- Apply Skeleton/EmptyState on platform pages consistently.

**Explicitly deferred:** new products, Marketplace, QR, Booking, Payment 14.6+, Experience FE-11.6, commercial registry engines.

---

## Dashboard Audit (Step 4 summary)

**Current behavior:** weak **application launcher stub** (cards without links) + tenant metadata panel.  
**Not** a business operating system (no setup, billing, entitlements, notifications, cross-product tasks, domain ops, upgrade).

**Missing OS capabilities:** apps rail, setup checklist, billing/trial, entitlement map, domain manager, team access (card says soon), branding manager (soon), search, notifications, upgrade, production readiness.

---

## Onboarding Audit (Step 5 summary)

| Field | Supported? |
| --- | --- |
| Business Type | Partial (8 intents) |
| Business Size | No |
| Industry | No (type only) |
| Country | No |
| Language | No (Experience workspace has language later) |
| Currency | No (Experience workspace has currency later) |
| Timezone | No (Experience workspace later) |
| Brand colors | Yes |
| Logo | Yes (URL only) |
| Domain preference | Partial (optional custom; no subdomain UX clarity) |
| Employees | No |
| Goals | No |
| Recommended services | Preview only |
| Bundle recommendation | Preview only |
| Trial creation | No |
| Workspace creation | Yes (tenant as workspace) |

---

## Commercial Rules Validation (Step 6 summary)

| Rule | UI support |
| --- | --- |
| Trial | No tenant UX |
| Demo period | No |
| Trial limits | No |
| Subscription | Admin only |
| License | No tenant UX |
| Bundle | Preview only |
| Entitlements | Not gated in UI |
| Recommended services | Yes (static) |
| Subdomain before payment | Not enforced / unclear UX |
| Custom domain only after active subscription | **Not enforced** |
| Feature locking | No |
| Capability locking | No |
| Upgrade prompts | No |

---

## STOP

Audit complete. **No implementation performed.** Await explicit authorization before Phase A+.