Story Prompts Generator Flow - Business Rules & Test Cases

Tool Purpose: Generate creative writing prompts for educational use, organized by grade level, genre, and theme with AI-powered customization.

Last Updated: July 16, 2025
Version: 1.0
Tool Status: Production
Code Location: /apps/tools-app/src/components/story-prompts/

Flow Overview

Flow Types

Browse Mode: Explore curated collections and prompts by grade/genre
Generate Mode: Create custom prompts with AI using specific parameters
Share Mode: Share individual prompts or collections with teachers/students
Save Mode: Save prompts for later use (authenticated users)

Core Principles

Educational Focus: Age-appropriate content for K-12 education
Curriculum Alignment: Prompts support common writing standards
Teacher-Friendly: Easy to use in classroom settings
Student Engagement: Inspiring and creative prompt generation
Accessibility: Clear language and diverse themes

User Journey Flow


Landing → Browse/Generate → Filter/Options → View Prompts → Save/Share
    ↓         ↓                  ↓             ↓           ↓
  Overview   Content          Customize    Review      Use in Class

Step-by-Step Business Rules

BR-SP-001: Landing Page Display

Rule: Show grade levels, genres, featured collections, and AI generator access
Implementation: StoryPromptsLanding.tsx:130-355 - Landing page layout
Test: Verify all navigation options are visible and functional
Rationale: Provide clear pathways to content discovery

BR-SP-002: Grade Level Organization

Rule: Display grade levels from Kindergarten to High School with age ranges
Implementation: StoryPromptsLanding.tsx:26-37 - Grade level data
Test: Verify grade level cards link to appropriate content
Rationale: Support age-appropriate content selection

BR-SP-003: Genre Categories

Rule: Display 6 main genres (Fantasy, Mystery, Adventure, Sci-Fi, Realistic, Historical)
Implementation: StoryPromptsLanding.tsx:39-46 - Genre definitions
Test: Verify genre cards display correct descriptions and links
Rationale: Enable content discovery by story type preferences

Step 2: Browse & Filter System

BR-SP-004: Grade Level Filtering

Rule: Filter prompts by specific grade levels (K, 1-12, High School)
Implementation: FilterPanel.tsx - Grade level filter component
Test: Verify filtering returns appropriate content for each grade
Rationale: Ensure age-appropriate content delivery

BR-SP-005: Genre Filtering

Rule: Filter prompts by genre with multi-select capability
Implementation: FilterPanel.tsx - Genre filter component
Test: Verify genre filtering works individually and in combination
Rationale: Support diverse writing interests and curriculum needs

BR-SP-006: Theme Filtering

Rule: Filter by themes (friendship, courage, family, nature, etc.)
Implementation: FilterPanel.tsx - Theme filter with tag support
Test: Verify theme filtering reduces results appropriately
Rationale: Support specific educational objectives and values

BR-SP-007: Difficulty Filtering

Rule: Filter by difficulty levels (Easy, Medium, Hard)
Implementation: FilterPanel.tsx - Difficulty selection
Test: Verify difficulty filtering matches student skill levels
Rationale: Provide appropriate challenge levels for different abilities

Step 3: AI Generation System

BR-SP-008: Generation Parameters

Rule: Allow customization of count, grade level, genre, themes, and difficulty
Implementation: GeneratePromptsPanel.tsx - Generation options
Test: Verify all parameters affect AI generation appropriately
Rationale: Enable personalized content creation for specific needs

BR-SP-009: AI Content Generation

Rule: Generate 1-20 prompts using GPT-4 with educational focus
Implementation: story-prompts-ai.ts:StoryPromptsAI.generatePrompts() - AI service
Test: Verify AI generates appropriate, educational content
Rationale: Provide high-quality, curriculum-aligned writing prompts

BR-SP-010: Content Validation

Rule: Validate AI responses for educational appropriateness and structure
Implementation: story-prompts-ai.ts:validatePromptResponse() - Validation logic
Test: Verify inappropriate content is filtered out
Rationale: Ensure safe, educational content for all age groups

