{"id":51243395,"url":"https://github.com/terencicp/react-saas-course","last_synced_at":"2026-06-29T02:03:21.295Z","repository":{"id":361825435,"uuid":"1232640830","full_name":"terencicp/react-saas-course","owner":"terencicp","description":"An in-depth web development course for junior devs; React 19 and Next.js 16, taught through web lessons with diagrams, exercises and Youtube videos.","archived":false,"fork":false,"pushed_at":"2026-06-23T20:08:28.000Z","size":47542,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-23T22:10:24.786Z","etag":null,"topics":["course","knowledge-extraction","personalized-education","web-development"],"latest_commit_sha":null,"homepage":"https://react-saas-course.pages.dev/","language":"MDX","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/terencicp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-08T06:05:30.000Z","updated_at":"2026-06-23T20:08:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/terencicp/react-saas-course","commit_stats":null,"previous_names":["terencicp/react-saas-course"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/terencicp/react-saas-course","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terencicp%2Freact-saas-course","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terencicp%2Freact-saas-course/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terencicp%2Freact-saas-course/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terencicp%2Freact-saas-course/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/terencicp","download_url":"https://codeload.github.com/terencicp/react-saas-course/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terencicp%2Freact-saas-course/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34910180,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-29T02:00:05.398Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["course","knowledge-extraction","personalized-education","web-development"],"created_at":"2026-06-29T02:03:18.655Z","updated_at":"2026-06-29T02:03:21.287Z","avatar_url":"https://github.com/terencicp.png","language":"MDX","funding_links":[],"categories":[],"sub_categories":[],"readme":"# A personalized course built using agentic workflows\n\n![A Claude prompt that reads \"Create a course: How to build a React SaaS app in 2026\"](documentation/readme-question.png)\n\nImagine an AI could take that one sentence, break it into a month of work, and actually do it — design the curriculum, write every lesson, build the interactive exercises, ship a working codebase for each project. This repository is that answer, run for real. Not a chatbot reply you read in thirty seconds, but the full thing an agent fleet produces when it's allowed to decompose the problem and grind on it chapter after chapter.\n\nA full-depth course on building a production SaaS with the minimum-viable 2026 stack, **designed and built for me — by me**, with Claude Code (Opus 4.8). I'm building it to learn from; the experiment is that I also engineered the agentic system that authors it. Authoring began May 2026.\n\n\u003e **Status: work in progress.** All 108 planned chapters are published. Built over ~5 weeks and ~760 commits so far (first commit 2026-05-08). Not yet deployed publicly.\n\n---\n\n## The course I couldn't find\n\nI just finished a Data Science degree and I'm moving into web development. I couldn't find a course pitched at the right altitude: everything for beginners assumes you've never written a function, and everything for experts assumes you already know the modern stack cold. So I built the one I wanted — senior-depth, decisions-before-syntax, and covering every layer a production SaaS actually ships: TypeScript, React 19, Next.js 16 (App Router, Server Components, PPR), Postgres + Drizzle, Better Auth, Stripe billing, transactional email, background jobs, file uploads, caching, rate limiting, i18n, testing, observability, CI/CD with zero-downtime migrations, and AI features over your own data.\n\nThe learner-facing overview lives on the site's landing page ([`src/content/docs/index.mdx`](src/content/docs/index.mdx)). This README is about the part underneath: how the course builds itself.\n\n## Three experiments\n\nBuilding it this way let me explore three things at once.\n\n### 1. Knowledge extraction\n\nWeb development is a sprawling field — countless libraries, frameworks, and competing ways to do everything. There's no shortage of tutorials; the work is deciding which small slice is actually worth learning. The course is an exercise in compression: distilling that sprawl down to the minimum viable stack a real SaaS ships today, and the reasoning behind each choice. The curriculum was derived top-down: pick the tech → define the audience and goals → draft the structure → break it into chapters, then lessons. Every paragraph and every code sample has to survive two filters: *does a 2026 SaaS dev actually use this, and does it teach the decision rather than just the syntax?*\n\n### 2. Personalized education\n\nThis course has exactly one student. It's tuned to where I am: adult tone, no bootcamp scaffolding, no \"what is a variable,\" skip-ahead self-checks when I already know something. It's also tuned to *how I learn*. Instead of static prose, it leans on a library of interactive components: in-browser code editors that run and grade my code, predict-the-output drills, PR-style code reviews, hover-to-define terms, and explorable diagrams. I'd rather have that than one more course built for everyone.\n\n### 3. Agentic engineering\n\nThe content is written by a fleet of agents; I designed the system that writes it. My job was the architecture — the pipeline, the contracts, the mechanisms that keep the agents from drifting. The rest of this README is about that system.\n\n## How I built it\n\nThe method, in order:\n\n1. **Decide the tech.** Pick the minimum-viable 2026 stack and fix it up front.\n2. **Define the audience and goals.** Who it's for, what \"done\" means.\n3. **Draft a high-level structure** — 22 units.\n4. **Break it down** — 108 chapters, then individual lessons.\n5. **Build the component library** — the interactive teaching primitives, first.\n6. **Define a canonical lesson structure** — so every lesson has the same skeleton.\n7. **Decompose authoring into specialized subagents** and add coherence mechanisms so the agents don't drift.\n8. **Write an orchestrator** that runs the right pipeline per chapter, **sequentially**, one chapter after the next, to keep the whole course internally consistent.\n\n## The authoring pipeline\n\nAn [orchestrator](documentation/chapter%20orchestrator%20prompts/Orchestrator.md) finds the next unwritten chapter, classifies it as a teaching chapter or a project chapter, routes it to the matching pipeline, builds the chapter end-to-end with no parallelism, commits, and moves on. The work is carried out by **32 specialized subagents** living in [`.claude/agents/`](.claude/agents), each doing one job. The two pipelines are diagrammed below, each at the end of its section — in both, a **square is a subagent** and a **rounded green box is a file** it reads or writes.\n\n### Teaching-chapter pipeline\n\nConcept lessons — prose, diagrams, exercises, and live coding. For each lesson, in order:\n\n| Step | Agent | Does |\n| --- | --- | --- |\n| 1 | `lesson-outliner` | Plans the pedagogy, sections, diagrams, and scope. |\n| 2 | `lesson-writer` | Writes the MDX prose with placeholders for interactive parts. |\n| 3 | `lesson-diagramer` (×n) | Replaces each diagram placeholder with a rendered diagram. |\n| 4 | `lesson-exerciser` (×n) | Replaces each exercise placeholder with a graded component or sandbox. |\n| 5 | `lesson-resourcer` | Adds vetted YouTube embeds and external-resource cards. |\n| 6 | `lesson-formatter` | Wires up component imports, tooltips, and code highlighting. |\n| 7 | `lesson-reviewer` | Audits pedagogy, facts, and cross-lesson coherence (reports only). |\n| 8 | `lesson-corrector` | Fixes the reviewer's findings surgically. |\n| 9 | `lesson-continuity` | Records what this lesson taught/cut/promised for later lessons. |\n\nThe chapter's final lesson is a quiz: `quiz-writer` extracts understanding-level questions from every lesson, then `quiz-coder` turns them into an interactive quiz.\n\n```mermaid\nflowchart TB\n    subgraph PL [for each lesson in chapter]\n        direction TB\n        subgraph t1 [draft]\n            direction LR\n            CO(chapter outline.md) --\u003e outliner[outliner] --\u003e LO(lesson-outline.md) --\u003e writer[writer] --\u003e MDX(lesson.mdx)\n        end\n        subgraph t2 [enrich and format]\n            direction LR\n            diagramer[\"diagramer\u003cbr/\u003e↻ per diagram\"] --\u003e exerciser[\"exerciser\u003cbr/\u003e↻ per exercise\"] --\u003e resourcer[resourcer] --\u003e formatter[formatter]\n        end\n        subgraph t3 [review and record]\n            direction LR\n            reviewer[reviewer] --\u003e corrector[corrector] --\u003e continuity[continuity] --\u003e CN(continuity notes.md)\n        end\n        t1 --\u003e t2 --\u003e t3\n    end\n    subgraph Q [chapter quiz]\n        direction LR\n        qwriter[quiz-writer] --\u003e qcoder[quiz-coder] --\u003e QMDX(quiz.mdx)\n    end\n    PL -. last lesson .-\u003e Q\n    classDef agent fill:#e0e7ff,stroke:#6366f1,color:#312e81;\n    classDef file fill:#dcfce7,stroke:#16a34a,color:#14532d;\n    class outliner,writer,diagramer,exerciser,resourcer,formatter,reviewer,corrector,continuity,qwriter,qcoder agent;\n    class CO,LO,MDX,CN,QMDX file;\n```\n\n**Coherence within the chapter.** Two mechanisms keep the lessons from contradicting or repeating each other:\n\n- **Continuity notes** — `lesson-continuity` keeps a per-chapter ledger of what each lesson taught, cut, promised, and the terminology it fixed. Every later `lesson-outliner` and `lesson-reviewer` reads it.\n- **Reviewer ⇄ corrector gate** — no lesson is finished until `lesson-reviewer` signs off on pedagogy, facts, and cross-lesson coherence, and `lesson-corrector` resolves the findings.\n\n### Project-chapter pipeline\n\nHands-on chapters where I build a real feature in a working codebase. Two phases.\n\n**Phase A — build the reference codebase (once):**\n\n| Step | Agent | Does |\n| --- | --- | --- |\n| 1 | `project-chapter-outline-lessons-aligner` | Reconciles the chapter outline with what the preceding teaching lessons actually delivered. |\n| 2 | `project-architect` | Designs the codebase and writes the plan that serves as the coding contract. |\n| 3 | `project-plan-verifier` | Compile-tests the plan's load-bearing choices before any code is written. |\n| 4 | `project-scaffolding-coder` | Scaffolds the app — dependencies, config, boilerplate. |\n| 5 | `project-slice-coder` (×n) | Implements the solution one feature slice at a time. |\n| 6 | `project-screenshotter` | Captures the UI screenshots the lessons reuse. |\n| 7 | `project-start-coder` | Derives my starter repo, with `TODO` stubs to fill in. |\n| 8 | `project-reviewer` ⇄ `project-corrector` | Reviews built code against the plan; corrector fixes the findings. |\n| 9 | `project-inspector` ⇄ `project-corrector` | Render-tests the running app; corrector fixes the defects. |\n| 10 | `project-approver` | Judges whether the project is good enough to learn from — rejection triggers a re-plan loop. |\n| 11 | `project-summarizer` | Produces a navigable codebase summary for the lesson agents. |\n| 12 | `project-chapter-outline-code-aligner` | Realigns the chapter outline to the code that actually got built. |\n\n**Phase B — write the lessons (per lesson):**\n\n| Step | Agent | Does |\n| --- | --- | --- |\n| 1 | `project-lesson-outliner` | Outlines the lesson (project overview / walkthrough / implementation). |\n| 2 | `project-lesson-test-coder` | For build-it-yourself lessons, writes the automated tests I code against. |\n| 3 | `project-lesson-writer` | Writes the lesson MDX from the outline and the working code. |\n| 4 | `lesson-diagramer` / `project-lesson-screenshotter` | Adds diagrams and embeds UI screenshots. |\n| 5 | `project-lesson-resourcer` | Adds supporting videos and external resources. |\n| 6 | `project-lesson-formatter` | Wires up components and finalizes formatting. |\n| 7 | `project-lesson-reviewer` ⇄ `project-lesson-corrector` | Reviews the lesson; corrector fixes the findings. |\n\n```mermaid\nflowchart TB\n    subgraph A [Phase A: build the codebase, once per chapter]\n        direction TB\n        subgraph pa1 [plan]\n            direction LR\n            CO(chapter outline.md) --\u003e aligner[lessons-aligner] --\u003e architect[architect] --\u003e PLAN(plan.md) --\u003e verifier[plan-verifier]\n        end\n        subgraph pa2 [build]\n            direction LR\n            scaffolder[scaffolding-coder] --\u003e slicer[\"slice-coder\u003cbr/\u003e↻ per slice\"] --\u003e shotter[screenshotter] --\u003e starter[start-coder]\n        end\n        subgraph pa3 [review and approve]\n            direction LR\n            reviewer[reviewer] --\u003e corrector[corrector] --\u003e inspector[inspector] --\u003e approver[approver]\n        end\n        subgraph pa4 [hand off]\n            direction LR\n            summarizer[summarizer] --\u003e SUM(code summary.md) --\u003e codeAligner[code-aligner]\n        end\n        pa1 --\u003e pa2 --\u003e pa3 --\u003e pa4\n        pa3 -. rejected, re-plan .-\u003e pa1\n    end\n    subgraph B [Phase B: write each lesson]\n        direction TB\n        subgraph pb1 [draft]\n            direction LR\n            SUMB(code summary.md) --\u003e loutliner[lesson-outliner] --\u003e LO(lesson-outline.md) --\u003e tcoder[test-coder] --\u003e TEST(Lesson Y.ts) --\u003e lwriter[lesson-writer] --\u003e MDX(lesson.mdx)\n        end\n        subgraph pb2 [enrich and format]\n            direction LR\n            ldiagramer[\"diagramer\u003cbr/\u003e↻ per diagram\"] --\u003e lshotter[screenshotter] --\u003e lresourcer[resourcer] --\u003e lformatter[formatter]\n        end\n        subgraph pb3 [review]\n            direction LR\n            lreviewer[reviewer] --\u003e lcorrector[corrector]\n        end\n        pb1 --\u003e pb2 --\u003e pb3\n    end\n    A --\u003e B\n    classDef agent fill:#e0e7ff,stroke:#6366f1,color:#312e81;\n    classDef file fill:#dcfce7,stroke:#16a34a,color:#14532d;\n    class aligner,architect,verifier,scaffolder,slicer,shotter,starter,reviewer,corrector,inspector,approver,summarizer,codeAligner,loutliner,tcoder,lwriter,ldiagramer,lshotter,lresourcer,lformatter,lreviewer,lcorrector agent;\n    class CO,PLAN,SUM,SUMB,LO,TEST,MDX file;\n```\n\n**Coherence across code and lessons.** This pipeline carries more risk — code and prose can drift apart — so it has more gates:\n\n- **Two outline aligners** — before coding, `...lessons-aligner` reconciles the outline with what earlier teaching chapters' continuity notes actually delivered; after coding, `...code-aligner` realigns it with the code that got built.\n- **Plan-as-contract** — the architect's plan pins stable selectors, locked decisions, and *falsifiable* rendered checks the app must pass.\n- **Per-lesson test files** — build-it-yourself lessons ship with real tests, so a lesson's promises are mechanically verified against my code.\n- **Layered review gates** — `reviewer ⇄ corrector`, then `inspector ⇄ corrector` on the running app, then a final `approver` that can send the whole chapter back for a re-plan.\n\n## The prose rewriting pipeline\n\nThe authoring pipelines above ship the whole course, first-draft prose included. Because that prose is AI-generated, it runs long and over-scaffolded. A separate pipeline goes back over every finished lesson to ready it for publication: a clarity-and-concision edit governed by a single [rewrite guide](documentation/rewriting/guidelines.md) — tighten the wording (typically ~30% shorter), cut scaffolding, hype, and out-of-scope detours, and fix any factual error, while leaving the curriculum, code, exercises, links, and diagrams untouched. Like the authoring orchestrator, it runs one chapter at a time, lesson by lesson, so terminology and cross-references stay consistent.\n\n| Agent | Does |\n| --- | --- |\n| `prose-chapter-rewrite-orchestrator` | Drives a chapter: rewrites each lesson in turn, then renames the chapter to a plainer title, realigns the table of contents, and commits. |\n| `prose-lesson-rewriter` | Rewrites one lesson end to end: triages and cuts whole sections, fans out a reviewer per surviving section, reassembles them, and rewrites the frontmatter. |\n| `prose-section-reviewer` (×n) | Proposes the tightened prose for one section — cutting, merging, and rewriting sentence by sentence then paragraph by paragraph against the guide. |\n| `prose-terminologist` | Checks every load-bearing term is defined once at first use, and records it in the course glossary. |\n\n```mermaid\nflowchart TB\n    orchestrator[chapter-orchestrator]\n    subgraph PL [for each lesson in chapter, in order]\n        direction TB\n        subgraph t1 [triage and cut sections]\n            direction LR\n            GUIDE(guidelines.md) --\u003e rewriter[lesson-rewriter]\n            MDX(lesson.mdx) --\u003e rewriter\n        end\n        subgraph t2 [rewrite every section, in parallel]\n            direction LR\n            reviewer[\"section-reviewer\u003cbr/\u003e↻ per section\"] --\u003e SECS(rewritten sections)\n        end\n        subgraph t3 [reassemble and finalize]\n            direction LR\n            assembler[lesson-rewriter] --\u003e terminologist[terminologist] --\u003e GLOSS(glossary.md)\n            terminologist --\u003e OUT(lesson.mdx ✎)\n        end\n        t1 --\u003e t2 --\u003e t3\n    end\n    orchestrator --\u003e PL --\u003e TOC(chapter title + Table of contents ✎)\n    classDef agent fill:#e0e7ff,stroke:#6366f1,color:#312e81;\n    classDef file fill:#dcfce7,stroke:#16a34a,color:#14532d;\n    class orchestrator,rewriter,reviewer,assembler,terminologist agent;\n    class GUIDE,MDX,SECS,GLOSS,OUT,TOC file;\n```\n\n**Keeping the rewrite faithful and consistent.** Four mechanisms hold the line:\n\n- **The rewrite guide** — [`documentation/rewriting/guidelines.md`](documentation/rewriting/guidelines.md) is the single contract every agent reads: name the mechanism not a metaphor, cut scaffolding and hype, define each term once, edit prose but never touch code, links, tests, or exercises.\n- **Word-count gate** — after each lesson the orchestrator strips code and measures the prose; if the rewrite isn't at least 25% shorter than the original, the lesson goes back for a second pass.\n- **Coherence pass** — because each section is rewritten by a different reviewer, the lesson-rewriter makes a final pass over the reassembled lesson to normalize titles and conventions across sections.\n- **Course glossary** — `prose-terminologist` records every load-bearing term and where it was first defined, so each term is introduced once and reused consistently across lessons.\n\n## The interactive stack\n\nThe site is an Astro + Starlight documentation app. Lessons are MDX, file-system-routed: every `NNN Chapter name` folder under `src/content/docs/` becomes a sidebar group. Most components are plain Astro (`.astro`), rendered to static HTML at build time; the genuinely interactive pieces drop down to React islands only where they need client-side state.\n\nThe teaching power comes from a custom library of **30+ pre-built components** (catalogued in [`documentation/components/INDEX.md`](documentation/components/INDEX.md)):\n\n- **In-browser code runtimes** — CodeMirror + `esbuild-wasm`, with PGlite (Postgres compiled to WASM) so SQL and Drizzle exercises run a real database in the browser. Variants cover SQL, Drizzle, React, Zod, and type-only TypeScript exercises, each auto-graded.\n- **Sandboxes \u0026 embeds** — StackBlitz, CodeSandbox, and in-page Sandpack for live, editable projects.\n- **Diagrams** — Mermaid and D2, both rendered at build time and themed for light/dark. A set of [diagram-engine guides](documentation/diagrams/INDEX.md) steers the diagram-building agents: which engine to pick for each kind of diagram, and the specific pitfalls of each.\n- **Drills \u0026 figures** — predict-the-output, PR-style code review, matching, classification, scrubbable request traces, state-machine walkers, and more.\n- **Code display** — Expressive Code with stepped, annotated walkthroughs and hover-to-define terms.\n\nOpen-ended answers and code reviews are graded through OpenRouter using the reader's own API key (BYOK), shared with the in-page AI chat — so feedback works without a backend.\n\n## Repository layout\n\n```\nsrc/\n  content/docs/      the lessons (MDX), one folder per chapter\n  components/        the interactive component library (figures, exercises, live-coding, embeds…)\ndocumentation/       the \"authoring brain\"\n  content/                        unit/chapter/lesson outlines + continuity notes\n  pedagogical approach/           the teaching guidelines every agent follows\n  code standards/                 canonical code conventions for projects and samples\n  components/ · diagrams/         component API and diagram-engine indices\n.claude/\n  prompts/chapter authoring/      the orchestrator + the two pipeline definitions\n  agents/                         the 32 authoring subagents (lesson/ and project/)\n```\n\nThe per-chapter project codebases — each chapter's `start/` and `solution/` — live in a companion repo: [`react-saas-course-projects`](https://github.com/terencicp/react-saas-course-projects).\n\n## Run it locally\n\nRequires Node 24+. The dev server wraps `astro dev` with a watcher that restarts on lesson add/delete (Astro's content loader doesn't reconcile those over HMR).\n\n```bash\nnpm install\nnpm run dev      # http://localhost:4321\nnpm run build    # static production build\nnpm run preview  # preview the production build\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fterencicp%2Freact-saas-course","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fterencicp%2Freact-saas-course","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fterencicp%2Freact-saas-course/lists"}