From be8744f937150c65ffa5d98ffdc74c502dbcdd5e Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Mon, 19 Sep 2022 22:21:40 +0200
Subject: [PATCH] manual: architecture overview

these changes were not merged properly and had to be reverted.

see merge commit d8e54d19f71f78540dd967b2e42be6a5d8a0b1bb for full
history leading up to here.
---
 doc/manual/src/SUMMARY.md.in                |  1 +
 doc/manual/src/architecture/architecture.md | 77 +++++++++++++++++++++
 2 files changed, 78 insertions(+)
 create mode 100644 doc/manual/src/architecture/architecture.md

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index 908e7e3d9..b386aa14b 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -59,6 +59,7 @@
 @manpages@
   - [Files](command-ref/files.md)
     - [nix.conf](command-ref/conf-file.md)
+- [Architecture](architecture/architecture.md)
 - [Glossary](glossary.md)
 - [Contributing](contributing/contributing.md)
   - [Hacking](contributing/hacking.md)
diff --git a/doc/manual/src/architecture/architecture.md b/doc/manual/src/architecture/architecture.md
new file mode 100644
index 000000000..24150fc2b
--- /dev/null
+++ b/doc/manual/src/architecture/architecture.md
@@ -0,0 +1,77 @@
+# Architecture
+
+This chapter describes how Nix works.
+It should help users understand why Nix behaves as it does, and it should help developers understand how to modify Nix and how to write similar tools.
+
+## Overview
+
+Nix consists of [hierarchical layers].
+
+[hierarchical layers]: https://en.m.wikipedia.org/wiki/Multitier_architecture#Layers
+
+```
++---------------------------------------------------------------+
+| Nix                                                           |
+|                 [ commmand line interface ]------,            |
+|                              |                   |            |
+|                          evaluates               |            |
+|                              |                manages         |
+|                              V                   |            |
+|                 [ configuration language  ]      |            |
+|                              |                   |            |
+| +----------------------------|-------------------V----------+ |
+| | store                 evaluates to                        | |
+| |                            |                              | |
+| |            referenced by   V       builds                 | |
+| | [ build input ] ---> [ build plan ] ---> [ build result ] | |
+| |                                                           | |
+| +-----------------------------------------------------------+ |
++---------------------------------------------------------------+
+```
+
+At the top is the [command line interface](../command-ref/command-ref.md), translating from invocations of Nix executables to interactions with the underlying layers.
+
+Below that is the [Nix language](../language/index.md), a [purely functional] configuration language.
+It is used to compose expressions which ultimately evaluate to self-contained *build plans*, used to derive *build results* from referenced *build inputs*.
+
+[purely functional]: https://en.m.wikipedia.org/wiki/Purely_functional_programming
+
+Command line interface and Nix language are what users interact with most.
+
+> **Note**
+> The Nix language itself does not have a notion of *packages* or *configurations*.
+> As far as we are concerned here, the inputs and results of a build plan are just data.
+
+Underlying these is the [Nix store](../glossary.md#gloss-store), 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.
+
+> **Important**
+> A build task in Nix is called [derivation](../glossary#gloss-derivation).
+
+```
++----------------------------------------------------------------------------------+
+| store           ..............................................                   |
+|                 : build plan                                 :                   |
+|                 :                                            :                   |
+| [ build input ]---instructions-,                             :                   |
+|                 :              |                             :                   |
+|                 :              v                             :                   |
+| [ build input ]--------->[ build task ]-instructions-,       :                   |
+|                 :                                    |       :                   |
+|                 :                                    v       :                   |
+| [ build input ]---instructions-,              [ build task ]--->[ build result ] |
+|                 :              |                     ^       :                   |
+|                 :              v                     |       :                   |
+| [ build input ]--------->[ build task ]--------------'       :                   |
+|                 :              ^                             :                   |
+|                 :              |                             :                   |
+| [ build input ]----------------'                             :                   |
+|                 :                                            :                   |
+|                 :............................................:                   |
++----------------------------------------------------------------------------------+
+```
+