docs: add bundle URI download flowcharts

Add flowcharts documenting how the bundle URI feature in Git downloads from
the bundle server.

Co-authored-by: Derrick Stolee <[email protected]>
Signed-off-by: Victoria Dye <[email protected]>

Author: vdye

docs/technical/architecture.md

@@ -81,3 +81,103 @@ repository and configured future fetches, the latter to [fetch new
 bundles][bundle-uri-fetch] according to the `creationToken` heuristic.
 
 [bundle-uri-fetch]: https://git-scm.com/docs/bundle-uri#_fetching_with_bundle_uris
+
+## Use with `git`
+
+Although the contents of the bundle server can be downloaded manually, the
+intended use case of the bundle server is to supplement clones & fetches in Git.
+
+### `git clone`
+
+When performing an initial clone from a remote repository, the `--bundle-uri`
+option can be specified to download an initial list of bundles _as well as_
+configure future fetches to download incremental updates from the bundle server.
+
+Within Git, this process is as follows:
+
+```mermaid
+%%{ init: { 'flowchart': { 'curve': 'monotoneX' } } }%%
+flowchart TB;
+    user((User))
+    subgraph git
+        direction TB
+
+        req["Request to --bundle-uri URI"]
+        isBundle{{"Is response a bundle?"}}
+        unbundle["Unbundle response"]
+        parse["Parse bundle list"]
+        sort["Sort bundles by creationToken,\nhigh to low, select bundle with\nhighest creationToken"]
+        reqBundle["Request bundle from server"]
+        markUnbundled["Mark unbundled to\nskip it later"]
+        downloadSuccess{{"Download successful?"}}
+        unbundleReq["Unbundle downloaded bundle"]
+        reachable{{"All bundle objects are reachable?"}}
+        moreBundles{{"More bundles in list?"}}
+        moveLater["Select bundle list item with\nlower creationToken"]
+        moveEarlier["Select not-yet-unbundled\nbundle list item with\nhigher creationToken"]
+        incrementalFetch["Incremental fetch from origin"]
+    end
+    bundleServer[(Bundle Server)]
+    origin[(Remote host)]
+
+    user --> |"git clone --bundle-uri URI"| req
+    req <--> bundleServer
+    req --> isBundle
+    isBundle ----------> |Yes| unbundle
+    unbundle ---> incrementalFetch
+
+    isBundle --> |No| parse
+    parse --> sort
+    sort --> reqBundle
+    reqBundle <--> bundleServer
+    reqBundle --> downloadSuccess
+    downloadSuccess --> |Yes| unbundleReq
+    moreBundles ----> |No| incrementalFetch
+    moreBundles ---> |Yes| moveLater
+    downloadSuccess --> |No| markUnbundled
+    markUnbundled --> moveLater
+    unbundleReq --> reachable
+    reachable --> |No| moreBundles
+    reachable --> |Yes| moveEarlier
+    moveEarlier --> |No| unbundleReq
+    moveLater --> reqBundle
+
+    incrementalFetch <--> origin
+
+```
+
+### `git fetch`
+
+The process for fetching with a bundle server is very similar to that of
+cloning. Instead of a `--bundle-uri`, `git fetch` will use the `fetch.bundleURI`
+(set by an earlier `clone`) as its base bundle URI, as well as a stored
+`fetch.bundleCreationToken` indicating that bundles with a `creationToken` less
+than the stored value should not be (re-)fetched.
+
+In the flowchart above, this corresponds to an additional decision point:
+
+```mermaid
+%%{ init: { 'flowchart': { 'curve': 'monotoneX' } } }%%
+flowchart TB;
+    user((User))
+    subgraph git
+        direction TB
+
+        reqBundle["Request bundle from server"]
+        moreBundles{{"More bundles in list?"}}
+        moveLater["Select bundle list item with\nlower creationToken"]
+        creationToken{{"creationToken >= fetch.bundleCreationToken?"}}
+        style creationToken fill:#007733,stroke:#333,stroke-width:4px
+        incrementalFetch["Incremental fetch from origin"]
+    end
+    origin[(Remote host)]
+
+    user -.-> reqBundle
+    reqBundle -....-> moreBundles
+    moreBundles --> |No| incrementalFetch
+    moreBundles --> |Yes| moveLater
+    moveLater --> creationToken
+    creationToken --> |Yes| reqBundle
+    creationToken --> |No| incrementalFetch
+    incrementalFetch <--> origin
+```