Skip to Content
📚 MyStoryFlow Docs — Your guide to preserving family stories
Tools Framework16-Tool Framework Architecture

16-Tool Framework Architecture

Overview

The MyStoryFlow Tools Framework is a comprehensive system for implementing AI-powered writing and creative tools. Based on analysis of successful existing tools (Story Prompts, Book Blurbs, Flashcards), this framework provides reusable patterns, standardized architecture, and proven implementation strategies for all 16 planned tools.

Framework Goals

  • Reusability: 80% code sharing between similar tools
  • Scalability: Built-in admin management and bulk operations
  • Community: Response system for user-generated content
  • SEO Power: Each tool generates indexable, searchable content
  • Business Integration: Natural funnel to MyStoryFlow main platform
  • AI Efficiency: Centralized prompt management and cost optimization

Tool Classification

Story Prompt Architecture (14/16 tools)

Most tools generate writing prompts that users can respond to:

Romance & Love Cluster (5 tools)

  1. Romance Writing Prompts Generator
  2. Love Story Ideas Generator
  3. Romance Character Generator
  4. Romance Dialogue Generator
  5. Romance Conflict Generator

Family Storytelling Cluster (3 tools) 6. Family Storytelling Ideas Generator 7. Family Memory Prompts Generator 8. Family Character Profile Generator

Adventure & Mystery Cluster (4 tools) 9. Adventure Story Ideas Generator 10. Mystery Writing Prompts Generator 11. Mystery Story Ideas Generator 12. Adventure Character Generator

Horror & Comedy Cluster (2 tools) 13. Horror Writing Prompts Generator 14. Comedy Story Ideas Generator

Multi-Variant Generator Architecture (2/16 tools)

Tools that generate multiple versions with analysis: 15. Story Plot Generator (All Genres) 16. Creative Writing Prompts Generator

Core Architecture Components

1. Database Schema Pattern

Every tool follows this standardized schema:

-- Main content table
CREATE TABLE tools_[tool_name] (
  -- Identity & sharing
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  share_code TEXT UNIQUE NOT NULL,
  
  -- Ownership
  user_id UUID REFERENCES auth.users(id),
  session_id TEXT NOT NULL,
  
  -- Visibility & management
  is_public BOOLEAN DEFAULT FALSE,
  is_featured BOOLEAN DEFAULT FALSE,
  is_reviewed BOOLEAN DEFAULT FALSE,
  
  -- Analytics
  view_count INTEGER DEFAULT 0,
  share_count INTEGER DEFAULT 0,
  export_count INTEGER DEFAULT 0,
  
  -- SEO optimization
  seo_title TEXT,
  seo_description TEXT,
  keywords TEXT[],
  
  -- AI integration
  is_ai_generated BOOLEAN DEFAULT TRUE,
  ai_generation_prompt TEXT,
  ai_confidence DECIMAL(3,2) DEFAULT 0.8,
  ai_tokens_used INTEGER,
  ai_cost_usd DECIMAL(10,4),
  ai_model TEXT,
  generation_time_ms INTEGER,
  
  -- Content (flexible JSONB for tool-specific data)
  content JSONB NOT NULL,
  generation_options JSONB,
  metadata JSONB DEFAULT '{}'::jsonb,
  
  -- Tool-specific fields
  [specialized_fields_per_tool],
  
  -- Timestamps
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW(),
  expires_at TIMESTAMPTZ -- for anonymous content
);
 
-- User responses table (for prompt-based tools)
CREATE TABLE tools_[tool_name]_responses (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  prompt_id UUID REFERENCES tools_[tool_name](id) ON DELETE CASCADE,
  user_id UUID REFERENCES auth.users(id),
  session_id TEXT NOT NULL,
  
  title TEXT NOT NULL,
  content TEXT NOT NULL,
  word_count INTEGER DEFAULT 0,
  
  is_public BOOLEAN DEFAULT FALSE,
  is_featured BOOLEAN DEFAULT FALSE,
  
  view_count INTEGER DEFAULT 0,
  like_count INTEGER DEFAULT 0,
  share_count INTEGER DEFAULT 0,
  
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);
 
-- Collections table (themed prompt sets)
CREATE TABLE tools_[tool_name]_collections (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  title TEXT NOT NULL,
  description TEXT,
  slug TEXT UNIQUE NOT NULL,
  
  is_featured BOOLEAN DEFAULT FALSE,
  is_published BOOLEAN DEFAULT TRUE,
  
  seo_title TEXT,
  seo_description TEXT,
  keywords TEXT[],
  
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);
 
