Tools Infrastructure Architecture Overview

User Request
    ↓
Rate Limiter → Session validation, bot protection
    ↓
Tool Generator → Form processing, validation
    ↓
AI Service → OpenAI integration, content generation
    ↓
Admin Tracker → Usage logging, cost tracking
    ↓
Content Persistence → Database storage, share codes
    ↓
Share System → Public URLs, social sharing
    ↓
SEO Optimization → Meta tags, structured data
    ↓
Response Writer → User content creation
    ↓
Export System → Multi-format downloads
    ↓
Analytics Tracking → Conversion, performance metrics

CREATE TABLE IF NOT EXISTS tools_{tool_name} (
  -- Universal Identity
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  title TEXT NOT NULL,
  share_code TEXT UNIQUE NOT NULL,
  
  -- Ownership & Sessions  
  user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE,
  session_id TEXT NOT NULL,
  
  -- Visibility & Quality Control
  is_public BOOLEAN DEFAULT FALSE,
  is_featured BOOLEAN DEFAULT FALSE,
  is_reviewed BOOLEAN DEFAULT FALSE,
  
  -- Analytics & Performance
  view_count INTEGER DEFAULT 0,
  share_count INTEGER DEFAULT 0,
  export_count INTEGER DEFAULT 0,
  use_count INTEGER DEFAULT 0,
  rating_sum INTEGER DEFAULT 0,
  rating_count INTEGER DEFAULT 0,
  
  -- AI Integration & Cost Tracking
  ai_generation_prompt TEXT,
  ai_tokens_used INTEGER DEFAULT 0,
  ai_cost_cents INTEGER DEFAULT 0,
  ai_model TEXT DEFAULT 'gpt-4o-mini-2024-07-18',
  ai_generation_time_ms INTEGER,
  ai_confidence_score DECIMAL(3,2),
  
  -- SEO & Discovery
  seo_title TEXT,
  seo_description TEXT,
  keywords TEXT[] DEFAULT '{}',
  canonical_url TEXT,
  
  -- Content Storage (Tool-Specific)
  content JSONB NOT NULL,
  metadata JSONB DEFAULT '{}'::jsonb,
  
  -- Lifecycle Management
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW(),
  expires_at TIMESTAMPTZ,
  
  -- Indexes for Performance
  CONSTRAINT valid_rating_score CHECK (rating_sum >= 0 AND rating_count >= 0),
  CONSTRAINT valid_ai_confidence CHECK (ai_confidence_score >= 0 AND ai_confidence_score <= 1)
);
 
-- Universal Indexes
CREATE INDEX IF NOT EXISTS idx_tools_{tool_name}_share_code ON tools_{tool_name}(share_code);
CREATE INDEX IF NOT EXISTS idx_tools_{tool_name}_session ON tools_{tool_name}(session_id);
CREATE INDEX IF NOT EXISTS idx_tools_{tool_name}_public ON tools_{tool_name}(is_public) WHERE is_public = true;
CREATE INDEX IF NOT EXISTS idx_tools_{tool_name}_featured ON tools_{tool_name}(is_featured) WHERE is_featured = true;

