@@ -1,35 +1,61 @@
 #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}
 
 These are my notes about the internals of the Local Yarn source code. In other words, a personal
 reference, rather than a tutorial. These pages concern only the source code itself. Refer to the
 wiki for info about deployment, etc.
 
-
 You’ll get the most out of these notes if you have read @other-doc['(lib
 "pollen/scribblings/pollen.scrbl")], and worked through the tutorials by hand.
 
-If you’re viewing these notes on the Fossil repository, 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. Links on those pages that lead outside of that domain will not work within
-this repo’s “Code Docs” frame, due to the repository’s
-@ext-link["https://content-security-policy.com"]{content security policy}. To follow such links,
-right-click and open the link in a new tab or window.
+@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. 
+
+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.
 
+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["overview.scrbl"]
+@include-section["tour.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"]