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+.