Course Planner - Key Decisions & Recommendations

🎯 Core Questions to Resolve

1. Separate Route vs. Integrated?

Option A: Separate Route (RECOMMENDED)

/admin/course-planner (new AI-powered creation)
/admin/catalog (existing manual creation)
/admin/courses/:id (existing course editor)

Pros: ✅ No risk of breaking existing functionality ✅ Can experiment freely ✅ Clear separation of concerns ✅ Easy to toggle features ✅ Different UX paradigm (conversational vs. form-based)

Cons: ❌ Two paths to create courses (could confuse users) ❌ Some code duplication

Option B: Integrated Add AI features to existing course editor

Pros: ✅ Single unified experience ✅ No duplication

Cons: ❌ High risk of breaking existing features ❌ Complex UI with many modes ❌ Harder to maintain

RECOMMENDATION: Option A (Separate Route)

Start with /admin/course-planner
Keep existing system intact
Merge later if successful

2. Which Research Tools to Use?

Comparison:

Tool	Purpose	Cost	Quality	Speed
Tavily API	Real-time search, academic papers	$50/mo	Excellent	Fast
Google Search	Broad coverage, trends	Free (Custom Search API)	Good	Fast
Firecrawl	Deep content extraction	$20/mo	Excellent	Medium
Perplexity API	AI-powered search & synthesis	$20/mo	Excellent	Fast
LLM Web Search	Built-in (Claude/GPT)	Included	Good	Fast

RECOMMENDED STACK:

Tier 1 (MVP):

✅ LLM with web search (Claude Opus 4.5 or GPT-4o)
- Cost: $0 extra (use existing OpenRouter)
- Quality: Very good
- Speed: Fast
- Coverage: Broad but not deep
✅ Tavily API
- Best for: Academic research, technical deep-dives
- Use when: Need authoritative sources
- Cost: $50/month

Tier 2 (Enhanced):

✅ Firecrawl
- Best for: Extracting full documentation, tutorials
- Use when: Need to analyze competitor courses in depth
- Cost: $20/month

Tier 3 (Advanced):

Google Custom Search API (free tier: 100 queries/day)
Perplexity API (for specialized research)

MVP RECOMMENDATION: Start with LLM web search + Tavily

Total cost: $50/month
Covers 90% of use cases
Add Firecrawl later if needed

3. Agent Framework: LangGraph vs. Claude SDK vs. Custom?

Option A: LangGraph

import { StateGraph } from "@langchain/langgraph";

const workflow = new StateGraph({
  channels: {
    research: null,
    outline: null,
    content: null
  }
})
  .addNode("research", researchAgent)
  .addNode("plan", planningAgent)
  .addNode("generate", contentAgent)
  .addEdge("research", "plan")
  .addEdge("plan", "generate");

Pros: ✅ Built for multi-step workflows ✅ State management included ✅ Visual debugging ✅ Tool integration

Cons: ❌ Learning curve ❌ Heavier dependency

Option B: Claude Agent SDK

import { Agent } from "@anthropic-ai/agent-sdk";

const courseAgent = new Agent({
  tools: [tavilyTool, firecrawlTool],
  model: "claude-opus-4-5"
});

const result = await courseAgent.run({
  instruction: "Research and plan a course on AI agents"
});

Pros: ✅ Native Claude integration ✅ Simple API ✅ Built for agentic workflows

Cons: ❌ Claude-specific (vendor lock-in) ❌ Less mature ecosystem

Option C: Custom Orchestration

// Simple sequential execution
async function createCourse(idea: string) {
  const researchBrief = await refineIdea(idea);
  const research = await conductResearch(researchBrief);
  const outline = await planCourse(research);
  const content = await generateContent(outline);
  return content;
}

Pros: ✅ Full control ✅ No dependencies ✅ Easy to understand

Cons: ❌ Manual state management ❌ No retry logic ❌ No visualization

RECOMMENDATION: Start Custom, Migrate to LangGraph

Phase 1 (MVP): Custom orchestration
- Simple linear workflow
- Fastest to build
- Easy to debug
Phase 2 (Scale): Migrate to LangGraph
- When you need: parallel execution, retries, complex branching
- LangGraph provides infrastructure

4. Content Generation Strategy

Option A: Sequential (One at a Time)

Research → Plan → Generate Lesson 1 → Generate Lesson 2 → ...

Pros: ✅ Simple to implement ✅ User sees progress ✅ Can stop anytime

Cons: ❌ Slow (20 lessons × 2 min = 40 minutes)

Option B: Batch Parallel

Research → Plan → [Generate all 20 lessons in parallel]

Pros: ✅ Fast (20 lessons in ~3 minutes) ✅ Efficient use of LLM API

Cons: ❌ All-or-nothing ❌ Harder to track progress

Option C: Hybrid (Recommended)

Research → Plan → Generate in batches of 5
Batch 1: Lessons 1-5  (parallel)
Batch 2: Lessons 6-10 (parallel)
...

Pros: ✅ Balance speed and control ✅ Clear progress indicators ✅ Can pause between batches

RECOMMENDATION: Hybrid Approach

Batch size: 5 lessons
Show progress per batch
Allow pause/resume

5. User Experience Flow

Recommended UX:

┌─────────────────────────────────────────────┐
│ Step 1: Tell Me About Your Course          │
├─────────────────────────────────────────────┤
│ What do you want to teach?                  │
│ ┌─────────────────────────────────────────┐ │
│ │ [Text input]                            │ │
│ └─────────────────────────────────────────┘ │
│                                             │
│ [Next: Let AI Refine This] ─────────────→  │
└─────────────────────────────────────────────┘

↓ AI asks clarifying questions ↓

