docs/delivery-map.md

GrowQR Delivery Map — June 3, 2026

Goal: Ship a testable GrowQR dashboard + backend to AVPS in one session. Team should be able to log in, start a workflow, chat with the agent, open service pages, and see analytics.

---

1. Repo Landscape

Repo	Role	Status
growqr-backend	Production backend (Hono + Rivet + Drizzle + AI SDK)	Active development
growqr-dashboard	Target dashboard UI (Next.js 14 + Clerk + Tailwind)	Mock data — needs API integration
growqr-next-frontend	Reference only — has v2/v3 UI we can borrow from	Abandoned as primary frontend
growqr-app/frontend	Reference only — production interview/roleplay/resume components	Still in production separately

Rule: All new UI goes into growqr-dashboard. Other repos are read-only reference.

---

2. Backend Current State

What already works

• Clerk-authenticated Hono routes
• Rivet actor registry with per-user userActor, per-run workflowRunActor, and service actors (interviewServiceActor, roleplayServiceActor, resumeServiceActor)
• Workflow registry with 5 sellable workflow definitions
• Database tables: workflowRuns, workflowRunModules, workflowEvents, workflowArtifacts, workflowApprovals, qscoreSnapshots
• Service adapters for resume, interview, roleplay, Q Score
• Chat route with LLM fallback + tool dispatch (start interview, start roleplay, analyze resume, compute qscore)
• Gitea per-user repo model
• OpenCode container lifecycle
• Prompt/agent markdown loading

Backend API surface

GET    /workflows                              — list all workflow definitions
GET    /workflows/:workflowId                  — get single workflow definition
POST   /workflows/:workflowId/runs             — start a workflow run
GET    /workflows/:workflowId/runs/current     — get current run for workflow
GET    /workflows/capabilities/services        — list service capabilities
GET    /workflows/capabilities/health          — health check all services
GET    /workflows/runs/history                 — user's run history
GET    /workflows/validate                     — validate all workflow defs

GET    /workflow-runs/:runId                   — full run detail (modules, artifacts, events)
POST   /workflow-runs/:runId/pause             — pause run
POST   /workflow-runs/:runId/resume            — resume run
POST   /workflow-runs/:runId/run               — run all modules until next gate
POST   /workflow-runs/:runId/modules/:moduleId/run  — run single module
GET    /workflow-runs/:runId/artifacts         — list artifacts
GET    /workflow-runs/:runId/artifacts/:id/content  — read artifact content
GET    /workflow-runs/:runId/events            — list events
POST   /workflow-runs/:runId/approvals/:id     — approve/reject gate

POST   /chat                                   — chat with Grow Agent

# Legacy compat aliases
GET    /workflows/job-application
POST   /workflows/job-application
POST   /workflows/job-application/pause
POST   /workflows/job-application/resume
POST   /workflows/job-application/agents/:moduleId/run
POST   /workflows/job-application/agents/:moduleId/score

5 Sellable Workflows

ID	Title	Urgency	Duration	Modules
interview-to-offer	Interview-to-Offer Accelerator	High	2–5 days	resume → interview-plan → sara → emily → qscore
career-transition	Career Transition Sprint	Medium	1–2 weeks	transition-map → resume
salary-negotiation-war-room	Salary Negotiation War Room	High	24–72 hrs	negotiation-script → emily
promotion-readiness	Promotion Readiness Packet	Medium	1 week	evidence-packet → emily
personal-brand-opportunity-engine	Personal Brand Opportunity Engine	Low	1 week	profile-rewrite

What the backend still needs today

• Verify build/typecheck passes
• Verify all routes respond locally
• Add clean analytics/Q Score summary endpoint if missing
• Ensure service actors work for Q Score
• Smoke-test workflow creation → module run
• Confirm env vars are correct for AVPS deploy

---

3. Dashboard Current State

Existing pages (all using mock data)

