LearnActively

LearnActively turns a topic into an active-learning session. You pick a topic and a starting level, and the app generates an introduction, an overview diagram, a cheatsheet, a concept roadmap, an explanation and practice activity for each roadmap node, flashcards, and a quiz. A tutor chat sits alongside to help when you get stuck.

It is built to make you work. Every artifact asks you to retrieve, apply, and correct, not just read.

The product spec lives in spec.md. It is the source of truth for scope, data contracts, and agent behavior. AGENT.md holds the working rules for coding agents. The tickets this version was built from, with their status and verification notes, are in docs/tickets/.

What the app does

/ Landing page

1. Pick a topic.
   • Search the catalog of 300 topics: 100 tech, plus science, math, business, economics, social science, philosophy, law, and accounting. Autocomplete shows up to 8 ranked matches.
   • Or browse by domain tab, grouped by subcategory.
   • Anything not in the catalog can be typed and started as a free-text topic.
2. Pick a starting level. Choose Total beginner, Intermediate, or Advanced / challenging. The level changes where the roadmap starts and how practice works:
   • Beginners start at foundations, with hints shown.
   • Intermediate learners get one review node, with hints on request.
   • Advanced learners skip foundations entirely and get a stretch goal.

The Archive sidebar lists past sessions. If no database is configured, the page falls back to free-text entry plus 12 example topics.

/learn/[sessionId] Learning workspace

Each session has its own URL, so refresh, back, and sharing all work.

• Left: Tutor chat.
  • Knows your topic, level, roadmap progress, and which roadmap node you have open.
  • Socratic by default: it asks what you tried and gives the smallest useful hint.
  • Gives a full solution only if you explicitly ask after attempting.
• Right: Workspace tabs.
  • Overview: introduction, key terms, misconceptions, and a generated SVG diagram.
  • Roadmap: an interactive concept tree. Click a node for its explanation (with a diagram), a retrieval prompt, the activity, hints, the solution, and Mark complete.
  • Cheatsheet: a dense, print-style reference.
  • Labs: every node's activity in one place. Each activity includes starter code (for programming topics), a self-check list, level-appropriate hints, and a solution.
  • Flashcards: flip cards for retrieval practice.
  • Quiz: one question at a time, multiple choice and fill-in-the-blank only. Grading is exact: case, spacing, and punctuation are ignored, but "not a left join" is marked wrong. You end with a score, weak areas, and the roadmap nodes to revisit.

Artifacts stream in as they are generated: introduction and cheatsheet first, then the roadmap, then node explanations and activities (4 nodes at a time), then flashcards and quiz. If one fails, it retries once automatically. If it still fails, the tab shows Couldn't generate this with a Retry button that regenerates only what is missing. No placeholder content is ever shown in place of real output.

An unknown session URL shows a "Session not found" page with a link back to /.

How practice adapts to the subject

The planner gives each session a practice mode. For catalog topics it comes from the topic's domain and kind; for free-text topics the model classifies it. The mode shapes the activities, flashcards, and quiz questions:

Subject	Practice mode	Example activity
Languages, frameworks, tools	code_lab	Write or fix code from starter code
Computing and AI concepts	design_trace	Trace an algorithm or justify a design
Math	worked_problem	Multi-step problem or proof step
Accounting	journal_calc	Record journal entries
Science	predict_explain	Predict an outcome, then explain why
Economics, social science	data_interpretation	Draw a conclusion from described data
Law	case_analysis	Analyze a fact pattern using IRAC (issue, rule, application, conclusion)
Business	scenario_decision	Write a decision memo with tradeoffs
Philosophy	argument_map	Map premises, then raise and answer an objection

Setup

Prerequisites

• Node.js 20 or newer (developed on Node 24)
• An OpenAI API key (required: the app does not generate anything without it)
• Optional: a Supabase project, for persistence and the topic catalog
• Optional: a Tavily API key, for web search on fast-changing topics

1. Install

npm install

2. Configure environment

Copy .env.example to .env (or .env.local) and fill it in:

# Required
OPENAI_API_KEY=sk-...

# Optional: persistence + topic catalog. Use the Supabase *pooled* Postgres connection string
# (Project Settings → Database → Connection pooling, port 6543), not the REST API URL.
DATABASE_URL=postgresql://postgres.<project-ref>:<password>@aws-0-<region>.pooler.supabase.com:6543/postgres

# Optional: web search for volatile topics (frameworks, AI, law, etc.)
TAVILY_API_KEY=tvly-...

# Optional: model overrides (defaults shown)
OPENAI_MODEL_FAST=gpt-4.1-mini
OPENAI_MODEL_STRUCTURED=gpt-4.1
OPENAI_MODEL_REASONING=gpt-5

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

