docs/growqr-frontend-v2-launch-gap-plan.md

GrowQR Frontend v2 Launch Gap Plan

This document only lists the differences between the current v2 frontend and the target sellable-workflow product. It is written so a frontend/UI agent can work independently from the backend agent.

Target assumption: backend owns workflow definitions, runs, score data, artifacts, agent availability, entitlements, and session URLs. The frontend renders that state in a playful, visual, low-reading experience.

---

1. Current frontend state observed

Relevant v2 files inspected:

• growqr-next-frontend/src/app/v2/page.tsx
• growqr-next-frontend/src/app/v2/workflows/page.tsx
• growqr-next-frontend/src/app/v2/chat/page.tsx
• growqr-next-frontend/src/app/v2/dashboard/page.tsx
• growqr-next-frontend/src/app/v2/agents/page.tsx
• growqr-next-frontend/src/app/v2/qx-score/page.tsx
• growqr-next-frontend/src/app/v2/pathways/page.tsx
• growqr-next-frontend/src/app/v2/marketplace/page.tsx
• growqr-next-frontend/src/app/v2/qvue/page.tsx
• growqr-next-frontend/src/components/home-v2/GrowChat.tsx
• growqr-next-frontend/src/components/home-v2/WorkflowDiscovery.tsx
• growqr-next-frontend/src/components/home-v2/WorkflowProgress.tsx
• growqr-next-frontend/src/components/home-v2/ChatInterface.tsx
• growqr-next-frontend/src/app/api/growqr/[...path]/route.ts

Already useful

• /v2/workflows/page.tsx is mostly backend-only and no longer shows example workflow progress.
• /v2/chat/page.tsx uses GrowChat, which calls the backend/actor path and avoids local fabricated final answers when the backend fails.
• /api/growqr/[...path]/route.ts exists as a Clerk-authenticated proxy to the backend.
• The visual direction is correct: agent avatars, large cards, simple labels, progress bars, and playful dashboard shell.

Additional UI reference checked

Source: docs/UI design Mockup Draft.pptx.

The mockup makes the frontend direction more explicit than the original gap plan did: GrowQR should feel like a visual career operating system, not a text dashboard. Keep the existing GrowQR branding/colors, but change the UI/UX toward:

• iPhone/App Library style grouping: Home should group many capabilities into simple visual folders/widgets instead of long menus or dense dashboards. Example groups from the mockup: Suggestions, Workflows, Pathways, Daily Rewards, Social, Productivity.
• Widget-first Home: Home is not a report page. It should show daily actions, active workflows/opportunities, Q Score, rewards, and small group summaries as tappable widgets that drill down.
• Low-reading UX: for Tier-2/Tier-3 India, students, freshers, and seekers, most information should be absorbed through icons, agent avatars, cards, progress maps, charts, badges, animations, and pictorial states. English copy should be short: one clear line + one CTA.
• TalkwithME as a primary mode: a video/avatar conversational surface should support voice and text, suggested prompt chips, history, and personalized guidance from the user journey. It should compare progress with peers/industry standards only when backend data is real.
• Workflows as agent squads: workflow cards should visually show the group of agents working together toward one outcome in a finite period of time. Active workflows need tabs, summary, action buttons, agent areas, artifact previews, charts, and feedback controls.
• Available vs Active mental model: Workflows, Opportunities/Agents, and other catalog surfaces should separate what can be bought/started from what is already running.
• Opportunities/Agents are one-off tasks: workflows are outcome bundles; opportunities/agents are cheaper single-purpose actions such as Resume, Social Branding, Interview, Role Play, Assessments, Jobs, Courses, Mentorships. Pathway is a one-time report/agent, while daily guidance belongs in workflows.
• Apple-inspired simplicity: complex product breadth should be hidden behind grouped widgets, folders, bottom/side navigation, and progressive disclosure. Maximum capability, minimum visible complexity.

---

2. Critical product gaps

Gap A — Workflow discovery is still frontend-owned

Current evidence:

• WorkflowDiscovery.tsx has a hardcoded WORKFLOWS object.
• The cards include IDs like job-preparation, interview-practice, resume-boost, career-switch, and job-search that do not all exist as backend workflow products.
• /v2/workflows/page.tsx only knows /workflows/job-application.

Target difference:

• Frontend should call GET /workflows and render backend-owned workflow products.
• Cards should represent sellable launch SKUs such as:
  • interview-to-offer
  • career-transition
  • salary-negotiation-war-room
  • promotion-readiness
  • personal-brand-opportunity-engine
  • optionally first-job-launchpad
• Frontend may own presentation, but not product definition.

Required change:

• Replace WORKFLOWS in WorkflowDiscovery.tsx with backend catalog data.
• Update /v2/workflows/page.tsx from one hardcoded job-application screen to:
  • catalog grid,
  • workflow detail drawer/page,
  • active run view,
  • module/artifact/status cards.

---

Gap B — Multiple v2 pages still show static/demo business data

Current evidence:

