Shadow-GuideFlow System Requirements Document

Introduction

The project "Shadow-GuideFlow" aims to develop a web application called GuideFlow. This interactive guide and product demo tool is designed for SaaS teams, enabling non-technical users to transform any workflow they perform in a browser into a shareable, step-by-step interactive guide, how-to article, or product demo, without writing code or editing video.

System Overview

GuideFlow addresses the inefficiencies faced by SaaS companies and internal teams who spend excessive time creating static documentation that quickly becomes outdated. By capturing real user actions directly from the browser, GuideFlow auto-generates interactive guides with annotated screenshots, hotspots, and optional voiceover/text callouts, significantly reducing the time required to create guides.

Product Interpretation and Delivery Boundary

• Domain Descriptors:

  • Interactive guide creation: GuideFlow captures user actions to auto-generate guides.
  • Team collaboration and workspace management: Supports shared workspaces for team collaboration.

• What is being built: A web application that allows users to create interactive guides from browser workflows, manage these guides within workspaces, and share them publicly or privately.

• Excluded Assumptions: Generic CMS features and standalone video editing tools are not part of this project.

• Access: Application-owned identity with authentication required for dashboard/editor/analytics/settings screens; public guide viewer requires no login.

• Behavior Contracts:

  • Edit Guide: SaaS onboarding/product teams can customize guides in the step editor.
  • Publish Guide: Internal ops/HR teams can publish guides to generate public URLs and embed codes.
  • View Guide: Viewers can access guides via public links without needing an account.
  • Organize Guides and Control Visibility: Authenticated users can organize guides and control their visibility.
  • Invite and Manage Team Members in Workspace: Workspace admins can invite users and manage roles.
  • Authenticate User and Enforce Permissions: Users are authenticated to access various app surfaces.
  • Capture Workflow to Create Guide Draft: Customer support and success teams can initiate guide recording sessions.

Page Content and Component Coverage

• Marketing Landing Page: Public entry point showcasing value proposition, pricing, and sign-up CTA.
• Sign Up / Log In Pages: Authentication entry for users via email/password and Google OAuth.
• Workspace Dashboard: Central hub for managing guides and workspaces, featuring search, filter, and "New Guide" button.
• Guide Recorder/Upload Flow: Interface for starting recording sessions or uploading screenshots.
• Step Editor: Allows editing and enhancement of captured guide steps with reorderable lists and callout tools.
• Publish Success Screen: Displays public link, embed code, and visibility toggle for published guides.
• Guide Analytics Page: Provides insights into guide usage and performance.
• Public Guide Viewer: Full-screen step-through experience for guide consumption without login.
• Workspace Settings: Manage team members and billing.
• Account Settings: Manage user profile and connected accounts.

Functional Requirements

• As a Customer support and success team member, I should be able to install a browser extension or use an in-app recorder to capture a sequence of screens/clicks on any website, which automatically generates a draft guide with one step per captured screen and an auto-cropped screenshot. explicit
• As a User, I should be able to edit a generated guide in a step editor: reorder steps, edit step titles/descriptions, add text callouts, arrows, and blur/redact boxes over sensitive info on each screenshot. explicit
• As a User, I should be able to publish a guide and get a shareable public link, plus an embeddable iframe/JS snippet to drop the guide into my own website or help center. explicit
• As a User, I should be able to organize guides into folders/collections and control each guide's visibility (private, unlisted link, public). explicit
• As a User, I should be able to view basic analytics per guide: total views, completion rate, and drop-off step. explicit
• As a User on the free plan, I should be capped at 5 published guides and be able to upgrade to a paid plan for unlimited guides via a hosted checkout. explicit
• As a User, I should be able to invite teammates to a shared workspace so guides are co-owned and editable by the team. explicit
• As a Viewer, I should be able to click through a published guide step by step in a clean, distraction-free viewer with a progress indicator, without needing an account. explicit

User Personas

• Customer Support and Success Teams: Primary users for creating guides.
• SaaS Onboarding/Product Teams: Users for building product tours.
• Internal Ops/HR Teams: Users for documenting SOPs.
• Viewers: Consumers of published guides.

Core User Flows

1. Visitor Flow:

   • Lands on the marketing homepage.
   • Signs up with email or Google OAuth.
   • Enters an empty workspace dashboard.
   • Clicks "New Guide" to start a guide creation process.

2. Guide Creation Flow:

   • Uploads a sequence of screenshots or uses the recorder to auto-capture steps.
   • Lands in the step editor where captured steps appear as an ordered list with screenshots.
   • Edits titles, adds callouts/blur boxes, reorders steps, and clicks "Publish."

3. Publishing Flow:

   • Publishing generates a public URL and an embed snippet.
   • Both are shown on a success screen with copy buttons.
   • The guide appears in the dashboard's guide list with a view count.

4. Guide Viewing Flow:

   • A separate anonymous viewer opens the public link.
   • Clicks "Next"/"Back" through the guide's steps without needing an account.

Visuals Colors and Theme

• Primary: #007BFF
• Primary Light: #66B2FF
• Secondary: #6C757D
• Accent: #28A745
• Highlight: #FFC107
• Background: #FFFFFF
• Surface: #F8F9FA
• Text: #212529
• Text Muted: #6C757D
• Border: #DEE2E6

Signature Design Concept

The design concept for GuideFlow focuses on a clean, modern interface that emphasizes usability and clarity. The marketing landing page will feature a dynamic hero section with subtle animations to draw attention to the product's key benefits. The workspace dashboard will use a card-based layout to organize guides and folders, providing a clear visual hierarchy. The step editor will feature a split-panel design, allowing users to easily navigate and edit guide steps. The public guide viewer will offer a distraction-free experience, with a progress indicator to guide viewers through the steps.

Interaction Model & Motion Direction

• Marketing Landing Page: Animated with moderate scroll-triggered reveals and hover transitions.
• Internal Pages: Static layout prioritizing clarity and data density.
• Public Guide Viewer: Minimal motion to maintain focus on the guide content.

Non-Functional Requirements

• Performance: The application must be responsive and performant on both desktop and tablet-sized screens. required_inference
• Security: Ensure secure access control and data protection for all user data. required_inference
• Scalability: The system should support multiple concurrent users without performance degradation. required_inference

Tech Stack

• Frontend: React/Next.js
• Backend: REST API
• Database: PostgreSQL
• Integrations: Stripe for billing, Google OAuth for authentication, S3-compatible storage for screenshots

Assumptions and Constraints

• The application will be built as a standard modern web app with a clear separation between public-facing and authenticated routes.
• The step editor is optimized for desktop use, while other components are responsive for tablet-sized screens.
• The system will use structured JSON for storing callout data in the step editor to maintain flexibility.

Glossary

• GuideFlow: The web application being developed.
• SaaS: Software as a Service.
• OAuth: Open Authorization, a protocol for secure authorization.
• API: Application Programming Interface.
• JSON: JavaScript Object Notation, a lightweight data interchange format.