App Flow

This document follows one visitor through the site and names every decision point. The canonical path is entry → hero → path → series → chapter → lab → quiz → progress → comment. Real visitors skip around; each step is designed to work as an entry point in its own right because search and shared links land people deep in the site.

/                      home: TOTP hero, new this week, continue, paths, library preview
/paths/$role           backend | security | sre — ordered chapter sequence
/library               all series, topic chips, live search
/series/$slug          chapter list + prerequisite graph
/series/$slug/$chapter prose, diagrams, playgrounds, diffs, lab, quiz, discussion
/lab                   index of the four modules
/lab/$module           totp | attack | webauthn | policy
/docs, /docs/$doc      the six project documents

1 · Entry

Most first visits arrive from a search result or a shared link to a chapter. The server renders full content, so the chapter is readable before scripts load; playgrounds, labs and the TOTP card appear as quiet skeletons and hydrate in place. Visitors who arrive at the root see the hero.

2 · Hero

The hero does one job: prove the site is a lab. Within a second of load the TOTP card shows a base32 secret and a six-digit code with a ring counting down. Nothing is sent anywhere; the secret is generated in the browser and discarded on reload. The two calls to action split the audience. “Enter the lab” goes to the cryptography series for people who want to start at the beginning. “Browse series” goes to the library for people who know what they are looking for. Returning visitors with progress also see “Continue learning”, which links directly to their next unfinished chapter.

3 · Path

Three role cards — Backend engineer, Security engineer, SRE — each open a path page listing a filtered sequence of chapters from the series whose topics match the role. Paths do not have their own progress; they reuse chapter completion, so finishing a chapter from any route advances every path that contains it. A path page links each chapter directly and shows which are done.

4 · Series

The series page shows level, blurb, the ordered chapter list with gold checks for completed chapters, and the prerequisite graph. Hovering a node highlights its full chain of ancestors; clicking a node navigates to that series. A visitor who opens series 6 sees that it rests on series 4, which rests on 1 and 3, and can decide whether to step back.

5 · Chapter

On wide screens the chapter page has three columns: the series checklist on the left, prose at about 68 characters per line in the centre, and a table of contents with scroll-spy on the right. On narrow screens the side columns collapse and the prose takes the full width. Within the prose the visitor meets diagrams, attacker/defender panels, risk tables, code, playgrounds and diff widgets in the order the argument needs them.

6 · Lab

Four chapters embed a full lab module: HOTP from the RFC embeds the TOTP workbench, the SIM-swap chapter embeds the attack simulator, the WebAuthn ceremony chapter embeds the ceremony mock, and the policy-design chapter embeds the policy engine. The same modules are reachable from the Lab item in the header, where each has a page of its own and a link back to its chapter. Playgrounds run as soon as they scroll into view; editing restarts them after a 450 ms pause.

7 · Quiz

Every chapter ends its prose with three questions. Choosing an option reveals immediately whether it is correct and why, including for wrong answers, because the explanation is where most learning happens. Quiz answers are not stored and do not gate completion; they are a self-check, not an exam.

8 · Progress

When the visitor scrolls past 80% of the chapter it is marked complete. A gold circle draws a check, a small burst of gold particles plays, a two-note chime sounds if the visitor has already interacted with the page, and a toast confirms. Progress rings on the series page, library and home update at once. A visitor can unmark a chapter from the checklist. Progress is per device; clearing site data resets it.

9 · Comment

Below previous/next navigation sits the discussion. A new chapter shows “Be the first to comment”. To post, the visitor types a display name and at least 15 characters; the button stays disabled until both are valid and a counter shows how many characters remain. Posting more than once in 30 seconds or more than eight times in an hour returns a plain-language message. Each top-level comment has Reply and Report; replies have Report only, keeping nesting to one level. A comment reported by three different browsers disappears for everyone, with its replies.

Error and edge states

• Unknown series, chapter, lab module or document → not-found page with a link to the library.
• Comments unavailable → an inline message with a Retry button; the chapter remains fully usable.
• Playground infinite loop → inline “Stopped after 6s” message; the editor stays editable.
• Invalid base32 in the workbench or invalid JSON in the policy engine → inline error under the field; other panels keep their last good state.