|
| 1 | +# Learning Hub Revamp Plan |
| 2 | + |
| 3 | +## Your question: JSON vs Markdown/README, which is better? |
| 4 | + |
| 5 | +Short answer: **keep JSON as the source of truth, but render rich content inside it.** Do not migrate wholesale to `.md` files. Here is why. |
| 6 | + |
| 7 | +### Why raw markdown is NOT the right move |
| 8 | +Current lesson files (e.g. [html-fundamentals.json](client/src/module/student/html/data/lessons/html-fundamentals.json)) are structured records with typed fields: `id`, `sectionId`, `orderIndex`, `difficulty`, `isInterviewQuestion`, `concepts`, `content.explanation`, `content.codeExamples[]`, `notes`, `commonPitfalls`, etc. The app relies on this shape for: |
| 9 | + |
| 10 | +1. Progress tracking per `id` |
| 11 | +2. Filtering (interview questions, difficulty, concepts) |
| 12 | +3. Ordering via `orderIndex` |
| 13 | +4. Rendering code examples with separate `code`, `output`, `explanation` blocks |
| 14 | +5. Future features like search, bookmarking, quizzes, XP |
| 15 | + |
| 16 | +Raw markdown throws all of that away. You would have to parse frontmatter and custom fences back out of the `.md`, which is strictly worse than just reading a field. Markdown is great for prose, bad for structured learning content. |
| 17 | + |
| 18 | +### The real problem |
| 19 | +The real problem is not the format, it is that **the `explanation` field is one giant wall of text** rendered as plain paragraphs. Whether that text lives in JSON or MD, it still looks boring. The fix is on the render side. |
| 20 | + |
| 21 | +### Recommended approach: hybrid |
| 22 | +- Keep the JSON schema. |
| 23 | +- Allow the `explanation` field (and notes, pitfalls) to contain **markdown + custom directives**. Render it with `react-markdown` + `remark-gfm` + `rehype-highlight`. |
| 24 | +- Add new optional fields to the JSON schema for rich blocks: `diagrams`, `flowcharts`, `interactiveDemos`, `quiz`, `visualizations`. |
| 25 | +- Render each block with a dedicated component. |
| 26 | + |
| 27 | +This gives you the "write like markdown" ergonomics for authors, and the structured metadata for the app. |
| 28 | + |
| 29 | +--- |
| 30 | + |
| 31 | +## Phase 1: Make existing content visually engaging |
| 32 | + |
| 33 | +### 1.1 Markdown rendering inside lessons |
| 34 | +- Install `react-markdown`, `remark-gfm`, `rehype-highlight`, `rehype-raw`. |
| 35 | +- Create [LessonContent.tsx](client/src/components/learn/LessonContent.tsx) that accepts the `content` object and renders explanation as markdown. |
| 36 | +- Support GitHub-style tables, task lists, callouts (`> [!NOTE]`, `> [!WARNING]`). |
| 37 | +- Style with Tailwind `prose` equivalent (use `@tailwindcss/typography` or hand-rolled since we are on TW v4). |
| 38 | + |
| 39 | +### 1.2 Diagrams and flowcharts (Mermaid) |
| 40 | +- Install `mermaid`. |
| 41 | +- Add a `Mermaid` renderer that lazy-loads and renders any ` ```mermaid ` code fence. |
| 42 | +- Add an optional `diagrams: [{ title, mermaid }]` array to the lesson JSON. Example use cases: |
| 43 | + - HTML rendering pipeline: `Browser -> HTTP -> Server -> HTML -> DOM -> CSSOM -> Render Tree -> Paint` |
| 44 | + - React lifecycle |
| 45 | + - Express middleware chain |
| 46 | + - SQL query execution order |
| 47 | + |
| 48 | +### 1.3 Charts (Recharts, already likely in deps) |
| 49 | +- Add optional `charts: [{ type: 'bar'|'line'|'pie', title, data }]` to JSON. |
| 50 | +- Useful for: time complexity comparisons, language popularity, framework benchmarks, aptitude answer distributions. |
| 51 | + |
| 52 | +### 1.4 Syntax-highlighted code with tabs |
| 53 | +- Upgrade `codeExamples` rendering to use Shiki or `rehype-highlight` with a copy button, line numbers, and a tabs UI when a lesson has multiple examples. |
| 54 | +- Add a "Run" button for JS/HTML/CSS examples via Sandpack (`@codesandbox/sandpack-react`). Instant interactive playground, zero backend. |
| 55 | + |
| 56 | +### 1.5 Callout cards |
| 57 | +- Replace the plain `notes` and `commonPitfalls` lists with colored callout cards (info, warning, tip, danger). Icon + border, not pill badges (per CLAUDE.md rules). |
| 58 | + |
| 59 | +--- |
| 60 | + |
| 61 | +## Phase 2: New interactive features |
| 62 | + |
| 63 | +### 2.1 Inline quizzes per lesson |
| 64 | +- Add `quiz: [{ question, options[], correctIndex, explanation }]` to JSON. |
| 65 | +- Render as a card after the lesson. Track correct/incorrect per user in localStorage first, then persist to server. |
| 66 | +- Award XP for first-try correct answers. |
| 67 | + |
| 68 | +### 2.2 Flashcards (spaced repetition lite) |
| 69 | +- Auto-generate flashcards from the `concepts` array + a new `definitions` map. |
| 70 | +- Simple SM-2 style review queue. Daily review streak. |
| 71 | + |
| 72 | +### 2.3 Progress, XP and streaks |
| 73 | +- Per-lesson progress: `not-started | in-progress | completed`. |
| 74 | +- Daily streak counter on the Learning Hub landing page. |
| 75 | +- XP bar, level up, badges for: "Finished HTML track", "10-day streak", "50 interview questions answered". |
| 76 | + |
| 77 | +### 2.4 TCS / exam question bank |
| 78 | +- Create [examData/](client/src/module/student/aptitude/data/exams/) with folders per exam: `tcs-nqt`, `infosys`, `wipro`, `accenture`, `capgemini`, `cognizant`. |
| 79 | +- Each JSON file: `{ exam, year, section, questions: [{ id, type, question, options, correctIndex, explanation, difficulty, topic }] }`. |
| 80 | +- New route `/student/exam-prep/:exam` with: |
| 81 | + - Topic-wise practice |
| 82 | + - Timed full mock tests with section timers matching real patterns (e.g. TCS NQT: Numerical 25m, Verbal 25m, Reasoning 25m, Coding 45m) |
| 83 | + - Score report with topic breakdown |
| 84 | + - Leaderboard (optional) |
| 85 | +- Mark questions with `isInterviewQuestion: true` to reuse the existing filter on the Learning Hub. |
| 86 | + |
| 87 | +### 2.5 Daily challenge |
| 88 | +- One curated question per day on the Learning Hub home. MCQ, code, or debug-the-snippet. Mixed across tracks. |
| 89 | +- "Maintain your streak" CTA. |
| 90 | + |
| 91 | +### 2.6 Code playground lessons |
| 92 | +- For JS / Python / SQL: embed Sandpack or Pyodide or sql.js so the learner can edit and run the example in place. |
| 93 | +- Add `playground: { language, starter, solution, tests }` to JSON. Auto-grade with tests. |
| 94 | + |
| 95 | +### 2.7 Visual concept maps |
| 96 | +- Each track gets a clickable concept-map landing page (React Flow). Nodes are lessons, edges are prerequisites. Clearly shows progress (completed nodes turn green). |
| 97 | +- Install `reactflow`. |
| 98 | + |
| 99 | +### 2.8 AI tutor per lesson |
| 100 | +- "Ask about this lesson" button. Sends lesson content + user question to Gemini (`gemini-2.5-flash-lite` per CLAUDE.md). Server endpoint under `learn-chat/` module mirroring the existing module pattern. |
| 101 | +- Rate-limit via `usageLimit` middleware, reuse an existing UsageAction (per CLAUDE.md: do not add new enum values). |
| 102 | + |
| 103 | +### 2.9 Notes and bookmarks |
| 104 | +- Per-user notes per lesson, stored server-side. Bookmark important lessons. Export notes as markdown. |
| 105 | + |
| 106 | +### 2.10 Community answers on interview questions |
| 107 | +- For lessons where `isInterviewQuestion: true`, let students post their own answers, upvote, and see a "top answer". Moderated by admin. |
| 108 | + |
| 109 | +--- |
| 110 | + |
| 111 | +## Phase 3: Engagement and retention |
| 112 | + |
| 113 | +- **Weekly learning digest email** using the existing broadcast email infra (recent commits show it exists). |
| 114 | +- **Certificates** on track completion, PDF generated server-side, shareable link. |
| 115 | +- **Study groups**: students join a track cohort, shared progress wall. |
| 116 | +- **Compare with friends**: opt-in progress sharing. |
| 117 | +- **Push notifications** via web push for daily challenge and streak reminders. |
| 118 | + |
| 119 | +--- |
| 120 | + |
| 121 | +## Proposed JSON schema additions (non-breaking) |
| 122 | + |
| 123 | +```ts |
| 124 | +type LessonContent = { |
| 125 | + explanation: string; // now: markdown, not plain text |
| 126 | + codeExamples?: CodeExample[]; |
| 127 | + notes?: string[]; |
| 128 | + commonPitfalls?: string[]; |
| 129 | + |
| 130 | + // NEW optional blocks |
| 131 | + diagrams?: { title: string; mermaid: string; caption?: string }[]; |
| 132 | + charts?: { title: string; type: "bar" | "line" | "pie"; data: any }[]; |
| 133 | + quiz?: { question: string; options: string[]; correctIndex: number; explanation: string }[]; |
| 134 | + playground?: { language: "js" | "html" | "python" | "sql"; starter: string; solution?: string; tests?: string }; |
| 135 | + keyTakeaways?: string[]; // rendered as a highlighted summary card |
| 136 | + furtherReading?: { title: string; url: string }[]; |
| 137 | +}; |
| 138 | +``` |
| 139 | + |
| 140 | +All new fields optional, so existing lessons keep working. |
| 141 | + |
| 142 | +--- |
| 143 | + |
| 144 | +## Implementation order (recommended) |
| 145 | + |
| 146 | +1. Markdown rendering + callouts + code copy button. Biggest visual win, smallest effort. |
| 147 | +2. Mermaid diagrams. Add 2-3 diagrams to HTML and JS fundamentals as proof. |
| 148 | +3. Inline quiz component + quiz data for one track. |
| 149 | +4. Sandpack playground for JS basics. |
| 150 | +5. XP, streak, daily challenge on the Learning Hub home. |
| 151 | +6. TCS / company exam module. |
| 152 | +7. React Flow concept maps per track. |
| 153 | +8. AI tutor endpoint. |
| 154 | +9. Flashcards and spaced repetition. |
| 155 | +10. Certificates and weekly digest. |
| 156 | + |
| 157 | +--- |
| 158 | + |
| 159 | +## Files that will change |
| 160 | + |
| 161 | +- [client/src/module/student/learn/LearnHubPage.tsx](client/src/module/student/learn/LearnHubPage.tsx): add daily challenge, streak, XP widgets. |
| 162 | +- New: [client/src/components/learn/](client/src/components/learn/) folder with `LessonContent.tsx`, `Mermaid.tsx`, `Quiz.tsx`, `Playground.tsx`, `Callout.tsx`, `ConceptMap.tsx`. |
| 163 | +- Each track's lesson renderer page (e.g. [DataAnalyticsLessonsPage.tsx](client/src/module/student/data-analytics/DataAnalyticsLessonsPage.tsx)) swaps its current text renderer for `<LessonContent content={lesson.content} />`. |
| 164 | +- New server module: `server/src/modules/learn-progress/` for XP, streaks, bookmarks, notes. Follows the routes/controller/service/validation pattern from CLAUDE.md. |
| 165 | +- New server module: `server/src/modules/learn-chat/` for AI tutor. |
| 166 | +- Prisma: new models `LessonProgress`, `LessonNote`, `LessonBookmark`, `QuizAttempt`, `DailyChallenge`, `UserStreak`. Confirm before creating migrations (per CLAUDE.md). |
| 167 | + |
| 168 | +--- |
| 169 | + |
| 170 | +## TL;DR |
| 171 | + |
| 172 | +Do not convert JSON to markdown files. Instead, let the `explanation` field contain markdown, render it richly, and add optional structured fields for diagrams, quizzes, playgrounds, and charts. Then layer on gamification (XP, streaks, daily challenge), a TCS/company exam bank, an AI tutor, and React Flow concept maps. That is what will actually bring students back, not a file-format swap. |
0 commit comments