doc: architecture view with drawio to svg generation

* Initial architecture document view a view to high level
stack of Spectrum.
* Stack view is generated to svg from drawio using Alyssa's
drawio-headless in nixpkgs-upstream. Cherry-picked to
nixpkgs-spectrum for testing.
* An example to analyze the details of Spectrum dependencies
interactively is also provided.

Signed-off-by: Ville Ilvonen <ville.ilvonen@unikie.com>
Message-Id: <20220607064259.588734-1-ville.ilvonen@unikie.com>
Reviewed-by: Alyssa Ross <hi@alyssa.is>
Tested-by: Alyssa Ross <hi@alyssa.is>
Signed-off-by: Alyssa Ross <hi@alyssa.is>

4 files changed, 84 insertions, 3 deletions

diff --git a/Documentation/architecture.adoc b/Documentation/architecture.adoc
new file mode 100644
index 0000000..60b3baf
--- /dev/null
+++ b/Documentation/architecture.adoc
@@ -0,0 +1,76 @@
+= Architecture
+:page-parent: Explanation
+
+// SPDX-FileCopyrightText: 2022 Unikie
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+
+== Introduction
+
+Spectrum operating system stack is based on the principle of security by
+compartmentalization. The high level system stack is illustrated in the
+following diagram.
+
+image::diagrams/stack.svg[]
+
+=== Kernel space
+
+In the stack, kernel space security by compartmentalization is supported with
+linux kernel that includes kernel-based virtual machine (KVM) module enabling
+the kernel to work as virtual-machine manager, hypervisor. The kernel-side
+hypervisor supports virtualization of hardware resources - computational cores,
+memory and devices - securely. User space virtual machine guests are managed
+with cloud-hypervisor. Linux with KVM also supports portability to several
+hardware architectures. Currently Spectrum is supported only on x86_64 but ARM64
+is under work. In addition, hardened kernel will be investigated.
+
+=== Host user space
+
+This section provides high level overview of host user space tools and
+libraries.
+
+User space stack is build on musl standard C library with
+https://www.etalabs.net/compare_libcs.html[added safety on resource exhaustion
+and security hardening on memory allocation].
+
+https://skarnet.org/software/s6-rc/overview.html[s6-rc] service manager is used
+for services. kmod, util-linux and busybox are provided for essential system
+administration.
+
+https://github.com/cloud-hypervisor/cloud-hypervisor[cloud-hypervisor] is a host
+tooling for virtual machine management, written in Rust with a strong focus on
+security.
+
+Wayland refers to whole display stack providing communication with compositor
+(weston) for desktop services, including libraries and drivers for direct
+rendering and event devices. Clients are implemented as application virtual
+machines (see next section). Minimal host provides only Wayland terminal client,
+foot. Wayland, a simpler and more secure, protocol for compositor could provide
+support for legacy X applications as well but as of now none are provided.
+https://wayland.freedesktop.org/architecture.html[Wayland architecture] is well
+documented here.
+
+=== Application and system virtual machines
+
+Security by compartmentalization in Spectrum is implemented with virtual
+machines. Virtual machines currently launch using terminal and support only
+virtio-console. Wayland graphics support for appvms is under work. Please refer
+to xref:running-vms.html[running VMs] for more
+information.
+
+Reference set of virtual machines includes system machine, netvm, and
+application VMs, appvm-catgirl and appvm-elinks. Please refer to
+xref:creating-vms.html[creating VMs] for more
+information.
+
+== Details of Spectrum dependency tree
+
+High level overview of Spectrum stack is limited view to the system. For
+detailed, interactive view to dependencies please use `nix-tree` under the
+spectrum repository:
+
+`nix-build img/live -I
+nixpkgs=https://spectrum-os.org/git/nixpkgs/snapshot/nixpkgs-rootfs.tar.gz
+--no-out-link | xargs -o nix-tree`
+
+https://diode.zone/w/8DBDQ6HQUe5UUdLkpDuL35[See video of Spectrum live image
+interactive analysis with nix-tree]
diff --git a/Documentation/default.nix b/Documentation/default.nix
index 02b3c31..8b969d4 100644
--- a/Documentation/default.nix
+++ b/Documentation/default.nix
@@ -3,7 +3,7 @@
 
 { pkgs ? import <nixpkgs> {} }: pkgs.callPackage (
 
-{ lib, runCommand, jekyll }:
+{ lib, runCommand, jekyll, drawio-headless }:
 
 runCommand "spectrum-docs" {
   src = with lib; cleanSourceWith {
@@ -14,11 +14,13 @@ runCommand "spectrum-docs" {
       !(hasSuffix ".nix" name);
   };
 
-  nativeBuildInputs = [ jekyll ];
+  nativeBuildInputs = [ jekyll drawio-headless ];
 
   passthru = { inherit jekyll; };
-} ''
+}
+  ''
   jekyll build --disable-disk-cache -b /doc -s $src -d $out
+  drawio --recursive $out/diagrams/ --export -f svg $out/assets/images/
 ''
 ) {
   jekyll = import ./jekyll.nix { inherit pkgs; };
diff --git a/Documentation/diagrams/stack.drawio b/Documentation/diagrams/stack.drawio
new file mode 100644
index 0000000..bb42c1b
--- /dev/null
+++ b/Documentation/diagrams/stack.drawio
@@ -0,0 +1 @@
+<mxfile host="Electron" modified="2022-06-07T05:42:17.682Z" agent="5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/15.7.3 Chrome/91.0.4472.164 Electron/13.6.1 Safari/537.36" etag="_9gN0vdoL1l32oJlLSGM" version="15.7.3" type="device"><diagram id="C5RBs43oDa-KdzZeNtuy" name="Page-1">7Vpbc5s6EP41nmke3OFu+9Fx6uQk6WmbnDY5Tx0ZZNBEICIJX/LrjwTCGEOOnYwxtScvBlaLpN3v25UWuWOOwsUlBXHwlXgQdwzNW3TMi45h6LpmiIuULJVEM+xM4lPkKVkhuEcvMFdU0gR5kJUUOSGYo7gsdEkUQZeXZIBSMi+rTQkujxoDH1YE9y7AVekD8niQSftGr5BfQeQH+ci6M8haQpArK0tYADwyXxOZXzrmiBLCs7twMYJYei/3y8Nfywd8++RcXv9gz+Dn+c0/f//qZp2N3/LKygQKI/7uriePN3394np8+/Pfl9nj/Bn2v/1Qr2gzgBPlr47hYDHI+ZSIsYS/gZs1OM+JNPT8jkwIJ8WzdAxf4rKSfLnLUi4MhYJhxIv1NxxfXq8A9ebCJqHwadF3zvKRhQnZ4Jmacv5qDIOSJPKgtEoTzfMAcXgfZ9OcCxILWcBDLJ701dtbXadcPIOUw8UacZQrLyEJIadLoaJaV/xWceFY6nlekMx2lCxYI1guA4rX/qrrAjtxo+B7A5R6i1DeoihZpMYL2w3t5tfXowbT7rcNptEimC4midcNljGkM8QIPSoozX4ZSkurQmloh4TSrEB5A2mULrMsdc+mH4WlvOwsxil5giOCBRjmRUQiKLFEGG+IAEZ+JB5d4VQo5OfSb0ishUPVECLPk8PUolPGT0I9BiHC0pGKXJlUrfESheyZJDTtJ+BcLOqGLbllC5/JH6nAPvuE+BiCGLHPLgnTBpelquNpNoa4LUZpjBwbYT6wK9zQ68LcbIobVoUbV4TJ8E6YwO+DIC0TxOq1TRC7xXUgTJiYnwNCiX00YfLSFdqjTeGrC0QmFiSOXp+Fgjedx6rjjmGaVso4ZUxZLFXT353sYBxEnthr/s+0symWp928gzGaUCBJckTra2WrZLS9VerVhMiG52DkDWUpWSTCNU/tnNX2nsU2c6UHWJBO5O0AQq9UBVfhW4enBp1cRiEGHM3KtXMdZGqE7wSlUZKz45V9dN4DS32oXlqvVTf60QdbOuKA+pBXOkoJtLJ6J0494ruXh2h8cT0fDgddrse/J7d7KYvfkgS3pjCnS90t+eoo04flVNPHoKHsUYt0dXfeLtJzsMRiuToFrO0dSjFdPyTY1e12u2BPErackMUpgO1o2wNb7x0S7H1snfcJ9lR+KE73uGlnE5o3fBKlWHh2EiQYbI/4/iE54PxhHHgKyUmkdnOXaLcOifRgD0i/F9WEI9zF2SfwSnCHKEIhwGfVpqNC3LJ2QLypuq8Wcb3NAw8mChDenYVHhWFl8123ITvoGq23ec4RQV4AuBaxbMlm4bHH6ybWqwp/Heu6Sku3GwO7rtb6+FLT0pcau0QPczAo97D7l5otHTX8pUbfR0337pNSwH1EcU0OAXF8/DnE0nbIIXXrRYM5pM0DEbyM6nZ4J4G13duOde25eYNYV6u3OziFwnJ5JqrNEOUJqAm+ELgBiiCrOPrj3LQp9mycm5r6jsXBO85NxWPxl7tsFSn+uWh++Q8=</diagram></mxfile>
\ No newline at end of file
diff --git a/Documentation/diagrams/stack.drawio.license b/Documentation/diagrams/stack.drawio.license
new file mode 100644
index 0000000..231a54c
--- /dev/null
+++ b/Documentation/diagrams/stack.drawio.license
@@ -0,0 +1,2 @@
+SPDX-FileCopyrightText: 2022 Unikie
+SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0