GrindUp LMS — Giovanni Braghieri

01 · Overview

GrindUp LMS is an open-source, production-ready learning platform I built and released under MIT. It supports multiple independent courses, AI-generated study plans, oral and written assessments, Stripe subscriptions, a teacher backoffice, and full English/Italian i18n — all on Supabase for auth, PostgreSQL, and Row Level Security.

It started as LitStudy, a literature-focused prototype for structured study paths and AI-assisted oral assessment; I evolved it into a general-purpose LMS that any subject can use. The typed content model from Phase 1 became a flexible Area → Subarea → Module hierarchy; persistence, billing, and multi-tenant access followed in Phase 2.

02 · Context

Literature teachers face a recurring gap: strong pedagogical material exists (biographies, themes, close reading), but it's scattered across PDFs, slides, and ad-hoc worksheets. Students need structure: what to study this week, how to practice orally, where they're weak. Teachers need a single place to host that journey.

Generic LMS platforms are built for video plus multiple choice. Literature teaching needs something different: author-centric navigation, work-level deep dives, visual concept maps, and practice that mirrors real oral exams. I built LitStudy as a purpose-built prototype to explore what that product could be, end to end — then generalized the architecture when I open-sourced it as GrindUp LMS.

03 · Problem

Content is hierarchical, but most tools are flat. Literature is Author → Works → Themes / Characters / Context. Without a model that reflects that, every feature becomes a one-off.

Oral assessment doesn't scale. Teachers can't give every student a full mock oral. Students need low-friction practice with feedback on clarity, coverage, and language.

Planning is disconnected from content. Exam dates and weekly tasks should tie back to the authors and works in the library, so the plan stays a real curriculum rather than a bare calendar.

Teachers need a system, not a pile of pages. Dashboard, content, assessment, and planning should feel like one product with consistent navigation and progress signals.

04 · What I built

Phase 1 — LitStudy prototype

LMS shell & navigation

A Next.js 15 App Router app with a persistent sidebar (Dashboard, Study Plan, Content, Assessment, Settings), responsive design, and a Radix + Tailwind component system.

Typed content layer

A structured model (lib/data.ts): authors with period and works; works with genre, themes, characters, symbols, conflicts, and context; slug-based resolvers that decouple routing from display strings.

Content library & deep-dive pages

Browseable author cards, author pages (key points, executive summary, interactive mind map + flashcards, works grid), and work pages with Mermaid diagrams and collapsible theme/character/symbol sections.

Study planning module

A questionnaire flow (exam date, self-assessed prep levels, preferred methods, focus areas) that generates a multi-week schedule with per-week focus, task checklists, and progress recalculation.

Assessment center

A three-tab hub: topic-based MCQ quizzes with difficulty and attempt tracking, an oral test, and a results view with score breakdowns and history.

AI oral assessment pipeline

POST /api/submit-audio validates the file, reconstructs a clean File for the OpenAI SDK, transcribes with Whisper, evaluates with GPT-4 on clarity / coverage / grammar, and returns structured JSON, with defensive error handling at each stage.

Content-derived learning tools

Mind maps generated programmatically from author data (configurable focus and detail), and flashcards auto-built from the same model, with no duplicate authoring.

Student dashboard

Progress overview, recent oral-assessment snapshots, pending tasks, performance aggregates, and quick links into assessment flows.

Phase 2 — Production platform

Supabase backend

Auth with email and Google OAuth, PostgreSQL persistence, and Row Level Security policies scoped to course and role.

Multi-course architecture

Independent courses, each with its own content hierarchy, enrollments, and settings — not a single hard-coded curriculum.

Content backoffice

Area → Subarea → Subsubarea → Module hierarchy for authoring; AI summaries, mind maps, and audio narration generated from module content.

Personalized study plans

AI-generated weekly schedules from student availability, exam dates, and progress — replacing the static questionnaire flow from the prototype.

Stripe billing

Recurring subscriptions with webhook-driven status updates — access gates tied to payment state, not manual flags.

Role-based access