BR-SP-011: Prompt Metadata Generation

Rule: Generate writing skills, word count ranges, and time estimates
Implementation: story-prompts-ai.ts - Metadata generation
Test: Verify metadata accurately reflects prompt requirements
Rationale: Support curriculum planning and assignment creation

Step 4: Collections System

BR-SP-012: Featured Collections

Rule: Display curated collections on landing page and collections page
Implementation: StoryPromptsLanding.tsx:216-243 - Featured collections
Test: Verify featured collections display with correct metadata
Rationale: Highlight high-quality, educator-approved content

BR-SP-013: Collection Organization

Rule: Group prompts by theme, grade level, or educational objective
Implementation: CollectionCard.tsx - Collection display component
Test: Verify collections contain appropriate, related prompts
Rationale: Support structured curriculum integration

BR-SP-014: Collection SEO

Rule: Generate SEO-optimized titles, descriptions, and keywords for collections
Implementation: Database schema with SEO fields
Test: Verify SEO metadata is properly generated and displayed
Rationale: Support discovery through search engines

Step 5: Prompt Display & Interaction

BR-SP-015: Prompt Card Display

Rule: Show prompt text, grade level, genre, difficulty, and metadata
Implementation: PromptCard.tsx - Prompt display component
Test: Verify all prompt information displays correctly
Rationale: Provide complete information for educational use

BR-SP-016: Prompt Interaction

Rule: Support saving, sharing, and rating prompts
Implementation: PromptCard.tsx - Interaction buttons
Test: Verify all interaction features work correctly
Rationale: Enable personalized prompt management

BR-SP-017: Writing Skills Display

Rule: Show writing skills targeted by each prompt (dialogue, description, etc.)
Implementation: PromptCard.tsx - Skills badges
Test: Verify writing skills are accurately displayed
Rationale: Support curriculum alignment and skill development

Rule: Generate shareable links for individual prompts
Implementation: PromptShareModal.tsx - Sharing interface
Test: Verify sharing links work correctly
Rationale: Enable easy sharing with students and colleagues

Rule: Share entire collections with SEO-optimized pages
Implementation: Collection sharing endpoints
Test: Verify collection sharing includes all prompts
Rationale: Support classroom distribution of themed content

Rule: Track when shared prompts are used for writing
Implementation: Share response tracking system
Test: Verify sharing analytics are captured
Rationale: Measure tool effectiveness and engagement

API Integration

Core API Endpoints

GET /api/story-prompts

Purpose: Browse and filter story prompts Query Parameters:


{
  gradeLevel?: string,
  genre?: string,
  difficulty?: 'easy' | 'medium' | 'hard',
  themes?: string[],
  search?: string,
  limit?: number,
  offset?: number
}

Response Schema:


{
  success: boolean,
  data: StoryPrompt[],
  meta: {
    total: number,
    hasMore: boolean,
    filters: FilterOptions
  }
}

Business Rules:

BR-SP-021: Validate all query parameters
BR-SP-022: Return age-appropriate content only
BR-SP-023: Support pagination for large result sets
BR-SP-024: Include filter metadata for UI

POST /api/story-prompts/generate

Purpose: Generate custom story prompts with AI Request Schema:


{
  count: number,
  gradeLevel: string,
  ageRange: string,
  genre: string,
  themes: string[],
  difficulty: 'easy' | 'medium' | 'hard',
  promptType?: 'opening' | 'character' | 'situation' | 'dialogue' | 'plot',
  writingSkills?: string[],
  basedOn?: string
}

Response Schema:


{
  success: boolean,
  prompts: StoryPrompt[],
  collection?: StoryPromptCollection,
  remainingLimit: number,
  generationTime: number
}

Business Rules:

BR-SP-025: Validate generation parameters
BR-SP-026: Check rate limits (15/day anonymous, 150/day authenticated)
BR-SP-027: Generate educational, age-appropriate content
BR-SP-028: Track AI usage and costs

