Merchant App Slice — Onboarding → Dashboard → Profile → Settings (R1)

Status: P0–P3 built against the stubbed seams (2026-07-24). Nothing backend-wired yet; a design-fidelity re-alignment pass is queued — see the note under Phasing. The FE-first implementation roadmap for the merchant app's core account slice. Built as vertical slices on a frozen typed service seam (stubbed), then one backend-integration PR for the whole slice. Authoritative decisions live in the ADRs + tracker; this page is the working roadmap.

Strategy

Complete the frontend to a matured level for the four screens against a typed, stubbed service seam that mirrors the real Edge-Function / RPC contracts exactly, then integrate the backend in one sequenced PR — so integration is "swap the impl", not "rework the screens". Locked decisions: Lean first-run home (the legacy menu-centric dashboard is R2/Digital-Menu and does not apply to R1) and a minimal bottom-tab shell (Home / Create / Profile / Settings + More). Every screen: tokens + i18n (en/mr/hi), light+dark, parity (Android native / iOS native / Web PWA), README, exhaustive tests — no exceptions.

Setu Card note: the Setu Card (universal public identity for every user; supersedes "Service Card", retires "BioLink") is a separately-designed future feature. In this slice it appears only as a lightweight reference — the onboarding SetuCardPreview and a Dashboard summary tile/CTA to a placeholder. No card renderer/editor is built here. BioLink was never deployed → no legacy data/debt to carry.

Scope

In	Out (sequenced)
Bottom-tab app shell (audience-aware)	Real backend wiring → own PR (see Deltas)
Dashboard (lean first-run home)	Full Setu Card feature (separate brainstorm)
Profile (4 tabs)	R1 tool editors (QR/Website/Feedback) — launchers only
Settings (General/Security/Danger Zone)	Billing/Plans UI, Admin, Digital Menu (R2)
Stubbed service seam + Zod schemas	Landing/auth web (Stack 1), responsive desktop
Progressive profile-completion cards

Architecture & compliance deltas (required for non-negotiable alignment)

These are backed by a source review of the existing schema + EFs (2026-07-23). They land in the integration PR but shape the FE contracts now:

1. 🔴 Widen manage-profile write allow-list — buildProfileUpsertRow drops slug, onboarding_completed, gstin, description, business_hours, social_media_links. Onboarding cannot complete without this.
2. 🟠 Widen manage-settings allow-list — covers only default_currency/show_ads; add language (respect the en/mr/hi CHECK) + reminder prefs.
3. 🟠 Seed business_domains — table exists but Dev has 0 rows; add a seed + a get_business_domains RPC, retire the FE constant.
4. 🟡 Add get_* read RPCs (get_profile, get_dashboard_summary, get_business_domains) — projected columns, SECURITY DEFINER + search_path + REVOKE/GRANT, composite for the dashboard. Reads route TanStack Query → service → RPC (never manage-profile GET select *; the from() ban holds).
5. 🟡 Zod at EF boundaries — EFs hand-roll validation; resolve write-once validation across the npm↔Deno seam.
6. 🟡 Rate-limit the public validate-user-input (and any OTP endpoint).
7. 🟡 Entitlement/capability resolver (ADR-0006/0007) drives dashboard tool visibility — not hardcoded.
8. 🟡 Auth OTP decision — Supabase native signInWithOtp/verifyOtp vs a ZeptoMail EF (ADR-0008).
9. 🟡 Promotion — Dev needs the profile-pictures bucket + business_domains seed; promote to both projects.
10. 🟡 Single writer for default_currency (Settings), not both EFs.

Phasing

Phase	Deliverable	State
P0	Foundations: Setu Card rename ✅ · service seam + Zod schemas · QueryClient · bottom-tab shell · core UI primitives	✅ done (77dceb6)
P1	Settings (General/Security/Danger Zone) — proves auto-save + account actions	✅ done (41a8c07)
P2	Profile (4 tabs, avatar, hours, social; individual variant)	✅ built (stubbed)
P3	Dashboard (lean home; Setu Card = placeholder entry; entitlement-gated tools)	✅ built (stubbed)
P3.5	Design-fidelity re-alignment — re-pull the latest designs from the Claude Design project (MCP) and reconcile Settings / Profile / Home to match; codify design-as-source-of-truth in the workflow	✅ done (2026-07-24, MCP MobileConsole) — Profile + Settings reconciled; Home rebuilt as the full merchant console on stubbed data (approved scope change); nav switched to Home / Leads / Chats / More + Create FAB; Profile/Settings moved to pushed routes. Leads/Chats content + real metrics deferred (see note)
P4	Progressive profile-completion cards	pending
P5	Backend-integration PR (deltas 1–10)	pending

Each phase: exhaustive tests (every state + advanced paths) + parity + README/portal + tracker, before the next. The Setu Card brainstorm should slot before/alongside P3; P0–P2 are unblocked.

Dashboard design vs R1 scope [decision needed, surfaced 2026-07-24]. The authoritative MCP MobileConsole "Home" is a full returning-merchant console — revenue/orders/QR-scans/rating stat tiles, a sponsored card, quick actions, a live-orders list, and a Home / Leads / Chats / More bottom nav with a center Create FAB. That conflicts with two locked R1 decisions (the lean first-run home, and the Home / Create / Profile / Settings tab shell) and depends on backend data that does not exist in R1 (revenue, orders, ratings, leads, chats). It also touches billing/compliance (ADR-0002). We deliberately did not fabricate a metrics console before a decision. Resolved 2026-07-24 — option (b): build the full console UI against STUBBED metrics now, switching the shell to Home / Leads / Chats / More + a center Create FAB. Consequences accepted and tracked: (1) Home ships illustrative demo numbers until the analytics/orders backend (ADR-0010) lands — clearly commented in DashboardService; (2) Leads / Chats are placeholder screens (their feeds need the enquiries/messaging backend that doesn't exist in R1); (3) Profile/Settings are now pushed routes reached from the Home header and More, not bottom tabs; (4) the PLAN card and any "upgrade" path remain web-first, no in-app purchase (ADR-0002). Follow-ups (QRS-169, QRS-171): real get_dashboard_summary + analytics wiring; Leads/Chats feature builds; entitlement-gated quick actions; a Notifications feed. The lean-home components SetuCardSummary/ToolsGrid were retired; ProfileCompletionCard is retained for P4.

Design fidelity [process gap surfaced 2026-07-24]. A review of the built Settings/Profile/Home screens against the provided designs found visual drift. CLAUDE.md treats the design as the primary source of truth, to be replicated as closely as possible. New standing rule: every UI implementation begins by pulling the latest design for that screen from the Claude Design project via the MCP DesignSync//design-sync integration — never from a possibly-stale local copy. Local .dc.html handoff files under QR setu prototype-handoff/ are a cache only; treat the MCP project as authoritative. P3.5 reconciles the existing screens; the rule applies to all future UI.

Testing

Per primitive (every state), per screen (happy + advanced: validation, error boundaries, auto-save races, avatar failure, delete-confirm, hours edges), controller/flow, service stubs (incl. failure), schema boundary rejections, i18n completeness + locale switch, light/dark, a11y, reduced-motion, and a "never calls supabase.from()" compliance test (activates at integration). Coverage 70% lines / 80% functions or better.

Open questions (flagged, resolve before the relevant phase)

Generic-mode dashboard depth for individuals · can users switch audience (business↔individual) later · update-password screen requirements · entitlement-matrix source (ADR-0007) · OTP provider · country_code handling (no column — keep selector display-only).