• dashboard/page.tsx hardcodes QX score 76, applications, interviews, skills, milestones, weekly activity, and agent stats.
• agents/page.tsx hardcodes agents, metrics, and “Active” state.
• qx-score/page.tsx hardcodes score 74 and visual areas.
• pathways/page.tsx hardcodes pathway programs and progress.
• marketplace/page.tsx hardcodes experts, ratings, availability, and counts.
• qvue/page.tsx hardcodes videos, views, ratings, and categories.
• DashboardSections.tsx, AgentExecution.tsx, and CareerCoPilot.tsx also contain static/demo surfaces.

Target difference:

• For launch, every visible claim should be one of:
  1. real backend data,
  2. a real backend catalog item,
  3. an empty/coming-soon locked state,
  4. a marketing card that clearly starts a real backend workflow.

Required change:

• Convert pages into real-data shells:
  • Dashboard: active workflow runs, latest artifacts, latest Q Score snapshot, next recommended workflow.
  • Agents: backend agent catalog + availability/status only.
  • QX Score: backend Q Score summary; if unavailable, show “Run Q Score” CTA, not fake score.
  • Pathways/QVue/Marketplace: either hide from launch nav or convert to locked/coming-soon backed by backend catalog.

---

Gap C — Chat has duplicated and conflicting implementations

Current evidence:

• /v2/chat/page.tsx uses GrowChat.
• HomeV2Client.tsx and marketplace/page.tsx can use ChatInterface.
• ChatInterface.tsx contains processResponse() with local fabricated suggestions and action cards.
• ChatInterface.tsx still references old growAgent actor naming.
• GrowChat.tsx is closer to the desired path, but still contains hardcoded suggestions, hardcoded agent metadata, and backend/session assumptions.

Target difference:

• One production chat surface for v2.
• Chat should only display:
  • assistant text from backend,
  • backend sessions,
  • backend workflow suggestions,
  • backend workflow run state,
  • backend artifacts.

Required change:

• Make GrowChat the only v2 chat component for launch.
• Stop using ChatInterface in v2 launch surfaces, or refactor it to delegate to GrowChat and delete local processResponse().
• Move suggestions from frontend constants to backend responses/catalog.

---

Gap D — Initial query behavior is still fragile

Current evidence:

• In GrowChat.tsx, welcome message is inserted on mount.
• The initialQuery effect only sends when messages.length === 0.
• Once the welcome message exists, initialQuery may not fire.

Target difference:

• Clicking workflow cards, agent cards, QVue cards, etc. must reliably start the real backend action.

Required change:

• Track consumed initialQuery with a ref instead of messages.length.
• Allow initial query to run after welcome message insertion.
• Clear or preserve welcome intentionally, but do not block the backend call.

---

Gap E — Workflow progress is hardcoded to one job-prep sequence

Current evidence:

• WorkflowProgress.tsx has a static six-step WORKFLOW_STEPS list.
• Chat infers workflow progress from local step numbers returned by backend chat fallback.

Target difference:

• Progress should come from the active WorkflowRun:
  • steps[],
  • currentStepId,
  • status,
  • agent/module state,
  • approval gates,
  • artifacts.

Required change:

• Replace static WORKFLOW_STEPS with workflow definition/run data.
• Support varied workflows: interview-to-offer, transition, negotiation, promotion, brand engine.

---

Gap F — API access is inconsistent

Current evidence:

• /v2/workflows/page.tsx calls NEXT_PUBLIC_GROWQR_BACKEND_URL directly.
• GrowChat.tsx sometimes calls backend URL directly and sometimes calls /api/growqr/....
• /api/growqr/[...path]/route.ts already exists and handles Clerk auth server-side.

Target difference:

