From d5eea66615266e7c341e8d4e982af12d6cb82887 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 26 May 2022 02:52:10 +0200
Subject: [PATCH] introduce build tasks

while it appears a bit much for the overview, this way we set the stage
for going directly into data types when describing the store, instead of
first having to say what build tasks are and how they relate to build
plans.
---
 doc/manual/src/architecture/architecture.md | 32 +++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/doc/manual/src/architecture/architecture.md b/doc/manual/src/architecture/architecture.md
index 6d4b86935..8000aecd1 100644
--- a/doc/manual/src/architecture/architecture.md
+++ b/doc/manual/src/architecture/architecture.md
@@ -43,5 +43,37 @@ In practice this amounts to a set of files in a file system.
 Underlying these is the [Nix store](./store/store.md), a mechanism to keep track of build plans, data, and references between them.
 It can also execute build plans to produce new data.
 
+A build plan is a series of *build tasks*.
+Each build task has a special build input which is used as *build instructions*.
+The result of a build task can be input to another build task.
+
+```
++-----------------------------------------------------------------------------------------+
+| store                                                                                   |
+|                   .................................................                     |
+|                   :  build plan                                   :                     |
+|                   :                                               :                     |
+|  [ build input ]-----instructions-,                               :                     |
+|                   :               |                               :                     |
+|                   :               v                               :                     |
+|  [ build input ]----------->[ build task ]--instructions-,        :                     |
+|                   :                                      |        :                     |
+|                   :                                      |        :                     |
+|                   :                                      v        :                     |
+|                   :                               [ build task ]----->[ build result ]  |
+|  [ build input ]-----instructions-,                      ^        :                     |
+|                   :               |                      |        :                     |
+|                   :               v                      |        :                     |
+|  [ build input ]----------->[ build task ]---------------'        :                     |
+|                   :               ^                               :                     |
+|                   :               |                               :                     |
+|  [ build input ]------------------'                               :                     |
+|                   :                                               :                     |
+|                   :                                               :                     |
+|                   :...............................................:                     |
+|                                                                                         |
++-----------------------------------------------------------------------------------------+
+```
+
 [layer-architecture]: https://en.m.wikipedia.org/wiki/Multitier_architecture#Layers
 [purely-functional-programming]: https://en.m.wikipedia.org/wiki/Purely_functional_programming