-- Analytics table
CREATE TABLE tools_[tool_name]_analytics (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  content_id UUID REFERENCES tools_[tool_name](id),
  event_type TEXT NOT NULL,
  event_data JSONB,
  user_id UUID REFERENCES auth.users(id),
  session_id TEXT,
  ip_address TEXT,
  user_agent TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

2. API Architecture Pattern

Each tool implements these standardized endpoints:

// Public endpoints
POST   /api/[tool-name]/generate           // Generate new content
GET    /api/[tool-name]/[id]               // View specific content
POST   /api/[tool-name]/[id]/export        // Export content
POST   /api/[tool-name]/[id]/share         // Create shareable link
GET    /api/[tool-name]/browse             // Browse public content
 
// Response system (for prompt-based tools)
GET    /api/[tool-name]/[id]/responses     // View responses
POST   /api/[tool-name]/[id]/responses     // Create response
GET    /api/[tool-name]/responses/[id]     // View specific response
 
// Admin endpoints
GET    /api/admin/[tool-name]/browse       // Admin content management
POST   /api/admin/[tool-name]/bulk-generate // Bulk content creation
POST   /api/admin/[tool-name]/[id]/review  // Quality review
POST   /api/admin/[tool-name]/[id]/feature // Feature content
GET    /api/admin/[tool-name]/analytics    // Performance metrics
POST   /api/admin/[tool-name]/[id]/set-expiration // Content lifecycle
 
// Collections management
GET    /api/admin/[tool-name]/collections  // Manage collections
POST   /api/admin/[tool-name]/collections  // Create collection
POST   /api/admin/[tool-name]/collections/[id]/generate-prompts // Bulk generate for collection

3. AI Service Pattern

All tools use this standardized AI integration approach:

export class [ToolName]AI {
  private openai: OpenAI
  
  constructor() {
    this.openai = new OpenAI({
      apiKey: process.env.OPENAI_API_KEY,
    })
  }
  
  async generateContent(
    options: GenerationOptions,
    userId?: string,
    sessionId?: string
  ): Promise<GenerationResult> {
    const startTime = Date.now()
    
    try {
      // Generate multiple variants with different approaches
      const variants = await Promise.all([
        this.generateCreativeVariant(options),
        this.generateAnalyticalVariant(options),
        this.generateBalancedVariant(options)
      ])
      
      // Calculate costs and tokens
      const totalTokens = variants.reduce((sum, v) => sum + v.tokensUsed, 0)
      const cost = estimateTokenCost('gpt-4o-mini-2024-07-18', totalTokens)
      const generationTime = Date.now() - startTime
      
      // REQUIRED: Track AI usage for admin monitoring
      await trackAIUsage({
        userId,
        sessionId,
        featureName: '[tool_name]_generation',
        promptName: 'content_creation',
        modelUsed: 'gpt-4o-mini-2024-07-18',
        provider: 'openai',
        tokensConsumed: totalTokens,
        costUsd: cost,
        responseTimeMs: generationTime,
        requestParams: options,
        requestSuccess: true,
        generatedPrompts: variants.map(v => v.content)
      })
      
      return {
        variants,
        analysis: this.analyzeVariants(variants),
        metadata: {
          totalTokens,
          cost,
          generationTime,
          model: 'gpt-4o-mini-2024-07-18'
        }
      }
    } catch (error) {
      // Track AI failures
      await trackAIUsage({
        userId,
        sessionId,
        featureName: '[tool_name]_generation',
        promptName: 'content_creation',
        modelUsed: 'gpt-4o-mini-2024-07-18',
        provider: 'openai',
        tokensConsumed: 0,
        costUsd: 0,
        responseTimeMs: Date.now() - startTime,
        requestParams: options,
        requestSuccess: false,
        errorMessage: error.message
      })
      throw error
    }
  }
}

4. Admin Management System

Every tool includes comprehensive admin capabilities:

Quality Control

  • Review generated content before making it public
  • Feature high-quality content for discovery
  • Set expiration dates for temporary content
  • Bulk operations for content management

Analytics & Performance

  • Track generation costs and token usage
  • Monitor user engagement and conversion rates
  • SEO performance metrics
  • A/B testing capabilities

Content Operations

  • Bulk generate content for specific themes/topics
  • Create curated collections and themed sets
  • Automated content quality scoring
  • Performance-based content ranking

5. Rate Limiting & Security

Standardized rate limiting across all tools:

// Rate limit configurations per tool
const RATE_LIMITS = {
  '[tool_name]_generation': {
    anonymous: 10,    // 10 generations per day
    authenticated: 100 // 100 generations per day
  },
  '[tool_name]_response': {
    anonymous: 5,     // 5 responses per day  
    authenticated: 50  // 50 responses per day
  }
}

Implementation Priorities

Phase 1: Romance & Love Cluster (Week 1-2)

SEO Priority: HIGH (41 total keyword impressions)

  • Romance Writing Prompts Generator
  • Love Story Ideas Generator
  • Romance Character Generator
  • Romance Dialogue Generator
  • Romance Conflict Generator

Phase 2: Family Storytelling Cluster (Week 3)

Conversion Priority: HIGH (Direct funnel to MyStoryFlow)

  • Family Storytelling Ideas Generator
  • Family Memory Prompts Generator
  • Family Character Profile Generator

Phase 3: Adventure & Mystery Cluster (Week 4-5)

SEO Priority: MEDIUM (40 total keyword impressions)

  • Adventure Story Ideas Generator
  • Mystery Writing Prompts Generator
  • Mystery Story Ideas Generator
  • Adventure Character Generator

Phase 4: Universal Tools (Week 6)

Growth Priority: MEDIUM (Foundational tools)

  • Horror Writing Prompts Generator
  • Comedy Story Ideas Generator
  • Story Plot Generator (All Genres)
  • Creative Writing Prompts Generator

SEO Implementation Strategy

All tools inherit the proven SEO patterns already implemented for Story Prompts, Book Blurbs, and Flashcards. The framework reuses existing SEO infrastructure with tool-specific optimizations.

Existing SEO Infrastructure

Database Schema (Already implemented):

-- All tools already have these SEO fields in their database tables
seo_title TEXT,
seo_description TEXT,
keywords TEXT[],
-- Plus tool-specific fields like target_audience, learning_objectives, etc.

Next.js Metadata Generation (Reference implementation):

// Pattern from /src/app/book-blurb/[shareCode]/page.tsx
export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
  const { shareCode } = await params
  
  // Fetch content from database
  const supabase = getSupabaseTools()
  const { data: content } = await supabase
    .from('tools_[tool_name]')
    .select('*')
    .eq('share_code', shareCode)
    .eq('is_public', true)
    .single()
  
  // Generate SEO-optimized metadata
  const seoTitle = content.seo_title || generateDefaultTitle(content)
  const seoDescription = content.seo_description || generateDefaultDescription(content)
  
  return {
    title: seoTitle,
    description: seoDescription,
    keywords: content.keywords || [],
    authors: [{ name: content.author_name }],
    openGraph: {
      title: seoTitle,
      description: seoDescription,
      type: 'article',
      url: `https://tools.mystoryflow.com/${toolName}/${shareCode}/`
    },
    twitter: {
      card: 'summary_large_image',
      title: seoTitle,
      description: seoDescription
    }
  }
}