• Browser frontend should prefer /api/growqr/* proxy for backend control-plane calls.
• Direct public backend URL should be a fallback only when explicitly needed.

Required change:

• Standardize v2 frontend calls on a small API client:
  • getWorkflowCatalog()
  • startWorkflow(workflowId, input)
  • getWorkflowRun(runId)
  • runWorkflowStep(runId, stepId)
  • sendChatMessage()
• Use /api/growqr/* by default.

---

Gap G — Home/navigation is still too dashboard-like for the mockup direction

Current evidence:

• /v2/page.tsx has an Apple-like folder idea already, but still mixes fake score widgets, dashboard report cards, long explanatory copy, and many routes.
• SidebarMinimal.tsx exposes product sections as a standard SaaS sidebar: Home, Chat, Agents, Workflows, Dashboard, QX Score, Q-Vue.
• The mockup instead frames the product around simple modes and grouped widgets: Home, Workflows, Opportunities, Analytics, Rewards, plus user identity/community modes such as Seeker, Mentor, Events, Community.

Target difference:

• Home should become a visual launchpad with grouped widgets/folders and one primary daily action.
• Navigation should reduce cognitive load. Users should not need to understand every product section before acting.
• The first screen should answer visually: “What should I do today?”, “Which workflow is active?”, “What reward/score changed?”, “Who is helping me?”

Required change:

• Replace dense dashboard sections with widget groups:
  • Today / Daily Actions,
  • Active Workflows,
  • Opportunities / Agents,
  • Q Score / Analytics,
  • Rewards / Badges.
• Use icon tiles and illustrated cards for catalog entries: Mock Interviews, Mock Tests, Jobs, Courses, Mentorships, Resume, Social Branding, Interview, Role Play, Assessments.
• Keep detailed analytics behind drill-down widgets; do not put dense text/charts on the first view.
• Add micro-interactions only where they clarify state: progress animation, agent typing/working state, reward unlock, workflow step completion.

---

3. Big frontend phases

Phase 1 — Tomorrow sellable-workflow launch UI

Goal: make the frontend safe to sell workflows without fake claims.

Must change:

1. Replace hardcoded workflow cards with backend GET /workflows catalog.
2. Replace hardcoded /workflows/job-application calls with /:workflowId routes once backend exposes them.
3. Make /v2/workflows the main launch surface:
   • visual mission cards,
   • available/active tabs,
   • start button,
   • active run panel,
   • agent squad cards,
   • module cards,
   • artifact preview tiles,
   • Q Score before/after slot.
4. Make /v2 Home a safe visual launchpad:
   • no fake score/report widgets,
   • Apple/App-Library-style grouped folders,
   • Today action widget,
   • Active workflow widget,
   • Opportunities/Agents widget,
   • Rewards/Badges locked or real.
5. Fix GrowChat initialQuery.
6. Remove/deactivate ChatInterface local fake responses from launch paths.
7. Hide or lock pages that still show fake metrics: marketplace, qvue, pathways, full dashboard sections.
8. Standardize API calls through /api/growqr.

Definition of done:

• A user can select a real workflow from backend catalog.
• Starting the workflow creates a backend run.
• The UI shows real run status/modules/artifacts only.
• If a service is unavailable, the UI shows blocked/unavailable from backend, not fake success.
• No visible fake Q Score, fake experts, fake videos, fake applications, or fake milestones on launch surfaces.

---

Phase 2 — Gamified low-reading workflow UX

Goal: make the product feel like a playful career mission system for students/freshers/Tier-2/Tier-3 users, using the mockup and iPhone/App Library as interaction references.

Must change:

1. Render backend workflow definitions as visual missions:
   • icon/mascot,
   • one-line promise,
   • estimated time,
   • reward/outcome,
   • agent squad avatars,
   • “Start Mission” CTA.
2. Render workflow runs as maps:
   • Start → Diagnose → Build → Practice → Score → Match/Finish.
3. Add Apple-style grouped widgets/folders:
   • Workflows,
   • Opportunities,
   • Pathways/Reports,
   • Analytics/Q Score,
   • Rewards,
   • Social/Productivity.
4. Add artifact cards:
   • resume version,
   • LinkedIn rewrite,
   • interview plan,
   • negotiation script,
   • promotion evidence packet,
   • brand posts.
5. Add score-delta and analytics cards that are visual before textual:
   • before/after Q Score ring,
   • dimensions improved,
   • mini graph/sparkline,
   • badges unlocked.
6. Add lightweight mobile-first states:
   • one primary CTA,
   • short copy,
   • visual status,
   • low text density,
   • voice/text TalkwithME entry point.
7. Add daily personalization feedback:
   • like/dislike/filter controls on workflow outputs,
   • “show me more like this” chips,
   • backend-backed preference state only.

Definition of done:

• Users understand each workflow in under 5 seconds without reading paragraphs.
• Each workflow has visible reward/output cards.
• Home feels like a visual app library/career OS, not a SaaS report dashboard.
• The UX sells outcomes, not internal services.

---

Phase 3 — Production polish and conversion

Goal: make frontend reliable for paid users and measurable launch.

Must change:

1. Add entitlement states:
   • free preview,
   • locked premium workflow,
   • purchased/active,
   • expired/completed.
2. Add durable loading/error states:
   • provisioning OpenCode,
   • service unavailable,
   • waiting for user input,
   • approval required,
   • retry available.
3. Add run history:
   • completed workflows,
   • generated artifacts,
   • score changes,
   • next recommended workflow.
4. Add analytics events:
   • catalog viewed,
   • workflow clicked,
   • workflow started,
   • module completed,
   • artifact opened,
   • payment intent.

Definition of done:

• The frontend is sales-ready, supportable, and measurable without inventing product state.

---

4. Frontend agent handoff checklist

Work in this order:

1. Create a frontend API client for /api/growqr.
2. Replace workflow discovery with backend catalog.
3. Generalize /v2/workflows to multiple workflow IDs.
4. Convert /v2 Home into a visual launchpad:
   • grouped widgets/folders,
   • one daily action,
   • Active vs Available surfaces,
   • no fake metrics.
5. Fix GrowChat initial query.
6. Remove ChatInterface from launch routes or delete its local response engine.
7. Hide/lock fake-data pages from nav until backend data exists.
8. Convert QX/Dashboard cards to backend-backed empty/real states.
9. Keep copy short and visual-first: icon/illustration + one line + CTA.

Do not work on microservice internals in this frontend pass.