Rewrite lessons 1-4 against real code, and revise the plan

[ephbaum]

Lessons 1-4 are now written against code that exists and passes its tests, and the sixteen-lesson outline has been audited against that code.

The implementation is in ephbaum/elxrBB#1. Every command and snippet in these lessons was run, not assumed.

The lessons

Lesson 1 — Setting Up the Environment. Phoenix 1.8.13 on Elixir 1.20 / OTP 28. Uses the official elixir-lang install script, drops the Node.js step (1.8 builds assets with standalone esbuild and Tailwind binaries), and explains why the project is generated as elxrbb --module ElxrBB — an OTP application name cannot be mixed case, which is what the 2023 attempt tripped over.

Lesson 2 — User Accounts (renamed from "User Authentication with Pow"). Built on mix phx.gen.auth: scopes, magic links, sudo mode. Then elxrBB's own material — the username generator built from this repository's word lists, case-insensitive uniqueness via a functional index, and the profile form. The Pow draft is preserved in docs/archive/original-lessons/ for reference.

Lesson 3 — Forums, Topics and Replies. Replaces the planned flat /topics + /replies CRUD with the nested routes a forum actually needs. Covers the aggregate subquery that produces reply counts without an N+1 or a counter column, why route declaration order matters, why ownership is checked at mount and on save, and how a stream-backed list has to track its own count.

Lesson 4 — Threaded Replies, Sub-Topics and Voting (new; merges old lessons 4 and 5). The self-referencing foreign key and why depth is stored rather than derived, the check constraints that keep that denormalization honest, building a tree in two queries instead of one per level, and why sibling ordering needs an id tiebreak or the page reorders itself between renders. For voting: one table with two nullable targets and an exclusive-or check constraint, partial unique indexes and why they must be partial, and summing scores rather than keeping a counter column.

Each lesson calls out a bug hit while building it — the nil-intolerant String.trim/1 in update_change/3, the aggregate that loses its Ecto type crossing a subquery, a username generator that produced names its own schema rejected, and a duplicate DOM id the test suite caught. These are the parts a reader learns most from.

The plan audit

The original outline was drafted before any code existed. The spine holds — contexts, then the forum domain, then threading, moderation, deployment — but several specifics do not survive contact with the application. docs/00a-outline.md now carries the revised plan and a Revisions to this plan section explaining each change:

1. Lessons 4 and 5 were the same lesson. "Threaded replies" and "sub-topics" both describe a reply with a parent_id. Merged.
2. Real-time moved from lesson 11 to lesson 5, and changed technology. The plan reached for Phoenix Channels; a LiveView broadcasts over Phoenix.PubSub and receives in handle_info/2. Channels are for clients that are not LiveViews. Leaving it at 11 also means six lessons where a posted reply is invisible to everyone but its author.
3. Pagination and search were missing entirely. Every list query in the application is unbounded today — fine with five topics, an outage with fifty thousand, and the largest gap between finishing the tutorial and having a working forum. New lesson 6.
4. Testing moved earlier and narrowed. The application has had tests since lesson 2, so a lesson introducing testing at the end would describe a project that does not exist.
5. The animal-names lesson is dropped. Lesson 2 loads those word lists at compile time; putting them in a table and exposing them to JavaScript adds nothing. The JS-hook material moves to lesson 8, where a Markdown preview gives it a purpose.
6. Payments, SMS and browser push became appendices. A step needing a vendor account, a card and a public webhook endpoint is not one most readers can take. The roles and permissions work they were bundled with is real and stays, as lesson 9.

Also: old lesson 6 splits (profiles shipped in lesson 2; avatars and private messaging become lesson 7, with file storage behind a behaviour rather than one vendor named in the title), and rich text narrows to Markdown alone with sanitization as the point rather than a footnote.

Sixteen lessons became fifteen plus four optional appendices.

STATUS.md

Now reports lesson status and implementation status separately, and lists the application's known gaps — no pagination, no real-time, no search, plain-text bodies, unrestricted forum management, no rate limiting — so they read as scheduled rather than overlooked.

README

Gains a table of contents and a statement of what the stack actually is. The original account of the ChatGPT collaboration is kept intact, under "Where this came from".

🤖 Generated with Claude Code

https://claude.ai/code/session_01QKEb38aDmzRFVxFnM6Fe3X

---

Generated by Claude Code