docs: add some software architecture to riki.md

Sponsored-by: author

1 files changed, 82 insertions, 0 deletions

diff --git a/riki.md b/riki.md
index b7551e1..4c78f11 100644
--- a/riki.md
+++ b/riki.md
@@ -8,6 +8,88 @@ speed. This document describes the requirements and acceptance
 criteria for the software, and how to verify that riki meets them in
 an automated way. This is done using the [Subplot][] software.
 
+# Software architecture
+
+`riki` converts files in a source tree into a files that form a static
+website in an output, or target, tree. The files in the source tree
+are either "pages" or "blobs". The files in the target tree are HTML
+files or blobs.
+
+Source pages contain "wiki text", which
+adds on top of Markdown syntax for *wiki links* and *directives*:
+
+* plain wiki link: `[[pagename]]`
+  - this corresponds to Markdown: `[pagename](pagename)`
+  - or HTML: `<a href="pagename">pagename</a>`
+* wiki link with link text: ``[[link text|pagename]]`
+  - this corresponds to Markdown: `[link text](pagename)`
+  - or HTML: `<a href="pagename">link text</a>`
+* directive: `[[!foo arg other="value for other" more="""value for
+  more"""]]`
+  - directive arguments may contain values
+  - values may be single or triple quoted: triple quoted may span
+    multiple lines
+
+Directives cause some processing to be done. That processing may take
+as its input only values of arguments, or the page, where the
+directive is used, or all other files in the site.
+
+Wiki text is converted into plain Markdown by replacing wiki links and
+directives with Markdown text, before the whole page is parsed into
+HTML, which gets written to the target directory.
+
+Blobs are copied to the target directory as-is, without any
+processing.
+
+## Processing pipeline
+
+~~~dot
+digraph "processing" {
+    source [shape=folder]
+    target [shape=folder]
+    blob [shape=note]
+    wikitext [shape=note]
+    html [shape=note]
+
+    source -> blob
+    source -> wikitext
+
+    wikitext -> markdown
+    wikitext -> wikilink
+    wikitext -> directive
+    wikilink -> markdown
+    directive -> markdown
+
+    markdown -> html
+    html -> target
+
+    blob -> target
+}
+~~~
+
+When the site is processed from source to target, the processing
+pipeline is roughly like this:
+
+* read in all files in the source tree
+* parse each page of wiki text into snippets
+  - a snippet is plain markdown, a wiki link, or a directive
+* prepare directives in each page
+  - this collects or produces data needed for processing the
+    directive, but doesn't produce output
+* process directives in each page
+  - this produces markdown output
+* process wiki links in each page
+* combine all processed snippets into one markdown string for each
+  page and parse that into HTML
+* write HTML files to target tree
+* copy all blobs to target tree
+
+Note that when preparing or processing directives, directives on all
+pages are prepared first, before any directives are processed. This
+allows things like defining shortcuts on any page of the site: the
+shortcut definitions are recognized and obeyed during the preparation
+stage.
+
 # Verification scenarios
 
 The approach used for verifying acceptance criteria is to run `riki`