@@ -1,11 +1,14 @@
 #lang scribble/manual
 
 @; SPDX-License-Identifier: BlueOak-1.0.0
 @; This file is licensed under the Blue Oak Model License 1.0.0.
 
-@(require "scribble-helpers.rkt")
+@(require "scribble-helpers.rkt"
+          racket/runtime-path
+          (for-label racket/base
+                     "../crystalize.rkt"))
 
 @title{Local Yarn: source code notes}
 
 @author{Joel Dueck}
 
@@ -17,22 +20,42 @@
 "pollen/scribblings/pollen.scrbl")], and worked through the tutorials by hand.
 
 @margin-note{Note that these pages are heavily interlinked with the central Racket documentation at
 @tt{docs.racket-lang.org}, which are written and maintained by others. 
 
-If you’re browsing these docs from within @italic{The Local Yarn}’s main website, and if you follow
-links to other Racket documentation, you’ll find that to @emph{other} sites on those pages will not
-work (due to the  @ext-link["https://content-security-policy.com"]{content security policy} in
-effect when inside a frame). To follow such links, right-click and open the link in a new tab or
-window.
+Some links from those pages will not work unless you @ext-link["#"]{open this page in its own tab}.
+}
+
+Here’s a rough diagram showing how the @tt{.rkt} modules in this project relate to each other, and
+to the Pollen source documents. This is the least complex system I could devise that would @tt{A)}
+implement everything I want in my @secref["design-goals"], @tt{B)} cleanly separate dependencies for
+print and web output, and @tt{C)} organize an ever-growing collection of hundreds of individual
+notes and articles without noticable loss of speed. 
+
+@(define-runtime-path source-diagram "source-diagram.png")
+@centered{@responsive-retina-image[source-diagram]}
+
+The solid-line connections indicate explicit @racket[require] relationships. Dotted arrows generally
+indicate implicit exports in the Pollen environment: docs and metas to templates,
+@seclink["pollen-rkt"]{@filepath{pollen.rkt}} to source documents and templates. The orange lines
+highlight the provision and use of the functions in
+@seclink["crystalize-rkt"]{@filepath{crystalize.rkt}}.
+
+Individual articles, while they are being rendered to HTML pages, save copies of their metadata and
+HTML to the SQLite cache. This is done by calling @racket[parse-and-cache-article!] from within
+their template. Likewise, series pages cache themselves with a call to @racket[cache-series!] from
+within their template.
 
-You may also wish to @ext-link["#"]{open this page in its own tab.}}
+Any pages that gather content from multiple articles, such as Series pages and the RSS feed, pull
+this content directly from the SQLite cache. This is much faster than trawling through Pollen’s
+cached metas of every article looking for matching articles.
 
 @local-table-of-contents[]
 
 @include-section["tour.scrbl"]
-@include-section["overview.scrbl"]
+@include-section["design.scrbl"]
 @include-section["pollen.scrbl"]  @; pollen.rkt
 @include-section["dust.scrbl"]    @; dust.rkt
 @include-section["snippets-html.scrbl"] @; you get the idea
 @include-section["cache.scrbl"]
 @include-section["crystalize.scrbl"]
+