POST /api/story-prompts/save

Purpose: Save prompts to user account Request Schema:


{
  promptId: string,
  notes?: string
}

Business Rules:

BR-SP-029: Require authentication for saving
BR-SP-030: Prevent duplicate saves
BR-SP-031: Support personal notes on saved prompts
BR-SP-032: Track save analytics

GET /api/story-prompts/collections

Purpose: Browse prompt collections Query Parameters:


{
  featured?: boolean,
  gradeLevel?: string,
  theme?: string,
  limit?: number
}

Business Rules:

BR-SP-033: Return published collections only
BR-SP-034: Support filtering by education parameters
BR-SP-035: Include prompt counts and metadata
BR-SP-036: Optimize for SEO and discovery

GET /api/story-prompts/collections/[slug]

Purpose: Get specific collection with all prompts Business Rules:

BR-SP-037: Validate collection slug
BR-SP-038: Return collection with all associated prompts
BR-SP-039: Include SEO metadata for sharing
BR-SP-040: Track collection view analytics

POST /api/story-prompts/share

Purpose: Create shareable link for prompts Request Schema:


{
  promptIds: string[],
  title?: string,
  description?: string
}

Business Rules:

BR-SP-041: Generate unique share identifiers
BR-SP-042: Support sharing multiple prompts
BR-SP-043: Include custom titles and descriptions
BR-SP-044: Track sharing analytics

GET /api/story-prompts/share/[id]

Purpose: Access shared prompts Business Rules:

BR-SP-045: Validate share identifier
BR-SP-046: Return shared prompts with metadata
BR-SP-047: Track access analytics
BR-SP-048: Support SEO for shared content

Data Persistence

Database Schema

tools_story_prompts Table

Core Content:

id (UUID): Unique prompt identifier
prompt_text (TEXT): The actual writing prompt
prompt_type (VARCHAR): Type of prompt (opening, character, etc.)

Educational Metadata:

grade_level (VARCHAR): Target grade level
age_range (VARCHAR): Age range (e.g., “8-10”)
genre (VARCHAR): Story genre
themes (TEXT[]): Thematic elements
difficulty (VARCHAR): Difficulty level
writing_skills (TEXT[]): Skills practiced
word_count_range (VARCHAR): Expected word count
time_estimate (VARCHAR): Time to complete

AI & Quality:

is_ai_generated (BOOLEAN): Generated by AI
ai_generation_prompt (TEXT): AI prompt used
ai_confidence (DECIMAL): AI confidence score
is_reviewed (BOOLEAN): Reviewed by educators

Engagement:

view_count, save_count, use_count
rating_sum, rating_count
is_featured (BOOLEAN): Featured content

SEO:

seo_title, seo_description, keywords[]

tools_story_prompt_collections Table

Collection Metadata:

id (UUID): Unique collection identifier
title (VARCHAR): Collection name
description (TEXT): Collection description
slug (VARCHAR): URL-friendly identifier
grade_level (VARCHAR): Target grade level
theme (VARCHAR): Collection theme
is_featured (BOOLEAN): Featured collection
is_published (BOOLEAN): Published status

SEO & Discovery:

seo_title, seo_description, keywords[]

tools_collection_prompts Table

Association Table:

collection_id (UUID): References collections
prompt_id (UUID): References prompts
sort_order (INTEGER): Order within collection

tools_user_saved_prompts Table

User Personalization:

user_id (UUID): References auth.users
prompt_id (UUID): References prompts
session_id (TEXT): For anonymous users
saved_at (TIMESTAMP): Save timestamp
notes (TEXT): User notes on prompt

Data Flow Rules

BR-SP-049: Collection-Prompt Relationship

Rule: Collections can contain multiple prompts, prompts can be in multiple collections
Implementation: Many-to-many relationship via junction table
Test: Verify collection operations maintain referential integrity
Rationale: Support flexible content organization

BR-SP-050: User-Prompt Relationship