CREATE TABLE IF NOT EXISTS tools_{tool_name}_responses (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  {tool_name}_id UUID REFERENCES tools_{tool_name}(id) ON DELETE CASCADE,
  
  user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE,
  session_id TEXT NOT NULL,
  
  title TEXT NOT NULL,
  content TEXT NOT NULL,
  word_count INTEGER GENERATED ALWAYS AS (array_length(string_to_array(content, ' '), 1)) STORED,
  
  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,
  
  seo_title TEXT,
  seo_description TEXT,
  
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

// Generation Endpoint
POST /api/{tool}/generate
{
  sessionId: string,
  options: ToolSpecificOptions,
  humanVerification?: string
}
 
// Browse/Filter Endpoint  
GET /api/{tool}?page=1&limit=20&filter[]=featured
{
  success: true,
  data: ToolContent[],
  pagination: PaginationMeta,
  filters: FilterOptions
}
 
// Sharing System
POST /api/{tool}/share
GET /api/{tool}/share/{shareCode}
PATCH /api/{tool}/share/{shareCode}
 
// User Responses
POST /api/{tool}/{id}/responses
GET /api/{tool}/responses/{responseId}
PATCH /api/{tool}/responses/{responseId}
 
// Export System
POST /api/{tool}/{id}/export
{
  format: 'json' | 'csv' | 'pdf' | 'html' | 'docx',
  options: ExportOptions
}

interface UniversalApiResponse<T = any> {
  success: boolean;
  data?: T;
  error?: {
    code: string;
    message: string;
    details?: any;
  };
  meta?: {
    timestamp: string;
    requestId: string;
    processingTime: number;
    remainingLimit?: number;
    conversionOpportunity?: boolean;
  };
}

{Tool}Landing.tsx
├── ToolHeader (brand, navigation)
├── ParameterForm (tool-specific inputs)
├── GenerationEngine (AI processing, results)
├── ResultsDisplay (content, analysis, actions)
└── ConversionFooter (CTA, social proof)

{Tool}Browse.tsx  
├── BrowseHeader (search, filters)
├── FeaturedContent (curated highlights)
├── ContentGrid (paginated results)
└── LoadMore (infinite scroll)

{Tool}Writer.tsx
├── WriterHeader (save, export, share)
├── RichTextEditor (content creation)
├── AutoSave (background persistence)
└── ExportOptions (multi-format output)

{Tool}PublicView.tsx
├── SEOOptimizedHeader (meta tags, structured data)
├── ContentDisplay (original prompt/content)
├── UserResponsesSection (community responses)
└── CTAFooter (try tool, create account)

class UniversalAIService {
  async generateContent<T>(
    toolName: string,
    options: GenerationOptions,
    sessionContext: SessionContext
  ): Promise<GenerationResult<T>> {
    
    // Retrieve stored prompts from admin database
    const prompt = await this.getStoredPrompt(toolName, options.variant)
    
    // Generate content with error handling
    const result = await this.callOpenAI(prompt, options)
    
    // Track usage with admin system
    await this.trackUsage(toolName, result.usage, sessionContext)
    
    // Generate multiple variants for A/B testing
    return this.createVariants(result)
  }
}

# Main App Database (for admin tracking)
NEXT_PUBLIC_SUPABASE_URL=https://main-app.supabase.co
SUPABASE_SERVICE_ROLE_KEY=service_role_key_not_service_key
 
# Tools Database (separate instance for isolation)
NEXT_PUBLIC_TOOLS_DATABASE_URL=https://tools.supabase.co
NEXT_PUBLIC_TOOLS_DATABASE_ANON_KEY=tools_anon_key
 
# AI Services
OPENAI_API_KEY=openai_key
 
# CORS & Sharing
NEXT_PUBLIC_TOOLS_APP_URL=https://tools.mystoryflow.com
WEB_APP_URL=https://mystoryflow.com

await trackAIUsage({
  sessionId,
  featureName: `[Tools] ${toolName}_generation`, // CRITICAL: [Tools] prefix
  promptName: `${toolName}_creation_v1`,
  modelUsed: getRecommendedToolsModel(), // gpt-4o-mini-2024-07-18
  provider: 'openai',
  tokensConsumed: result.usage.total_tokens,
  costUsd: calculateCost(result.usage),
  responseTimeMs: processingTime,
  requestSuccess: true,
  metadata: {
    toolType: toolName,
    userType: sessionContext.isAuthenticated ? 'registered' : 'anonymous',
    conversionOpportunity: shouldShowCTA(sessionContext)
  }
})

interface SEOMetadata {
  title: string;           // Tool-specific with keyword optimization
  description: string;     // 155-character optimized descriptions  
  keywords: string[];      // Primary + long-tail keywords
  canonicalUrl: string;    // Clean URL structure
  openGraph: {
    title: string;
    description: string;
    image: string;         // Auto-generated social images
    type: 'article';
  };
  structuredData: {
    '@type': 'SoftwareApplication';
    name: string;
    description: string;
    applicationCategory: 'BusinessApplication';
    operatingSystem: 'Web';
    // ... complete schema.org markup
  };
}