Skip to content

feat: Add first-time user onboarding with spotlight tours for app and workflow builder#313

Open
krishna9358 wants to merge 10 commits intomainfrom
krishna9358/onboarding-tutorial
Open

feat: Add first-time user onboarding with spotlight tours for app and workflow builder#313
krishna9358 wants to merge 10 commits intomainfrom
krishna9358/onboarding-tutorial

Conversation

@krishna9358
Copy link
Contributor

@krishna9358 krishna9358 commented Feb 27, 2026 •
edited
Loading

Summary

Adds a complete first-time user onboarding system with two spotlight-based guided tours and server-side state persistence.

Tour 1: App Navigation Tour

  • Welcome dialog introducing ShipSec Studio
  • Spotlight highlights for: Workflow Builder, Template Library, Schedules, Action Center, and Manage Settings (sidebar sections)
  • Keyboard navigation (Arrow keys, Escape)
  • Skip tour button

Tour 2: Workflow Builder Tour

  • Triggers automatically on first visit to the workflow builder after completing Tour 1
  • 10-step guided walkthrough covering: Canvas, Component Library, Node Inspector, Top Bar Actions, Mode Switching (Design/Execute), Execution Inspector, Inspector Tabs, Schedules, and Publish
  • Auto-switches between Design and Execute modes to demonstrate each context
  • Responsive tooltip positioning with width cascade (380px → 320px → fit)
  • requestAnimationFrame continuous tracking for accurate spotlight positioning during layout transitions

State Persistence (Database-backed)

  • user_preferences table with Drizzle ORM schema — composite PK (userId, organizationId), stores has_completed_onboarding and has_completed_builder_tour booleans
  • Backend API: GET /api/v1/users/me/preferences and PATCH /api/v1/users/me/preferences with NestJS module (controller, service, repository)
  • Frontend: TanStack Query hooks with optimistic updates for instant UI response
  • Migration: One-time localStorage → DB migration for existing users, auto-cleans up after sync
  • Table is auto-created on backend startup via drizzle-kit push

UI/UX

  • Spotlight cutout using box-shadow: 0 0 0 9999px technique with animated pulse border
  • Gradient-themed tooltip cards per step with icons
  • Portal-rendered overlay at z-index 200
  • Loading guard prevents dialog flash on page load
  • Skip tour and Back/Next navigation in both tours

Other Changes

  • Top bar dropdown reordered: Undo/Redo → Import/Export → separator → Publish as Template → View Analytics
  • Pinned bun to 1.3.9 to fix NestJS decorator regression in 1.3.10

Files Added

  • backend/src/database/schema/user-preferences.ts — Drizzle table schema
  • backend/src/user-preferences/ — NestJS module (controller, service, repository, dto, module)
  • frontend/src/components/onboarding/OnboardingDialog.tsx — App navigation tour dialog
  • frontend/src/components/onboarding/WorkflowBuilderTour.tsx — Workflow builder tour
  • frontend/src/hooks/queries/useUserPreferencesQueries.ts — TanStack Query hooks
  • frontend/src/store/onboardingStore.ts — Session-only step tracking (Zustand, no persist)

Files Modified

  • frontend/src/components/layout/AppLayout.tsx — Tour 1 integration, DB-backed state, localStorage migration
  • frontend/src/features/workflow-builder/WorkflowBuilder.tsx — Tour 2 integration, DB-backed state
  • frontend/src/components/layout/TopBar.tsx — Dropdown reorder, data-onboarding attributes
  • frontend/src/services/api.ts — User preferences API endpoints
  • frontend/src/lib/queryKeys.ts — User preferences query key
  • backend/src/app.module.ts — Register UserPreferencesModule
  • backend/src/database/schema/index.ts — Export user-preferences schema

Test Plan

  • Fresh user: App tour appears on first login, all 6 steps highlight correct sidebar items
  • Complete app tour → navigate to workflow builder → builder tour starts automatically
  • Builder tour: all 10 steps highlight correct elements, mode switching works
  • Skip tour button dismisses both tours
  • Refresh page after completing tours → tours do not reappear
  • Check user_preferences table in DB shows has_completed_onboarding = true
  • Existing localStorage users: state migrates to DB, localStorage key removed
  • Keyboard nav: Arrow Right/Left for next/back, Escape to close
  • Responsive: tooltips don't overflow on smaller screens

@krishna9358
feat: Add first-time user onboarding tutorial with spotlight-based gu…
86cf416 
…ided walkthrough

Implement a comprehensive onboarding experience for first-time users featuring:
- Spotlight-based guided tour that highlights actual UI elements in the sidebar
- 6-step walkthrough covering Workflow Builder, Templates, Schedules, Action Center, and Manage section
- Smooth spotlight transitions and pulsing rings for visual emphasis
- Tooltip cards positioned next to highlighted elements
- Sidebar forced open during onboarding for visibility
- Automatic Manage section expansion on the final step
- Keyboard navigation (arrow keys and Escape support)
- First-time detection via localStorage persistence
- Auth-gated (only shows for authenticated users)
- Zero new dependencies (uses existing Dialog, Button, Lucide icons, Tailwind)

Architecture:
- useOnboardingStore (Zustand): Manages onboarding state with localStorage persistence
- OnboardingDialog component: Spotlight tour with createPortal rendering for proper z-index
- AppLayout integration: Data attributes on sidebar items, sidebar forcing, settings auto-expand

