18 KiB
18 KiB
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, existingfrontend/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
- Dashboard rescue — replace “بهزودی” cards with entitlement-aware app launcher (reuse
PLATFORM_APPS+TenantSwitcher+ links already in bundles). - Onboarding commercial bridge — after tenant create: explicit bundle confirm; call existing subscription/trial APIs if available; else clear “manual activation” state + admin path.
- Domain policy UX — subdomain default; gate custom domain until
subscription_status=active(or document temporary override). - Feature locking + upgrade prompts — wire
features/checkinto hub entry and key actions. - Needs assessment + type catalog alignment — expand intents toward business-type catalog; collect size/goals flags (still FE/rules-local until evaluator exists).
- Billing pages — tenant subscribe/trial/upgrade using existing Core plan/subscription endpoints (reuse admin patterns).
- Setup checklist — guided links into Experience/Payment/… hubs.
- Shell polish — header nav, dark mode toggle, skeletons, empty states, notifications shell.
- 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_LINKSwith linked tiles fromPLATFORM_APPSfiltered 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 viaapi.subscriptionsif 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_INTENTStowardbusiness-type-catalogcodes (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+.