= Architecture
:page-parent: About Spectrum

// SPDX-FileCopyrightText: 2022 Unikie
// SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0

Spectrum is based on the principle of security by compartmentalization.

The high level stack is illustrated in the following diagram:

image::../diagrams/stack.svg[]

The default set of virtual machines includes two application VMs,
_appvm-catgirl_ (an IRC client) and _appvm-lynx_ (a text-based web
browser); and a system VM, _netvm_ (which handles hardware network
devices and provides network services to application VMs).  Refer to
xref:creating-vms.adoc[Creating VMs] and xref:running-vms.adoc[Running
VMs] for more information about using VMs in Spectrum.

== Architecture Decision Records (ADRs)

https://en.wikipedia.org/wiki/Architectural_decision[Architecturally significant
decisions] are xref:decisions/index.adoc[recorded] as lightweight
https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions/[ADRs].

== Spectrum Host System

Compartmentalization is implemented using
https://cloud-hypervisor.org/[cloud-hypervisor] virtual machines.
cloud-hypervisor uses Linux's
https://en.wikipedia.org/wiki/Kernel-based_Virtual_Machine[Kernel-based Virtual
Machine] (KVM) to provide lightweight, hardware-accelerated VMs.

While Linux (including KVM) is portable between many hardware architectures,
cloud-hypervisor supports only x86_64 and aarch64. Spectrum currently only
works on x86_64, but aarch64 support is in development.

https://skarnet.org/software/s6-rc/overview.html[s6-rc] is used for service
management.  Utilities like kmod, util-linux and busybox are installed for boot
and service scripts.

https://wayland.freedesktop.org/[Wayland] is used for window management and
display.  The Wayland architecture is well documented
https://wayland.freedesktop.org/architecture.html[here]. The host provides only
a Wayland terminal client, https://codeberg.org/dnkl/foot/[foot], which is used
for interacting with VM consoles.  In future it will be possible for application
VMs to display windows on the single Wayland compositor on the host system,
using Wayland virtio-gpu contexts.  X11 applications are not currently
supported, but could be in future.

All host user space components are built with the https://musl.libc.org/[musl C
library].  In comparison to other libc implementations, musl has
https://www.etalabs.net/compare_libcs.html[added safety on resource exhaustion
and security hardening on memory allocation].  Kernel hardening will be
investigated in future.

== Spectrum Dependency Tree

For a detailed, interactive view of dependencies, use
https://github.com/utdemir/nix-tree[nix-tree] in the Spectrum repository:

[source,shell]
[listing]
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].