Rule: Users can save prompts with personal notes
Implementation: User saved prompts with notes field
Test: Verify save/unsave operations work correctly
Rationale: Enable personalized prompt management

BR-SP-051: Anonymous User Support

Rule: Anonymous users can browse and generate but not save
Implementation: Session-based tracking for anonymous users
Test: Verify anonymous user limitations are enforced
Rationale: Balance accessibility with feature incentives

Collections & Browsing System

Content Organization

BR-SP-052: Grade Level Organization

Rule: Organize content by specific grade levels with age ranges
Implementation: Grade level filtering and navigation
Test: Verify grade-appropriate content is properly categorized
Rationale: Support curriculum planning and age-appropriate selection

BR-SP-053: Genre Organization

Rule: Organize by major genres with clear descriptions
Implementation: Genre-based navigation and filtering
Test: Verify genre categories contain appropriate content
Rationale: Support diverse writing interests and curriculum needs

BR-SP-054: Theme Organization

Rule: Support thematic organization across genres and grades
Implementation: Multi-tag theme system
Test: Verify theme filtering works across different content types
Rationale: Enable values-based and topic-specific content selection

Discovery Features

BR-SP-055: Search Functionality

Rule: Full-text search across prompt text, themes, and metadata
Implementation: Search API with relevance scoring
Test: Verify search returns relevant results
Rationale: Enable quick content discovery

BR-SP-056: Featured Content

Rule: Highlight high-quality, educator-approved content
Implementation: Featured flags and special display
Test: Verify featured content is prominently displayed
Rationale: Guide users to highest-quality content

Rule: Show related prompts based on grade, genre, and theme
Implementation: Content recommendation algorithm
Test: Verify related content suggestions are relevant
Rationale: Encourage exploration and provide alternatives

Test Case Categories

Critical Path Testing

TC-SP-001: Browse to Generate Flow

Tests: BR-SP-001, BR-SP-002, BR-SP-008, BR-SP-009
Scenario: User browses landing → selects grade level → generates custom prompts
Expected: Successful prompt generation with appropriate content
Implementation: e2e/story-prompts-browse.test.ts
Priority: P0 (Critical)

TC-SP-002: Collection Browse Flow

Tests: BR-SP-012, BR-SP-013, BR-SP-033, BR-SP-037
Scenario: User views featured collections → selects collection → browses prompts
Expected: Collection displays with all associated prompts
Implementation: e2e/collections-browse.test.ts
Priority: P0 (Critical)

TC-SP-003: AI Generation Flow

Tests: BR-SP-008, BR-SP-009, BR-SP-010, BR-SP-011
Scenario: User customizes parameters → generates prompts → reviews results
Expected: AI generates appropriate, educational content
Implementation: e2e/ai-generation.test.ts
Priority: P0 (Critical)

Business Logic Testing

TC-SP-004: Grade Level Filtering

Tests: BR-SP-004, BR-SP-021, BR-SP-022
Scenario: Filter prompts by different grade levels
Expected: Only age-appropriate content is returned
Implementation: integration/filtering.test.ts
Priority: P1 (High)

TC-SP-005: Content Validation

Tests: BR-SP-010, BR-SP-027
Scenario: AI generates various content types
Expected: All content is educational and appropriate
Implementation: unit/content-validation.test.ts
Priority: P1 (High)

Tests: BR-SP-018, BR-SP-019, BR-SP-041, BR-SP-042
Scenario: User shares individual prompts and collections
Expected: Sharing works with proper access controls
Implementation: integration/sharing.test.ts
Priority: P1 (High)

Integration Testing

TC-SP-007: Database Operations

Tests: BR-SP-049, BR-SP-050, BR-SP-051
Scenario: Create prompts → add to collections → save by users
Expected: All database operations maintain data integrity
Implementation: integration/database.test.ts
Priority: P1 (High)

TC-SP-008: API Endpoints

Tests: BR-SP-021-048
Scenario: Test all API endpoints with various parameters
Expected: All endpoints return correct data and handle errors
Implementation: integration/api.test.ts
Priority: P1 (High)