Admin, Teacher, and Student roles with RLS policies — teachers manage their courses; students see only what they're enrolled in.

i18n

English and Italian, fully translatable UI and content hooks — built for European teacher-exam markets from the start.

Test suite

Vitest unit tests and Cypress e2e coverage for critical flows — study plans, assessments, auth, and backoffice paths.

05 · Product decisions

Single content model drives all features

One authors/works structure powers pages, flashcards, and mind maps, so teachers maintain a single source rather than three.

Author → Work routing with slugs

Clean, shareable URLs that are easy to extend with a CMS or database later.

Separate assessment center

Quizzes and oral practice are distinct modalities; tabbed UX keeps scope clear.

Oral = record → transcribe → evaluate

Mirrors the real exam flow and cleanly separates speech recognition from rubric scoring.

Three-dimension oral rubric

Clarity, coverage, and grammar map to how literature teachers actually grade oral responses.

Mermaid for mind maps

Diagrams stay in sync with structured data, with no manual image maintenance.

Prototype-first shell

Phase 1 shipped the full LMS UX on static data to validate flows before wiring Supabase — an intentional step, not a shortcut left unfinished.

Generalize beyond literature

The typed Author → Work model became a flexible Area → Subarea → Module hierarchy any subject can use, without rewriting assessment or planning features.

Supabase over static data

Persistence, auth, and RLS without a custom backend — Postgres policies enforce course boundaries instead of application-layer checks alone.

Platform code vs content

The repo ships the platform only; courses are seeded locally or authored via the backoffice — so forks aren't tied to my literature curriculum.

06 · Technical approach

Stack: Next.js 15, React 19, TypeScript, Tailwind, shadcn/ui, Supabase (Auth + Postgres + RLS), OpenAI (Whisper + GPT), Stripe, Vitest, Cypress. Typed content interfaces remain the contract between database rows, UI, and AI generators.

Next.js App Router (SSR + API routes)
   ├─► Supabase — auth (email + Google), PostgreSQL, RLS by role/course
   ├─► OpenAI API — Whisper transcription, GPT oral/written evaluation
   └─► Stripe — checkout, subscriptions, webhook → access status

content hierarchy (Area → Subarea → Module)
   ├─► student library + study plan UI
   ├─► teacher backoffice (authoring, AI summaries, mind maps, audio)
   └─► assessment center (MCQ + oral + results, persisted)

Phase 1 note: lib/data.ts static layer → migrated to Supabase in Phase 2

Server Components handle content-heavy pages; client components appear only where there's real interactivity (recording, quizzes, plan toggles, backoffice editors). The audio API uses staged validation with granular error responses. What started as "swap lib/data.ts for Supabase later" is done — persistence, quiz results, oral history, and dashboard metrics all read from Postgres with RLS. Stripe webhooks keep subscription state in sync without polling.

07 · Outcome

GrindUp LMS is open-sourced under MIT as a production-ready platform — not a demo scaffold. Others can fork it, connect their own Supabase project and Stripe account, and deploy a multi-course LMS with AI assessments and billing.

It delivers end-to-end content navigation, multi-modal assessment (MCQ + AI oral), AI study planning, teacher backoffice, role-based access, and subscription billing — on an architecture that grew honestly from a literature prototype. Source: github.com/gbrg15/lms-concorso-open.

There is no live public demo — running it requires self-hosted setup (Supabase + API keys). See the repo README for local and deploy instructions.

08 · Evolution to open source

Phase 1 was LitStudy: a literature-focused prototype to validate whether a typed content model, AI oral assessment, and study planning could feel like one coherent LMS — built on static data, with a credible product shell.

Phase 2 generalized that into GrindUp LMS: multi-course, Supabase-backed, Stripe-billed, with a teacher backoffice and i18n. I open-sourced it under MIT so other educators and builders can deploy their own instance without starting from a generic LMS template.

The LitStudy story is still the origin — the literature problem framing, the oral-assessment pipeline, and the content-derived mind maps all carry forward. What changed is scope: from one curriculum to a platform any course can plug into.