Signed-off-by: Krishna Mohan <krishanmohank974@gmail.com>
@chatgpt-codex-connector
Copy link

chatgpt-codex-connector bot commented Feb 27, 2026

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Credits must be used to enable repository wide code reviews.

@krishna9358 krishna9358 marked this pull request as draft February 27, 2026 10:00
@krishna9358
feat: Add spotlight-based guided tour for Workflow Builder
cacfe5b 
Extends the onboarding system with a dedicated Workflow Builder tour
that walks first-time users through the builder interface: component
library, canvas, design/execute modes, save, run, and more options.

Signed-off-by: Krishna Mohan <krishanmohank974@gmail.com>
@krishna9358 krishna9358 changed the title feat: Add first-time user onboarding spotlight tour feat: Add first-time user onboarding with spotlight tours for app and workflow builder Mar 2, 2026
@krishna9358
fix: Improve onboarding tour speed, visibility, and UI polish
3294d6d 
- Reduce step transition delay from 350ms to 120ms for snappier feel
- Remove !isNewWorkflow gate so builder tour shows on first visit
- Upgrade both tours with gradient headers, backdrop blur, rounded-2xl
  cards, slide-in animations, close button, and refined progress dots
- Reduce spotlight transition from 500ms to 300ms with ease-out

Signed-off-by: Krishna Mohan <krishanmohank974@gmail.com>
@krishna9358
feat: Add Execute mode, Inspector tabs, and Schedules to builder tour
cbf0666 
Extend the Workflow Builder tour with 3 new steps:
- Execution Inspector panel (run selector, timeline, stop/rerun)
- Inspector tabs (Events, Logs, Agent, Artifacts, I/O, Network)
- Schedules summary bar (create, manage, view scheduled runs)

Signed-off-by: Krishna Mohan <krishanmohank974@gmail.com>
@krishna9358
ci: Pin bun to 1.3.9 to fix NestJS decorator regression in 1.3.10
c1fcb49 
Bun 1.3.10 introduced a breaking change with NestJS decorators where
descriptor.value becomes undefined, causing 6 backend test failures.
Pin to 1.3.9 (last known working version) until the regression is fixed.

Signed-off-by: Krishna Mohan <krishanmohank974@gmail.com>
@krishna9358
feat: Auto-switch modes, add Publish step, and remove step indicators…
e66d7a8 
… from tours

- Auto-switch to Execute mode when tour reaches Execution Inspector and
  Inspector Tabs steps, eliminating manual mode switching
- Auto-restore Design mode when navigating back or completing the tour
- Add Publish as Template step spotlighting the dropdown trigger
- Remove progress dots and step counter from both tour dialogs for
  cleaner UX that doesn't encourage users to skip ahead
- Reorder builder tour: design-mode steps first, execution steps last
  to minimize mode switches
- Add left-side tooltip positioning for inspector panel steps

Signed-off-by: Krishna Mohan <krishanmohank974@gmail.com>
@krishna9358
feat: Consolidate top bar actions and streamline builder tour
77eda11 
Move Publish as Template and View Analytics into the More Options
dropdown. Remove duplicate Welcome step from builder tour. Fix
execution tab tooltip positioning when it would go off-screen left.

Signed-off-by: Krishna Mohan <krishanmohank974@gmail.com>
@krishna9358
feat: Improve onboarding tour layout, skip button, and dropdown order
360b50f 
- Reorder More Options dropdown: Undo/Redo, Import/Export, then
  Publish as Template and View Analytics at the bottom
- Add Skip tour button to both platform and builder tours
- Fix spotlight positioning with requestAnimationFrame continuous
  tracking instead of fragile one-shot setTimeout
- Clamp spotlight to viewport edges for edge-hugging panels
- Expand inspector spotlight to cover parent pl-2 gap
- Use responsive tooltip width cascade (380/320/fit) for side panels

Signed-off-by: Krishna Mohan <krishanmohank974@gmail.com>
@krishna9358
feat: Persist onboarding state in database instead of localStorage
da7372b 
Add user_preferences table and API to store onboarding completion flags
server-side. Frontend uses TanStack Query with optimistic updates for
instant UI response. Includes one-time localStorage→DB migration for
existing users.

Signed-off-by: Krishna Mohan <krishanmohank974@gmail.com>
@krishna9358
fix: Use isSuccess guard for onboarding preferences fallback
acc9fe3 
Default to false (show dialog) when the query has successfully loaded
but data is missing, instead of silently defaulting to true (hide).
Only hide during the loading state to prevent flash.

Signed-off-by: Krishna Mohan <krishanmohank974@gmail.com>
@krishna9358 krishna9358 marked this pull request as ready for review March 3, 2026 11:19
@chatgpt-codex-connector
Copy link

chatgpt-codex-connector bot commented Mar 3, 2026

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Credits must be used to enable repository wide code reviews.

2 similar comments
@chatgpt-codex-connector
Copy link

chatgpt-codex-connector bot commented Mar 3, 2026

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Credits must be used to enable repository wide code reviews.

@chatgpt-codex-connector
Copy link

chatgpt-codex-connector bot commented Mar 3, 2026

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Credits must be used to enable repository wide code reviews.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@krishna9358