From ba11775edcfa37f73458a8a6e2b2cb137525915c Mon Sep 17 00:00:00 2001
From: James Lucktaylor <jlucktay+github@gmail.com>
Date: Fri, 28 Jun 2024 14:18:01 +0100
Subject: [PATCH] docs(taskfile): add flowchart for intended behaviour of Cache

Mapped out a flowchart to describe the behaviour of taskfile.Cache, so as to aid technical design and implementation.

re #1402
---
 taskfile/README.md | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)
 create mode 100644 taskfile/README.md

diff --git a/taskfile/README.md b/taskfile/README.md
new file mode 100644
index 0000000000..9b04190064
--- /dev/null
+++ b/taskfile/README.md
@@ -0,0 +1,43 @@
+# The `taskfile` package
+
+```mermaid
+---
+title: taskfile.Cache behaviour
+---
+flowchart LR
+  %% Beginning state
+    start([A remote Taskfile
+      is required])
+
+  %% Checks to decide
+    cached{Remote Taskfile
+      already cached?}
+
+    subgraph checkTTL [Is the cached Taskfile still inside TTL?]
+    %% Beginning state
+      lastModified(Stat the cached
+        Taskfile and get last
+        modified timestamp)
+
+    %% Check to decide
+      timestampPlusTTL{Timestamp
+        plus TTL is in
+        the future?}
+
+    %% Flowlines
+      lastModified-->timestampPlusTTL
+    end
+
+  %% End states
+    useCached([Use the
+      cached Taskfile])
+    download(["(Re)download the
+      remote Taskfile"])
+
+  %% Flowlines
+    start-->cached
+    cached-- Yes -->lastModified
+    cached-- No -->download
+    timestampPlusTTL-- Yes -->useCached
+    timestampPlusTTL-- No -->download
+```