Skip to main content

​
System overview

LearnTerms is a SvelteKit application backed by Convex for data and server functions. Authentication flows through Clerk, source PDFs are stored in R2, hosting is handled by Vercel, and AI-assisted generation runs through a managed LearnTerms agent workflow. At a high level:
  • SvelteKit renders the app and route structure
  • Clerk manages sign-in and identity
  • Convex stores app data and powers mutations, queries, and actions
  • R2 stores Content Library source PDFs
  • The generation layer plans, drafts, checks, and records source-grounded question runs

​
Core data model

The schema is centered on structured academic content.

​
Academic hierarchy

  • school
  • cohort
  • semester
  • class
  • module
  • question
This hierarchy is what makes the app feel curriculum-aware. Classes belong to cohorts. Modules belong to classes. Questions belong to modules.

​
User and progress data

The users table stores identity and app-level metadata such as:
  • Clerk user ID
  • name, email, and image metadata
  • cohort assignment
  • role
  • denormalized progress stats
  • generation usage
  • PDF upload usage
User progress is tracked separately so LearnTerms can remember:
  • selected options
  • eliminated options
  • flags
  • module-level activity

​
Content and authoring data

Question and content authoring use several additional tables:
  • contentLib for uploaded source documents
  • page-aware extraction artifacts, search entries, and topic maps for processed documents
  • questionMedia for image attachments
  • tags and moduleTags for class-scoped grouping

​
Route structure

The route structure mirrors the product model:
  • /classes for the student dashboard and class selection
  • /classes/[classId]/modules/[moduleId] for module study
  • /classes/[classId]/tests/new for custom test creation
  • /admin and nested routes for admin workflows
  • /badges, /cohort, and /status for supporting product surfaces
This alignment is worth documenting because it helps contributors understand where a feature belongs before they edit either docs or code.

​
Authentication and protected areas

Clerk is wired into the SvelteKit server hooks. The app protects /admin routes by checking the authenticated user and then resolving their LearnTerms role from Convex. Unauthenticated users are redirected to sign in. Authenticated users need an allowed role to enter admin pages. Role documentation defines both policy and route access.

​
Source-document pipeline

Content Library PDFs upload to R2 and then move through four background stages:
  1. Stored
  2. Extracted
  3. Indexed
  4. Mapped
The current source-PDF limits are 30 MB and 150 pages. Extraction produces page-aware text and layout artifacts, indexing makes that content retrievable, and mapping creates reusable topics for Question Studio. Question images use a separate media workflow and remain attached to question records. The Content Library pipeline handles source PDFs.

​
Generation layer

Question Studio uses a centrally managed LearnTerms generation model. The curator interface exposes selected pages or topics, the Learn / Clinical / Critical thinking mix, focus notes, and the destination module. Each run stores durable job state, candidates, source citations, checks, activity, and usage telemetry. Selected candidates are saved to the module as drafts; publishing remains a separate editorial action.

​
Why this architecture matters for docs

The docs should reflect the actual boundaries in the codebase:
  • content creation is cohort-scoped
  • questions are module-scoped
  • admin access is role-gated
  • uploads and generation have explicit limits
  • student progress persists across sessions
Following those boundaries keeps the documentation aligned with the product.