LearnActively

LearnActively is an AI-powered active-learning workspace built for the OpenAI hackathon. It turns any topic into a structured learning session with an introduction, visual overview, cheatsheet, concept roadmap, node-by-node explanations, practice activities, flashcards, and a quiz.

The goal is not to make learning passive. LearnActively uses OpenAI to generate material that makes learners retrieve, apply, and correct their understanding.

Demo Flow

Youtube Demo Video Here: https://youtu.be/zzGtWu65A1Q?si=VA5p5B1owcQPD4Vq

1. Enter a topic such as SQL joins, how transformers work, or photosynthesis.
2. Choose a learning depth: beginner, intermediate, or advanced.
3. The app creates a learning session and streams generated artifacts into the workspace.
4. Read the intro and cheatsheet while deeper artifacts continue generating.
5. Explore the concept roadmap, open each subtopic, complete activities, review flashcards, and take the quiz.

How This Project Uses OpenAI

OpenAI is the core generation layer for the product. The app uses the Vercel AI SDK with @ai-sdk/openai to call OpenAI models from the server.

1. Multi-Agent Learning Orchestration

The backend runs a learning orchestrator in lib/ai/orchestrator.ts. For each user topic, it coordinates specialized AI agents:

• plannerAgent creates a structured learning plan.
• introductionAgent generates the first explanation.
• visualExplainerAgent creates an overview visual artifact.
• cheatsheetAgent produces a compact reference guide.
• conceptTreeAgent builds the prerequisite roadmap.
• nodeExplanationAgent explains each roadmap node.
• activityAgent creates active-learning exercises.
• flashcardAgent creates retrieval-practice cards.
• quizAgent creates an assessment aligned to the roadmap.

Each agent is prompted to produce a specific learning artifact instead of a generic chat response.

2. Structured Outputs With Zod Validation

OpenAI responses are generated through generateObject from the AI SDK in lib/ai/generate.ts. Each artifact has a matching Zod schema in lib/ai/schemas.

This lets the app render AI output as real UI:

• ReactFlow roadmap nodes and edges
• Mermaid diagrams
• Quiz questions
• Flashcards
• Activity prompts
• Cheatsheet sections
• Stream events

The generated content is validated before being stored or displayed, which makes the product more reliable for a live demo.

3. Model Tiers

The app supports separate model settings for different generation jobs:

OPENAI_MODEL_FAST=gpt-4.1-mini
OPENAI_MODEL_REASONING=gpt-5
OPENAI_MODEL_STRUCTURED=gpt-4.1

Defaults are defined in lib/utils/env.ts. The planner and chatbot use the fast tier, while structured learning artifacts use the structured tier.

4. OpenAI-Powered Chat Support

The app also includes a support assistant in lib/ai/chatbot.ts, exposed through POST /api/chat. It uses OpenAI text generation to help users understand and navigate the LearnActively experience.

5. Search-Aware Generation

For current or fast-changing topics, the planner can decide to use Tavily search. Source notes are passed into OpenAI prompts so generated explanations can account for recent information instead of relying only on model knowledge.

For stable topics, the app skips web search and generates directly from the OpenAI model.

6. Resilient Fallbacks

If OPENAI_API_KEY is missing or a model call fails, the generation wrapper returns deterministic fallback artifacts. This keeps the demo usable locally while preserving the full OpenAI-powered path when credentials are configured.

Product Features

• Topic-to-session generation
• Beginner, intermediate, and advanced learning depths
• Streaming artifact updates with Server-Sent Events
• Interactive concept roadmap using ReactFlow
• Visual explanations with Mermaid and SVG overview artifacts
• Practice activities for each subtopic
• Flashcards for retrieval practice
• Quiz with feedback and weak-area recommendations
• Supabase/Postgres persistence through Drizzle ORM
• In-memory development fallback when DATABASE_URL is not configured

Tech Stack

• Next.js 15
• React 19
• TypeScript
• Tailwind CSS
• Vercel AI SDK
• OpenAI via @ai-sdk/openai
• Zod
• Drizzle ORM
• Supabase Postgres
• ReactFlow
• Mermaid
• KaTeX
• Framer Motion
• Vitest
• Playwright

Architecture

User topic
  -> POST /api/learn
  -> learning session is created
  -> GET /api/learn/:sessionId/stream
  -> runLearningOrchestrator()
  -> OpenAI-powered agents generate structured artifacts
  -> artifacts are validated with Zod
  -> artifacts are persisted with Drizzle
  -> Server-Sent Events stream updates to the UI
  -> learner interacts with roadmap, activities, flashcards, and quiz

Key Files

• lib/ai/generate.ts - OpenAI model wrapper for structured objects and text.
• lib/ai/orchestrator.ts - Coordinates the full learning generation workflow.
• lib/ai/agents/* - Specialized artifact-generation agents.
• lib/ai/schemas/* - Zod schemas for AI-generated outputs.
• app/api/learn/[sessionId]/stream/route.ts - SSE endpoint for streaming generation progress.
• app/api/chat/route.ts - OpenAI-powered support chat endpoint.
• components/workspace/workspace-tabs.tsx - Main artifact workspace UI.
• components/roadmap/concept-tree.tsx - Interactive learning roadmap.
• db/schema.ts - Drizzle database schema.

Environment Variables

Create a .env.local file:

OPENAI_API_KEY=your_openai_api_key
DATABASE_URL=your_supabase_postgres_connection_string
TAVILY_API_KEY=your_tavily_key

NEXT_PUBLIC_APP_NAME=LearnActively
NEXT_PUBLIC_APP_URL=http://localhost:3000

OPENAI_MODEL_FAST=gpt-4.1-mini
OPENAI_MODEL_REASONING=gpt-5
OPENAI_MODEL_STRUCTURED=gpt-4.1

OPENAI_API_KEY is required for the full OpenAI-powered experience. DATABASE_URL and TAVILY_API_KEY are optional for local demo usage because the app includes development fallbacks.

Run Locally

npm install
npm run dev

Open:

http://localhost:3000

Verification

npm run test
npm run build

Why It Matters

Most AI learning tools answer the question and stop. LearnActively uses OpenAI to transform a topic into a complete active-learning path: plan, explain, visualize, practice, retrieve, assess, and review weak areas.

The OpenAI integration is not just a chatbot layer. It is the generation engine for a structured educational workspace.