┌─────────────────────────────────────────────┐
│ Step 2: AI Understanding Your Vision        │
├─────────────────────────────────────────────┤
│ Based on your input, I'll create a course: │
│                                             │
│ ✅ Title: "Building AI Agents with Claude" │
│ ✅ Audience: Intermediate developers       │
│ ✅ Duration: 12 hours                      │
│ ✅ Focus: Production-ready patterns        │
│                                             │
│ Does this match your vision?                │
│ [Yes, Research This] [No, Let Me Adjust]   │
└─────────────────────────────────────────────┘

↓ User confirms ↓

┌─────────────────────────────────────────────┐
│ Step 3: Research in Progress...             │
├─────────────────────────────────────────────┤
│ 🔍 Searching for: "AI agent best practices" │
│ ⏳ Found 24 articles...                     │
│ ⏳ Analyzing competitor courses...          │
│ ⏳ Extracting code examples...              │
│                                             │
│ [View Real-Time Findings]                   │
└─────────────────────────────────────────────┘

↓ Research complete ↓

┌─────────────────────────────────────────────┐
│ Step 4: Research Report Ready               │
├─────────────────────────────────────────────┤
│ ✅ Analyzed 24 sources                      │
│ ✅ Found 3 gaps in existing courses         │
│ ✅ Identified 5 key frameworks               │
│                                             │
│ [Read Full Report] [Skip to Planning]      │
└─────────────────────────────────────────────┘

↓ User reviews ↓

┌─────────────────────────────────────────────┐
│ Step 5: Proposed Course Outline            │
├─────────────────────────────────────────────┤
│ AI generated this structure:                │
│                                             │
│ Section 1: Agent Fundamentals (4 lessons)   │
│ Section 2: Tool Integration (5 lessons)     │
│ Section 3: Memory Systems (4 lessons)       │
│ ...                                         │
│                                             │
│ [Edit Outline] [Approve & Generate]        │
└─────────────────────────────────────────────┘

↓ User approves ↓

┌─────────────────────────────────────────────┐
│ Step 6: Generating Course Content          │
├─────────────────────────────────────────────┤
│ Progress: ████████░░░░ 40% (8/20 lessons)  │
│                                             │
│ ✅ Lesson 1: "What Are AI Agents?" (3.2k)  │
│ ✅ Lesson 2: "The Agent Loop" (2.8k)       │
│ ⏳ Lesson 9: "Tool Selection Strategies"   │
│                                             │
│ [Pause] [View Generated Content]           │
└─────────────────────────────────────────────┘

↓ Generation complete ↓

┌─────────────────────────────────────────────┐
│ 🎉 Course Created Successfully!             │
├─────────────────────────────────────────────┤
│ ✅ 20 lessons (45,000 words)                │
│ ✅ 15 video scripts                         │
│ ✅ 8 blog post drafts                       │
│ ✅ 25 exercises                             │
│                                             │
│ [View Course] [Generate More Content]      │
│ [Publish to Platform]                       │
└─────────────────────────────────────────────┘

6. Where to Store Generated Content?

Options:

A) Directly to Database (Recommended)

// As content is generated, save to Supabase
await supabase.from('nova_lessons').insert({
  title: generated.title,
  content: generated.content,
  // ...
});

Pros: ✅ Immediate persistence ✅ Can pause/resume ✅ No data loss

B) Staging Area First

// Save to temporary storage
await supabase.from('course_drafts').insert({
  course_id: draft.id,
  generated_content: JSON.stringify(allLessons)
});

// User reviews, then approves
await moveDraftToProduction(draft.id);

Pros: ✅ User can review before committing ✅ Can discard if unsatisfied ✅ Edit before publishing

RECOMMENDATION: Staging Area (Option B)

Create course_drafts table
User reviews generated content
One-click publish to main tables

🚀 Recommended Implementation Plan

Week 1: Foundation

Week 2: Research Integration

Sign up for Tavily API
Create research orchestrator
Build research report UI
Test research quality

Week 3: Planning Engine

Integrate course outline prompt
Build outline editor UI
Add edit/approval workflow
Test with real course ideas

Week 4: Content Generation

Batch lesson generator
Progress tracking UI
Staging area system
Review and publish flow

Week 5: Enhanced Features

Video script generation
Blog post generation
Code example extraction
Polish and testing

📊 Decision Summary

Decision	Recommendation	Rationale
Architecture	Separate route `/admin/course-planner`	Low risk, clean separation
Research Tools	LLM web search + Tavily	Best quality/cost ratio
Agent Framework	Custom → LangGraph	Start simple, scale up
Generation Strategy	Hybrid batching (5 at a time)	Balance speed and control
Storage	Staging area first	Review before commit
Cost	~$50-100/month	Scalable, affordable

🎯 Success Criteria

MVP (Week 4):

User enters course idea
AI refines to research prompt
System researches using Tavily
System generates course outline
System generates 5 sample lessons
User can review and publish

Full Release (Week 8):

Next Immediate Steps

Review this document - Confirm decisions
Set up Tavily account - Get API key
Create /admin/course-planner route - UI skeleton
Build ideation prompt - First component
Test manually - Validate quality

Ready to start building? 🚀

🎯 Core Questions to Resolve​

1. Separate Route vs. Integrated?​

2. Which Research Tools to Use?​

3. Agent Framework: LangGraph vs. Claude SDK vs. Custom?​

4. Content Generation Strategy​

5. User Experience Flow​

6. Where to Store Generated Content?​

🚀 Recommended Implementation Plan​

Week 1: Foundation​

Week 2: Research Integration​

Week 3: Planning Engine​

Week 4: Content Generation​

Week 5: Enhanced Features​

📊 Decision Summary​

🎯 Success Criteria​

Next Immediate Steps​