app/page.tsx              — Home
app/analytics/page.tsx    — Analytics
app/community/page.tsx    — Community
app/events/page.tsx       — Events
app/features/page.tsx     — Features (available/active tabs)
app/features/[id]/page.tsx — Feature detail
app/mentor/page.tsx       — Mentor
app/pathways/page.tsx     — Pathways
app/productivity/page.tsx — Productivity
app/rewards/page.tsx      — Rewards
app/settings/page.tsx     — Settings
app/social/page.tsx       — Social
app/suggestions/page.tsx  — Suggestions
app/workflows/page.tsx    — Workflows (available/active tabs)
app/workflows/[id]/page.tsx — Workflow detail

Dashboard components

components/AppShell.tsx
components/ModuleHeader.tsx
components/ActiveWorkflowDetail.tsx
components/AvailableWorkflowCard.tsx
components/PromptBar.tsx

Dashboard design system

• Tailwind with custom theme (brand-orange, ink, surface-rail, etc.)
• rounded-tile pattern for cards
• Day simulation via useDay() for demo progression

What the dashboard needs today

1. API layer — typed client to backend (replace mock getWorkflows, getFeatures, etc.)
2. API proxy — app/api/growqr/[...path]/route.ts to avoid CORS issues
3. Workflows page — wire to real backend
4. Workflow detail — add mission state sidebar + workflow chat
5. Talk to Me chat — new chat page with streaming-ish UI
6. Feature pages — port interview/roleplay/resume/Q Score from other repos
7. Analytics — merge Q Score + career performance data

---

4. Reference UI Sources

From growqr-next-frontend

