= Architecture
:page-parent: About Spectrum

// SPDX-FileCopyrightText: 2022 Unikie
// SPDX-FileCopyrightText: 2022, 2024 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 default set of virtual machines includes some application VMs,
(names prefixed with _appvm-_); and a system VM, _netvm_ (which
handles hardware network devices and provides network services to
application VMs).  Refer to
xref:../using-spectrum/running-vms.adoc[Running VMs] and
xref:../using-spectrum/creating-custom-vms.adoc[Creating Custom 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://cloudhypervisor.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 onlya Wayland terminal client,
https://codeberg.org/dnkl/foot/[foot], which is used for interacting with VM
consoles.
It is possible for application VMs to display windows on the single Wayland
compositor on the host system, using Wayland virtio-gpu contexts.  X11
applications may be usable, but the host does not provide any special
accommodations for them, so the guest must bridge them to Wayland.
By default this is done with
https://github.com/talex5/wayland-proxy-virtwl[wayland-proxy-virtwl].

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 --no-out-link | xargs -o nix-tree

See the https://diode.zone/w/8DBDQ6HQUe5UUdLkpDuL35[video] of Spectrum live
image interactive analysis with nix-tree.