AI-Generated SEO Metadata (Reference implementation):

// Pattern from existing tools - AI generates SEO metadata during content creation
interface SEOMetadata {
  seoTitle: string        // 50-60 chars with primary keyword
  seoDescription: string  // 150-160 chars with compelling CTA
  keywords: string[]      // 5-10 relevant search terms
  targetAudience: string  // Who the content is for
  estimatedUseTime: string // How long to engage with content
}
 
// Each tool's AI service includes SEO generation
export class [ToolName]AI {
  private generateSEOMetadata(content: any, options: GenerationOptions): SEOMetadata {
    // AI analyzes content and generates optimized SEO metadata
    // Uses tool-specific keyword targeting and audience optimization
  }
}

Tool-Specific SEO Configuration

Each tool targets specific keywords following the proven pattern:

// SEO targeting per tool (following existing pattern)
const TOOL_SEO_TARGETING = {
  'romance-writing-prompts': {
    primaryKeywords: ['romance writing prompts', 'love story ideas'],
    targetAudience: 'romance writers and creative writing enthusiasts',
    contentType: 'writing prompts',
    genre: 'romance'
  },
  'family-storytelling-ideas': {
    primaryKeywords: ['family storytelling ideas', 'family memory prompts'],
    targetAudience: 'families wanting to preserve memories',
    contentType: 'story ideas',
    genre: 'family stories'
  },
  'mystery-writing-prompts': {
    primaryKeywords: ['mystery writing prompts', 'detective story ideas'],
    targetAudience: 'mystery writers and thriller enthusiasts',
    contentType: 'writing prompts',
    genre: 'mystery'
  }
  // ... configuration for all 16 tools
}

