LearnRank

The SAT & ACT tutor's workspace — an AI-powered lesson and curriculum generator for micro-educators. LearnRank turns a short intake form into ready-to-teach lesson plans, activities, quizzes, rubrics, energizers, and analogies, with first-class support for Digital SAT and ACT question formats while still handling any standard you teach (Common Core, NGSS, and more).

The codebase identity remains lessonforge for historical/infra reasons; everything a user reads says LearnRank.

---

Why LearnRank

At the ~$20/mo price band of general AI assistants, "AI lesson generation" alone isn't a moat. LearnRank's defensible value is format specialization + workflow:

• Knows your formats — Digital SAT short single-question passages, ACT 5-choice math, and exact difficulty mixes computed in code (not left to the model to estimate).
• A real library — every generation is saved, versioned, searchable, exportable, and shareable. No re-specifying the same context to a chatbot every session.

Features

• Six content generators — lesson plans, activities, quizzes, rubrics, energizers (warm-ups), and analogies.
• SAT/ACT test formats — lesson plans can append practice-question blocks in Digital SAT or ACT format with a configurable count and difficulty mix.
• Structured AI output — generations are constrained to valid JSON via Claude structured outputs, with inline streamed progress and a non-blocking "your content is ready" notification.
• Block editor + version history — edit any content type, reorder sections, and restore earlier snapshots.
• Exports — Markdown, plain text, DOCX (Word), and PPTX (PowerPoint, with a preview modal).
• Public share links — read-only share pages with optional unbranded output for paid tiers.
• Credits & billing — Stripe-backed subscription tiers (Free / Starter / Pro) plus one-time credit top-up bundles; every generation costs 5 credits.
• Auth — email/password and Google OAuth via Supabase, with branded transactional emails and password reset.
• Installable PWA — installable on desktop and mobile with a branded offline shell.
• Failed-generation recovery — one-click retry or prefilled re-edit for any generation that didn't finish.
• Admin beta-feedback dashboard — a secret-gated results page with per-criterion scoring and triage state.

Tech Stack

Area	Technology
Framework	Next.js 16 (App Router) + React 19 + TypeScript
Styling	Tailwind CSS (@tailwindcss/typography), custom design system
Database & Auth	Supabase — PostgreSQL, Row-Level Security, SSR client
AI	Anthropic Claude via @anthropic-ai/sdk (claude-haiku-4-5), structured outputs
Payments	Stripe (subscriptions + one-time credit bundles)
Rate limiting	Upstash Redis + @upstash/ratelimit (sliding window)
Exports	docx (Word), pptxgenjs (PowerPoint), native Markdown
Math/markdown rendering	react-markdown, remark-gfm, remark-math, rehype-katex, katex
Background durability	@vercel/functions (waitUntil)
Testing	Jest + ts-jest (unit), Playwright (e2e)
Hosting	Vercel

Project Structure

src/
  app/                  # Next.js App Router pages & API routes
    api/                # generate-*, lessons, jobs, credits, webhooks/stripe, cron
    generate/           # one page per content type
    lessons/[id]/       # view + edit
    share/[token]/      # public read-only share page
    dashboard/ settings/ auth/ admin/
  components/           # TopNav, generators UI, editors, notifications, PWA install
  lib/
    supabase/           # browser, server, and middleware clients
    openrouter.ts       # shared Claude generation helper (generateWithFallback)
    generation-*.ts     # streaming, events, worker, schemas
    stripe.ts credits.ts rate-limit.ts ...
  types/lesson.ts       # shared TypeScript interfaces
supabase/
  schema.sql            # full schema
  migrations/           # incremental migrations (run manually in the SQL Editor)
  email-templates/      # branded auth emails
public/                 # PWA manifest, service worker, icons

Getting Started

Prerequisites

• Node.js 20+
• Accounts/keys for Supabase, Anthropic (Claude), Stripe (test mode), and Upstash Redis

Installation

git clone git@github.com:DVFZ/learn-rank.git
cd learn-rank
npm install

Environment variables

Create a .env.local in the project root (never commit it). Required keys:

# Supabase
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY=

# Claude (Anthropic)
CLAUDE_API_KEY=

# Rate limiting (use the FULL-ACCESS Upstash REST token, not the read-only one)
UPSTASH_REDIS_REST_URL=
UPSTASH_REDIS_REST_TOKEN=

# Stripe (test mode)
STRIPE_PUBLIC_KEY=
STRIPE_SECRET_KEY=
STRIPE_WEBHOOK_SECRET=
STRIPE_STARTER_PRICE_ID=
STRIPE_PRO_PRICE_ID=
STRIPE_CREDITS_SMALL_PRICE_ID=
STRIPE_CREDITS_MEDIUM_PRICE_ID=
STRIPE_CREDITS_LARGE_PRICE_ID=
NEXT_PUBLIC_STRIPE_CREDITS_SMALL_PRICE_ID=
NEXT_PUBLIC_STRIPE_CREDITS_MEDIUM_PRICE_ID=
NEXT_PUBLIC_STRIPE_CREDITS_LARGE_PRICE_ID=

# App
NEXT_PUBLIC_APP_URL=http://localhost:3000
CRON_SECRET=
ADMIN_SECRET=

Database setup

Supabase does not auto-run migrations. In the Supabase SQL Editor, run supabase/schema.sql, then each file in supabase/migrations/ in numeric order (or use the concatenated supabase/work-setup.sql).

Run the dev server

npm run dev

Open http://localhost:3000.

PWA note: the service worker and the in-app Install button only work in a production build. To test them, run npm run build && npm start (localhost counts as a secure context), not npm run dev.

Stripe webhooks (local)

stripe listen --forward-to localhost:3000/api/webhooks/stripe

Available Scripts

Script	Description
npm run dev	Start the dev server
npm run build	Production build
npm start	Serve the production build
npm run lint	ESLint (flat config)
npm test	Jest unit tests
npm run test:watch	Jest in watch mode
npm run test:e2e	Playwright end-to-end tests
npm run test:e2e:ui	Playwright in UI mode

Usage

1. Sign up / sign in (email + password or Google). New free accounts receive starter credits.
2. Pick a content type from the dashboard's + New content button.
3. Fill the intake form — subject, topic, grade level, and type-specific options (e.g. SAT/ACT format, practice count, difficulty mix).
4. Generate — watch inline streamed progress; a "ready" card appears when it finishes.
5. View, edit, version, export, or share the result from the lesson page.

Contributing

LearnRank is a closed, solo-developed project; external contributions are not currently accepted. For internal development:

• Work on master (no feature branches).
• Make surgical, in-scope changes only — don't refactor or rename outside the task.
• Keep comments sparse; only explain non-obvious code.
• Never commit .env.local or run git commit automatically — provide the commit message for review.
• Read CLAUDE.md (project rules) and DESIGN.md (design system) before making functional or visual changes.
• Run npm run lint and npm test before submitting changes.

License

Proprietary — © Digital Ventures FZ (DVFZ). All rights reserved. Not licensed for redistribution or reuse.