Edge Case Testing

TC-SP-009: Large Collection Handling

Tests: BR-SP-023, BR-SP-035
Scenario: Browse collections with hundreds of prompts
Expected: Pagination and performance remain acceptable
Implementation: performance/large-collections.test.ts
Priority: P2 (Medium)

TC-SP-010: Concurrent Generation

Tests: BR-SP-026, BR-SP-028
Scenario: Multiple users generate prompts simultaneously
Expected: Rate limiting and AI service handle concurrent requests
Implementation: performance/concurrent.test.ts
Priority: P2 (Medium)

TC-SP-011: Search Performance

Tests: BR-SP-055
Scenario: Search large prompt database with complex queries
Expected: Search returns results within acceptable time
Implementation: performance/search.test.ts
Priority: P2 (Medium)

Performance Requirements

Response Time Standards

BR-SP-058: Browse Response Time

Rule: Prompt browsing must load within 1 second
Implementation: Optimized database queries and caching
Test: Verify browse operations meet time requirements
Rationale: Support fluid content discovery

BR-SP-059: AI Generation Time

Rule: Prompt generation must complete within 8 seconds
Implementation: Optimized AI prompts and timeout handling
Test: Verify generation completes within time limit
Rationale: Maintain user engagement during content creation

BR-SP-060: Search Response Time

Rule: Search results must return within 500ms
Implementation: Full-text search indexing and optimization
Test: Verify search performance across different query types
Rationale: Support immediate content discovery

Scalability Requirements

BR-SP-061: Content Volume Support

Rule: Support 10,000+ prompts with fast browsing
Implementation: Proper database indexing and query optimization
Test: Verify performance with large content volumes
Rationale: Support comprehensive educational content library

BR-SP-062: Concurrent User Support

Rule: Support 200+ concurrent users browsing content
Implementation: Efficient caching and database connections
Test: Load testing with concurrent users
Rationale: Support classroom and institutional usage

Error Handling

User-Facing Error Scenarios

BR-SP-063: AI Service Failures

Rule: Display clear error messages with alternative suggestions
Implementation: Error boundaries and fallback content
Test: Verify error handling provides helpful guidance
Rationale: Maintain user confidence during technical issues

BR-SP-064: Content Loading Errors

Rule: Show loading states and retry mechanisms
Implementation: Loading indicators and retry logic
Test: Verify error recovery works correctly
Rationale: Handle temporary network issues gracefully

BR-SP-065: Search No Results

Rule: Provide helpful suggestions when no results found
Implementation: No results page with alternative suggestions
Test: Verify no results handling is user-friendly
Rationale: Guide users to successful content discovery

System Error Handling

BR-SP-066: Database Error Recovery

Rule: Graceful degradation when database is unavailable
Implementation: Cached content and error logging
Test: Verify system remains functional during database issues
Rationale: Maintain service availability under adverse conditions

BR-SP-067: Rate Limit Handling

Rule: Clear communication about rate limits with upgrade paths
Implementation: Rate limit UI with registration encouragement
Test: Verify rate limit messages are helpful
Rationale: Convert rate-limited users to registered users

Analytics & Monitoring

Educational Metrics

BR-SP-068: Content Usage Tracking

Rule: Track prompt views, saves, and usage by educators
Implementation: Comprehensive analytics on prompt interactions
Test: Verify analytics capture educational usage patterns
Rationale: Understand content effectiveness and popularity

BR-SP-069: Generation Quality Metrics

Rule: Track AI generation success rates and user satisfaction
Implementation: Quality scoring and user feedback tracking
Test: Verify quality metrics are accurately captured
Rationale: Improve AI generation and content quality

BR-SP-070: Curriculum Alignment Tracking

Rule: Track usage by grade level and subject area
Implementation: Educational metadata analytics
Test: Verify curriculum tracking provides useful insights
Rationale: Support curriculum planning and content development

Business Intelligence

BR-SP-071: User Engagement Patterns