URL Structure & Routing

Following the established pattern:

Domain Structure (Already implemented):
tools.mystoryflow.com/story-prompts/           ✅ Working
tools.mystoryflow.com/book-blurb/              ✅ Working
tools.mystoryflow.com/flashcards/              ✅ Working

New Tool Pattern:
tools.mystoryflow.com/[tool-name]/             - Main tool page
tools.mystoryflow.com/[tool-name]/[shareCode]/ - Individual content
tools.mystoryflow.com/[tool-name]/browse/      - Browse public content

Schema.org Structured Data

Reuse existing structured data patterns:

// Reference: Flashcards use LearningResource schema
// Story Prompts use CreativeWork schema
// Book Blurbs use Book/Review schema
 
const generateStructuredData = (toolName: string, content: any) => {
  switch (toolName) {
    case 'romance-writing-prompts':
      return {
        "@context": "https://schema.org",
        "@type": "CreativeWork",
        "name": content.seo_title,
        "description": content.seo_description,
        "genre": "Romance Writing",
        "keywords": content.keywords?.join(", "),
        "author": { "@type": "Organization", "name": "MyStoryFlow" }
      }
    case 'family-storytelling-ideas':
      return {
        "@context": "https://schema.org",
        "@type": "Article",
        "headline": content.seo_title,
        "description": content.seo_description,
        "articleSection": "Family Stories",
        "keywords": content.keywords?.join(", ")
      }
    // ... patterns for each tool type
  }
}

SEO Automation & Backfilling

Leverage existing automation:

# Existing script for SEO metadata backfilling
npm run backfill-seo-metadata
 
# Script processes all tools and generates missing metadata
# Reference: /apps/tools-app/scripts/backfill-seo-metadata.ts

Performance & Analytics

Inherit existing performance optimizations:

  • Next.js metadata caching ✅ Already implemented
  • Sitemap generation ✅ Already implemented
  • Robots.txt optimization ✅ Already implemented
  • Core Web Vitals optimization ✅ Already implemented

Implementation Checklist for New Tools

SEO Integration Checklist:

  • Add seo_title, seo_description, keywords fields to database table
  • Implement generateMetadata() function in page component
  • Add SEO metadata generation to AI service
  • Configure tool-specific keyword targeting
  • Add structured data markup for tool type
  • Test social media sharing (Open Graph/Twitter Cards)
  • Verify search engine indexing
  • Monitor organic traffic and rankings

Reference Files:

  • Database Schema: /lib/database/migrations/20250719_170000_create_story_prompt_responses.sql
  • Metadata Generation: /src/app/book-blurb/[shareCode]/page.tsx
  • AI SEO Integration: /src/lib/story-prompts-ai.ts
  • SEO Documentation: /docs/SEO_FEATURES.md

Cross-Tool Integration

Workflow Connections

Romance Ecosystem: Prompts → Characters → Dialogue → Conflicts → Complete Stories Family Ecosystem: Ideas → Memory Prompts → Character Profiles → MyStoryFlow Integration Adventure Ecosystem: Ideas → Characters → Plot Generator → Complete Adventures Mystery Ecosystem: Prompts → Ideas → Plot Generator → Complete Mysteries

Technical Integration

  • Shared user sessions across related tools
  • Cross-referencing between generated content
  • Workflow-based content suggestions
  • Unified analytics and user journey tracking
  • Cross-tool SEO link building and content recommendations

Success Metrics

Technical Metrics

  • Code Reusability: 80% shared codebase between similar tools
  • Performance: Under 500ms API response times
  • Reliability: 99.9% uptime for all tools
  • Cost Efficiency: Under $0.05 per generation average

Business Metrics

  • SEO Growth: Target keyword rankings in top 10
  • User Engagement: Over 60% of users try multiple tools
  • Conversion Rate: Over 15% progression to MyStoryFlow main app
  • Community Growth: Over 1000 public story responses per month

Quality Metrics

  • AI Confidence: Over 85% average confidence scores
  • User Satisfaction: Above 4.5/5 average ratings
  • Content Quality: Over 90% admin approval rate
  • Response Rate: Over 30% of prompts receive user responses

Next Steps

This framework ensures consistent, scalable, and high-quality implementation of all 16 tools while maximizing code reuse and maintaining excellent user experience.

ComponentsArchitecture Patterns & Best Practices