[1.2] AI Idea Validator

1. Front Matter

• Title: AI Idea Validator

• Author: Sean Patrick Caintic (scorevi)

• Reviewers: Joshua Tribiana Uriel, Krizha Onise Cortez (Joshua-Yel, armaminter)

• Created: February - March 2026

• Status: Approved

• References:

  • Issue: [1.2] AI Idea Validator #24

  • Milestone: [1] Diagnose (Project Setup)

2. Introduction & Goals

• Problem Summary: Creators need a way to validate their quest topics before investing time in content creation. The AI Idea Validator is a Gemini-powered system that assesses topic viability and generates structured curriculum outlines including conflict points, crisis scenarios, and recommendations—all importable into the Visual Canvas editor.

• Goals:

  • Provide AI-powered topic validation with viability scoring (0-100)

  • Generate structured curriculum outlines with modules

  • Identify conflict points and crisis scenarios for engagement

  • Enable direct import of AI output to Visual Canvas

  • Cache responses to reduce redundant API calls

  • Implement content safety filtering

• Non-Goals:

  • Real-time content generation during quest editing

  • AI-generated media assets (images, videos)

  • Automatic quest publishing without creator review

• Glossary:

  • Viability Score: 0-100 rating of topic's educational potential

  • Curriculum Module: A unit of learning content with duration estimate

  • Conflict Point: Branching decision point for learner engagement

  • Crisis Scenario: Assessment activity placed after specific modules

  • Canvas Metadata: React Flow nodes/edges JSON structure

3. High-Level Architecture

• System Diagram:

Data Flow: Input → Zod validation → Content safety check → Cache check → (miss) Gemini call → Parse structured JSON → Save response log → Save to idea_validations → Return result.

• Technologies Used:

  • Google Gemini Pro - AI topic validation and curriculum generation

  • Zod - Input/output schema validation

  • Supabase - Data persistence and caching

  • Clerk - Authentication (creator role)

  • React Flow - Canvas node conversion

4. Detailed Design & Implementation

• Data Model / Schema:

idea_validations Table:

Supporting Tables:

• gemini_cache - Response cache with 30-day TTL

• gemini_responses - Full audit log of all AI calls

• gemini_api_logs - Per-request usage and quota tracking

• gemini_pricing - Model pricing configuration

• gemini_config - Admin model configuration

• API Specification:

  • POST /api/ai/validate-idea - Validate topic and generate curriculum

    • Request: { topic: string (2-200 chars, required), context: string (max 2000), learningObjectives: string (max 2000), bypassCache: boolean, questMode: "linear" | "exploration" }

    • Response: { success: true, data: { viabilityScore, viabilityRationale, curriculumOutline, conflictPoints, crisisScenarios, recommendations }, error: null }

  • GET /api/ai/idea-validations - Get creator's validation history

  • GET /api/ai/active-model - Get active Gemini model info

• Error Codes:

  • 400 - Bad input / malformed JSON

  • 401 - Unauthorized / not authenticated

  • 422 - Content policy violation

  • 429 - Rate limit exceeded

  • 500 - AI parse failure / server error

  • 504 - Timeout

• Logic & Workflows:

Validation Flow:

1. Creator submits topic, context, and objectives

2. Zod validates input schema

3. Content safety layer filters (local + AI)

4. Cache check (SHA-256 key hash)

5. On miss: Gemini API call with structured output

6. Parse and validate response against output schema

7. Save to idea_validations and gemini_responses

8. Return validated result

Curriculum-to-Canvas Conversion:

• Start node (green) → Entry point

• Curriculum Module → quest-card content card

• Conflict Point → decision diamond for branching

• Crisis Scenario → activity assessment activity

• End node (red) → Completion point

Content Safety Layers:

• Layer 1 (Local): Zero-latency regex filter in Zod superRefine

• Layer 2 (AI): Gemini contextual analysis with evasion detection

• Key Files:

  • app/api/ai/validate-idea/route.ts - Main API endpoint

  • shared/schemas/ai-validator.schema.ts - Zod schemas

  • lib/ai/api-key-manager.ts - Gemini key management

  • lib/ai/cache.service.ts - Response caching

  • lib/ai/content-safety.service.ts - Safety filtering

  • lib/utils/curriculum-to-canvas.ts - Canvas converter

  • components/creator/AIValidator.tsx - Main UI component

5. Infrastructure & Operations

• Dependencies:

  • Google Gemini Pro - AI inference

  • Supabase - Data persistence, caching

  • Clerk - Authentication

• Monitoring & Alerting:

  • gemini_api_logs tracks per-request usage and quota

  • Circuit breaker: 3 consecutive AI failures → 5-minute local filter fallback

  • Response logger dual-sink: Supabase + local JSONL backup

• Deployment Plan:

  1. Run database migrations for all tables

  2. Configure Gemini API keys in environment

  3. Deploy API routes and UI components

  4. Verify cache and logging functionality

6. Testing & Quality Assurance

• Test Strategy:

  • Unit: Validator service (7 tests, mocked Gemini)

  • Integration: Real API calls (5 tests)

  • Structural: Request/response validation (~20 tests)

  • Unit: Content safety Zod integration

  • Unit: Local regex filter

• Known Limitations:

  • Gemini response quality varies by topic complexity

  • Cache invalidation is TTL-based only (no manual purge)

  • Content safety may have false positives on edge cases

7. Maintenance & Support

• Troubleshooting:

  • 422 Content Policy Error → Topic triggered safety filter; rephrase input

  • 504 Timeout → Gemini overloaded; retry or bypass cache

  • Cache not updating → Check gemini_cache TTL; use bypassCache: true

  • Empty curriculum → Topic too narrow; add more context

• Changelog:

  • 1.0 (Feb 2026): Initial implementation

  • 1.1 (Feb 2026): Added Quest Mode support (#285)

  • 1.2 (Feb 2026): Smart Merge & Error Feedback (#245)

Document Version

1.0 - Approved, Feature deployed to production, 02/18/2026