What	Source Path	Use For
v3 Workflows layout	src/app/v3/workflows/page.tsx	Workflow page layout with slim sidebar
v3 Workflow detail	src/app/v3/workflows/interview-to-offer/page.tsx	Active workflow detail pattern
v2 Services (already ported)	src/app/v2/services/interview/*	Interview/roleplay/resume pages
Q Score	src/app/qx-score/page.tsx, src/app/v2/qx-score/page.tsx	Analytics/Q Score UI
Chat route	src/app/api/chat/route.ts	Streaming chat backend pattern
Auth flow	src/app/auth/*	Career profile, goals, onboarding

From growqr-app/frontend

What	Source Path	Use For
Interview components	src/components/interview/*	LiveAvatarVideo, CoachingBanner, EquipmentCheck, etc.
Interview pages	src/app/(dashboard)/upskilling/interview/*	Setup, preview, feedback
Roleplay components	src/components/roleplay/*	LiveAvatarVideo, RoleplayLaunchOverlay, FeedbackDashboard
Resume components	src/components/resume/*	ResumeUpload, ResumeCard, ResumePreviewModal, TemplateGallery
Interview hooks	src/hooks/useInterview*.ts	Session, media, review, recording hooks
Interview lib	src/lib/interview/*	Types, API helpers

---

5. Execution Plan — 6 Hours

Phase 1: Stabilize & Map (0:00–0:30)

Goal: Know exactly what's broken before touching UI.

• Run growqr-backend build + typecheck
• Run growqr-dashboard build
• Check envs: backend URL, Clerk keys, service URLs, AVPS deploy env
• Confirm backend routes respond locally (/workflows, /chat, etc.)
• Document short failure list

Deliverable: Known broken things list. No UI changes yet.

---

Phase 2: Dashboard API Layer (0:30–1:30)

Goal: Dashboard can talk to backend instead of mock data.

Create in growqr-dashboard:

lib/api.ts              — Base fetch wrapper with auth
lib/growqr-api.ts       — Typed API client
types/workflows.ts      — Workflow/run/module types
types/chat.ts           — Chat message types
app/api/growqr/[...path]/route.ts  — Next.js API proxy

Client methods needed:

listWorkflows()
getWorkflow(id)
startWorkflow(workflowId, goal?, input?)
getCurrentRun(workflowId)
getWorkflowRun(runId)
runWorkflow(runId)
runModule(runId, moduleId)
pauseRun(runId)
resumeRun(runId)
sendChat(messages)
getRunArtifacts(runId)
getRunEvents(runId)
approveGate(runId, approvalId, status)

Deliverable: Dashboard fetches real workflow data from backend.

---

Phase 3: Workflows Page MVP (1:30–2:30)

Goal: Workflows become real product pages.

Update these files:

app/workflows/page.tsx               — Wire to real API
app/workflows/[id]/page.tsx          — Wire to real API
components/AvailableWorkflowCard.tsx  — Show real workflow data
components/ActiveWorkflowDetail.tsx   — Show real run state

Required behavior:

• Available tab lists 5 backend workflows with real data
• Each card shows: promise, modules, duration, price, "Start workflow" button
• Starting a workflow calls POST /workflows/:workflowId/runs
• Active section calls GET /workflows/:workflowId/runs/current
• Detail page layout:
  • Left: slim workflow nav
  • Top: current workflow title + status bar
  • Center: workflow chat / work area
  • Right: mission state (modules, artifacts, events, approvals)

Deliverable: User can start and view a workflow from the dashboard.

---

Phase 4: Chat Surfaces (2:30–3:30)

Goal: Product feels agentic with two chat surfaces.

A. Global "Talk to Me" Chat

New page:

app/talk/page.tsx   (or app/chat/page.tsx)

Purpose:

• Agent discovery & workflow recommendation
• Starting workflows from conversation
• Pulling workflow status
• User preferences & memory
• General career questions

Backend: POST /chat

UI should show:

• Streaming-like assistant response (staged states if not truly streaming)
• Tool/session cards when backend returns sessions
• Workflow suggestion/action buttons when backend recommends one
• Progressive states: "Reading memory…" → "Checking workflows…" → "Thinking…" → response

B. Workflow-Specific Chat

Inside app/workflows/[id]/page.tsx:

• "Run next step", "Show status", "Launch interview", "Open artifact", "Approve plan"
• Calls same /chat with workflow context prepended
• Shows module execution results inline

Deliverable: Both chat surfaces are functional and connected to backend.

---

Phase 5: Feature/Service Pages (3:30–4:45)

Goal: Feature cards route to working service UIs.

New pages in dashboard:

app/features/resume/page.tsx
app/features/interview/page.tsx
app/features/roleplay/page.tsx
app/features/qscore/page.tsx

Port strategy (in priority order):

1. Interview — from growqr-app/frontend/src/components/interview/* + growqr-next-frontend/src/app/v2/services/interview/*
2. Roleplay — from growqr-app/frontend/src/components/roleplay/* + growqr-next-frontend/src/app/v2/services/roleplay/*
3. Resume — from growqr-app/frontend/src/components/resume/* + growqr-next-frontend/src/app/v2/services/resume/*
4. Q Score — from growqr-next-frontend/src/app/v2/qx-score/*

Shortcut approach:

• Create dashboard-compatible wrappers, not perfect ports
• Missing backend data → clean empty/loading states
• Support workflow query params: ?workflowRunId=...&moduleId=...

Deliverable: Feature cards open functional service pages.

---

Phase 6: Q Score + Analytics (4:45–5:30)

Goal: Coherent analytics page with real data where available.

Merge from:

• growqr-dashboard/app/analytics/page.tsx (existing)
• growqr-next-frontend/src/app/qx-score/page.tsx
• growqr-next-frontend/src/app/v2/qx-score/page.tsx

Minimum analytics sections:

• Current Q Score (gauge/number)
• Baseline vs Latest comparison
• Workflow progress contribution
• Readiness dimension breakdown
• Recent sessions/events timeline
• Recommended next action

Backend data sources:

• workflowRuns.qscoreBefore for baseline
• qscoreSnapshots table for history
• /workflow-runs/:runId for module progress
• Add GET /analytics/summary endpoint if needed

Deliverable: Analytics page shows real Q Score + workflow progress.

---

Phase 7: Build, Fix, Deploy (5:30–6:15)

Goal: Everything builds, deploys, and team can test.

• cd growqr-backend && bun run typecheck && bun run build
• cd growqr-dashboard && pnpm build
• Fix only blockers: type errors, missing imports, env names, auth/proxy
• Deploy to AVPS
• Send test links + testing checklist to team

Deliverable: Deployed link on AVPS.

---

6. Hard Cuts — What We Are NOT Doing Today

To finish in 6 hours, we explicitly skip:

• Homepage rethink / redesign
• Full billing / entitlement / SKU enforcement
• True streaming protocol (SSE/WebSocket) — simulate with staged UI
• Complete service UI parity with growqr-app
• Deep memory/conversation history UI
• Advanced workflow graph animations
• New backend architecture changes
• Moving/cleaning all three repos
• Community, events, social, rewards, productivity, mentor, pathways, suggestions pages
• Mobile responsiveness polish
• E2E tests

---

7. MVP Acceptance Checklist

By end of session, team should be able to test all of these:

• Auth: Login works with Clerk
• Workflows page: Lists 5 workflows from backend
• Start workflow: User can start Interview-to-Offer
• Active workflow: Detail page shows modules/state/events
• Run module: User can trigger at least one module
• Talk to Me chat: Responds to messages, can suggest/trigger workflows
• Workflow chat: Exists inside workflow detail page
• Features page: Opens Interview, Roleplay, Resume, Q Score
• Analytics: Shows Q Score and workflow progress
• Deploy: Dashboard builds and deploys to AVPS
• Team test link: Sent with testing instructions

---

8. Implementation Priority Order

If time runs short, do these in exactly this order:

1. Dashboard API proxy + typed client
2. Real workflows list / start / current-run
3. Workflow detail shell with mission state + chat
4. Global Talk-to-Me chat page
5. Feature page routing to service pages
6. Q Score / analytics page
7. Build / deploy / test links

---

9. Key Files Reference

Backend

growqr-backend/src/index.ts                    — App entry
growqr-backend/src/config.ts                   — Env config
growqr-backend/src/actors/registry.ts          — Rivet actor registry
growqr-backend/src/actors/user-actor.ts        — Per-user actor
growqr-backend/src/actors/workflow-run-actor.ts — Per-run actor
growqr-backend/src/actors/product-service-actors.ts — Service actors
growqr-backend/src/routes/workflows.ts         — Workflow + run routes
growqr-backend/src/routes/chat.ts              — Chat route
growqr-backend/src/routes/services.ts          — Service routes
growqr-backend/src/workflows/registry.ts       — 5 workflow definitions
growqr-backend/src/workflows/module-runner.ts  — Module execution
growqr-backend/src/workflows/types.ts          — Workflow types
growqr-backend/src/db/schema.ts                — Database schema
growqr-backend/src/agents/catalog.ts           — Agent catalog + prompts

Dashboard

growqr-dashboard/app/layout.tsx                — Root layout
growqr-dashboard/app/page.tsx                  — Home
growqr-dashboard/app/workflows/page.tsx        — Workflows list
growqr-dashboard/app/workflows/[id]/page.tsx   — Workflow detail
growqr-dashboard/app/features/page.tsx         — Features list
growqr-dashboard/app/features/[id]/page.tsx    — Feature detail
growqr-dashboard/app/analytics/page.tsx        — Analytics
growqr-dashboard/components/AppShell.tsx        — Shell + sidebar
growqr-dashboard/components/PromptBar.tsx       — Chat input bar
growqr-dashboard/middleware.ts                  — Clerk middleware
growqr-dashboard/lib/state.ts                  — Day simulation state
growqr-dashboard/data/workflows.ts             — Mock workflow data (TO REPLACE)
growqr-dashboard/data/features.ts              — Mock feature data (TO REPLACE)

Reference (read-only)

growqr-next-frontend/src/app/v3/workflows/*                    — Workflow UI pattern
growqr-next-frontend/src/app/v2/services/interview/*           — Interview pages
growqr-next-frontend/src/app/v2/services/roleplay/*            — Roleplay pages
growqr-next-frontend/src/app/v2/services/resume/*              — Resume pages
growqr-next-frontend/src/app/v2/qx-score/*                     — Q Score UI
growqr-next-frontend/src/app/api/chat/route.ts                 — Chat streaming pattern
growqr-app/frontend/src/components/interview/*                 — Production interview components
growqr-app/frontend/src/components/roleplay/*                  — Production roleplay components
growqr-app/frontend/src/components/resume/*                    — Production resume components
growqr-app/frontend/src/hooks/useInterview*.ts                 — Interview hooks
growqr-app/frontend/src/lib/interview/*                        — Interview lib