Variable	Without it
OPENAI_API_KEY	Starting a session fails with "OPENAI_API_KEY is not configured" (HTTP 503).
DATABASE_URL	In-memory storage: sessions vanish on restart, and the landing page shows free text plus 12 examples instead of the catalog.
TAVILY_API_KEY	Volatile topics are generated without web sources.

NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY are listed in .env.example, but the app does not use them yet. All database access goes through Drizzle and DATABASE_URL.

3. Set up the database (only if using DATABASE_URL)

npm run db:migrate

This creates the tables and seeds the 300-topic catalog. The seed uses ON CONFLICT DO NOTHING, so it is safe to re-run.

After the first seed, Supabase is the source of truth for topics. Add or edit them in the Supabase dashboard. CHECK constraints keep domain, kind, and scope valid, and the landing page picks up changes within an hour.

4. Run

npm run dev

Open http://localhost:3000.

Scripts

Command	What it does
npm run dev	Start the dev server
npm run build / npm start	Production build / serve it
npm run lint	ESLint
npm run test	Unit tests (Vitest). Model calls are mocked; no keys or database needed.
npm run test:e2e	Browser tests (Playwright, desktop + mobile Chrome). Starts a dev server on port 3002.
npm run db:generate	Generate a migration after editing db/schema.ts
npm run db:migrate	Apply migrations to DATABASE_URL

Run the e2e suite with live services switched off, so it cannot write to your database or call OpenAI:

DATABASE_URL= OPENAI_API_KEY= TAVILY_API_KEY= npm run test:e2e

Playwright's browser needs a one-time npx playwright install chromium.

How it works

Landing (/)                     → POST /api/learn { topic, depth, topicId? }  → session created ("planning")
Workspace (/learn/:id)          → GET  /api/learn/:id                          → stored state
  if planning                   → GET  /api/learn/:id/stream (SSE)             → claims the session, runs the orchestrator
  if generating (another tab)   → polls GET /api/learn/:id every 3s
Retry button                    → POST /api/learn/:id/retry                    → requeues; stream regenerates only missing/failed artifacts
Quiz submit                     → POST /api/learn/:id/quiz                     → deterministic grading
Tutor chat                      → POST /api/chat { sessionId, nodeId?, messages }

• Generation runs once per session. The stream atomically moves a session from planning to generating. A second tab or a refresh polls instead of starting another run.
• Abandoned runs resume. A session left generating with no progress for 300s is requeued the next time it is opened. The orchestrator is resumable: it skips the planner if a plan exists and skips every artifact that is already ready.
• Agents (lib/ai/agents/*) produce Zod-validated JSON (lib/ai/schemas/*). Each agent's system prompt is composed in lib/ai/prompts.ts in this order: global rules, then the level rubric, then the practice-mode instructions, then the agent's own instructions.
• Model tiers:
  • fast: planner and SVG quality reviewer.
  • structured: all learner-facing content and the tutor.
  • reasoning: the overview SVG.

Key files

Path	Purpose
app/page.tsx, components/landing/topic-picker.tsx	Landing page: catalog search, domain tabs, level step
app/learn/[sessionId]/page.tsx, components/app-shell/learn-shell.tsx	Workspace shell: loading, streaming, polling, retry
components/workspace/workspace-tabs.tsx	Workspace tabs
lib/ai/orchestrator.ts	Resumable generation pipeline
lib/ai/prompts.ts	Learning context, level rubric, practice-mode instructions
lib/ai/practice-mode.ts	Practice modes and catalog → mode mapping
lib/ai/tutor.ts	Tutor context and replies
lib/quiz/grade.ts	Deterministic quiz grading
lib/topics.ts	Autocomplete ranking
db/schema.ts, db/repository.ts	Tables, session claiming, catalog queries, in-memory fallback
db/migrations/0003_seed_topics.sql	Initial 300-topic seed (generated from spec.md Appendix A)

Known limitations

• No authentication, rate limiting, or cross-session memory. Don't expose a deployment publicly without adding protection; every session costs OpenAI calls.
• Catalog search matches titles only, with no aliases: "JS" does not find "JavaScript".
• Quiz questions are multiple choice and fill-in-the-blank only. Activities are self-checked, not graded.
• Practice-mode adherence depends on the model. In testing, a beginner accounting activity came out as a true/false question rather than journal entries, and one advanced activity had no stretch goal.
• Sessions created before this version may have open-ended quiz questions. They are shown with the model answer but not scored.

Tech stack

Next.js 15 · React 19 · TypeScript · Tailwind CSS · Vercel AI SDK with OpenAI · Zod · Drizzle ORM · Supabase Postgres · Tavily · ReactFlow · Mermaid · KaTeX · Framer Motion · Vitest · Playwright