Rule: Track user journey from browse to generation to usage
Implementation: Funnel analytics and user behavior tracking
Test: Verify engagement metrics are comprehensively captured
Rationale: Optimize user experience and feature development

BR-SP-072: Content Performance Analysis

Rule: Analyze which content types and themes perform best
Implementation: Content analytics dashboard
Test: Verify content analytics provide actionable insights
Rationale: Guide content strategy and development priorities

Security & Privacy

Educational Content Safety

BR-SP-073: Content Appropriateness

Rule: All content must be appropriate for educational use
Implementation: Content validation and moderation systems
Test: Verify inappropriate content is filtered out
Rationale: Ensure safe, educational environment for all users

BR-SP-074: User Data Protection

Rule: Protect user data and saved content privacy
Implementation: Data encryption and access controls
Test: Verify user data protection measures
Rationale: Maintain trust and comply with educational privacy standards

BR-SP-075: Anonymous User Privacy

Rule: Anonymous users can browse without data collection
Implementation: Session-based tracking with minimal data
Test: Verify anonymous user privacy is protected
Rationale: Enable educational access without privacy concerns

Last Updated: July 16, 2025
Maintained by: Tools Development & Testing Teams

Story Prompts Generator Flow - Business Rules & Test Cases

📋 Table of Contents

Flow Overview

Flow Types

Core Principles

User Journey Flow

Step-by-Step Business Rules

Step 1: Landing & Navigation

BR-SP-001: Landing Page Display

BR-SP-002: Grade Level Organization

BR-SP-003: Genre Categories

Step 2: Browse & Filter System

BR-SP-004: Grade Level Filtering

BR-SP-005: Genre Filtering

BR-SP-006: Theme Filtering

BR-SP-007: Difficulty Filtering

Step 3: AI Generation System

BR-SP-008: Generation Parameters

BR-SP-009: AI Content Generation

BR-SP-010: Content Validation

BR-SP-011: Prompt Metadata Generation

Step 4: Collections System

BR-SP-012: Featured Collections

BR-SP-013: Collection Organization

BR-SP-014: Collection SEO

Step 5: Prompt Display & Interaction

BR-SP-015: Prompt Card Display

BR-SP-016: Prompt Interaction

BR-SP-017: Writing Skills Display

Step 6: Sharing System

BR-SP-018: Individual Prompt Sharing

BR-SP-019: Collection Sharing

BR-SP-020: Share Response Tracking

API Integration

Core API Endpoints

GET /api/story-prompts

POST /api/story-prompts/generate

POST /api/story-prompts/save

GET /api/story-prompts/collections

GET /api/story-prompts/collections/[slug]

POST /api/story-prompts/share

GET /api/story-prompts/share/[id]

Data Persistence

Database Schema

tools_story_prompts Table

tools_story_prompt_collections Table

tools_collection_prompts Table

tools_user_saved_prompts Table

Data Flow Rules

BR-SP-049: Collection-Prompt Relationship

BR-SP-050: User-Prompt Relationship

BR-SP-051: Anonymous User Support

Collections & Browsing System

Content Organization

BR-SP-052: Grade Level Organization

BR-SP-053: Genre Organization

BR-SP-054: Theme Organization

Discovery Features

BR-SP-055: Search Functionality

BR-SP-056: Featured Content

BR-SP-057: Related Content

Test Case Categories

Critical Path Testing

TC-SP-001: Browse to Generate Flow

TC-SP-002: Collection Browse Flow

TC-SP-003: AI Generation Flow

Business Logic Testing

TC-SP-004: Grade Level Filtering

TC-SP-005: Content Validation

TC-SP-006: Sharing System

Integration Testing

TC-SP-007: Database Operations

TC-SP-008: API Endpoints

Edge Case Testing

TC-SP-009: Large Collection Handling

TC-SP-010: Concurrent Generation

TC-SP-011: Search Performance

Performance Requirements

Response Time Standards

BR-SP-058: Browse Response Time