docs: add architecture explanation page

docs/.custom_wordlist.txt

@@ -15,6 +15,7 @@ Codecov
 distro
 distros
 ESM
+gRPC
 Intune
 macOS
 MSIX

docs/explanation/index.md

@@ -0,0 +1,12 @@
+(explanation)=
+
+# Explanation
+
+This section contains explanations that will help you develop a deeper
+understanding of how UP4W is designed.
+
+```{toctree}
+:titlesonly:
+
+ref-arch-explanation
+```

docs/explanation/ref-arch-explanation.md

@@ -0,0 +1,139 @@
+# UP4W architecture
+
+This page describes the different components of UP4W and how they integrate
+together to form the software architecture.
+
+## Background
+
+### What is Ubuntu WSL?
+
+With the Windows Subsystem for Linux (WSL), Linux distributions can be run on
+Windows with minimal overhead. Ubuntu WSL is an image that is optimised for
+running Ubuntu WSL. A user can create an Ubuntu WSL instance on a Windows
+machine and use that instance as a production-ready development environment.
+Ubuntu WSL also benefits from tight integration with Ubuntu Pro and
+Landscape, which makes it easier to secure Ubuntu WSL instances and manage them
+at scale.
+
+### Why is managing WSL instances at scale difficult?
+
+An individual user can create and configure multiple, independent instances of
+Ubuntu WSL on their machine. For a system administrator, who is managing
+fleets of Windows machines with multiple users, the potential number of Ubuntu
+WSL instances increases dramatically. While the system administrator has tools
+for managing Windows machines, WSL instances can be a black box that cannot be
+directly monitored or patched. This can result in WSL instances that do not
+follow system administration policies.
+
+### How does Ubuntu Pro for WSL solve this problem?
+
+Ubuntu Pro for WSL (UP4W) helps automate the management of Ubuntu WSL.
+For each new instance that is discovered or created, UP4W will automatically:
+
+* Attach them to your Ubuntu Pro subscription
+* Enrol them with your Landscape server
+
+The integration with Ubuntu Pro keeps instances secure, while the
+integration with Landscape enables remote deployment and management.
+
+Without UP4W, these configurations would be manual, time-consuming and
+error-prone.
+
+## The components of UP4W
+
+```{admonition} WSL architecture
+:class: tip
+WSL is maintained by Microsoft and its architecture is outside the scope of this page.
+
+A good overview of WSL architecture is provided in [this blog from Microsoft](https://learn.microsoft.com/en-us/previous-versions/windows/desktop/cmdline/wsl-architectural-overview).
+```
+
+### Overview
+
+UP4W consists of some components that run on a Windows host
+and others that run within instances of Ubuntu  WSL.
+
+A user interacts with the UP4W application. UP4W then automatically
+pro-attaches and Landscape-enrols each new instance of Ubuntu WSL that is
+created on the Windows host.
+
+In an organisation, multiple users of Windows machines can create Ubuntu WSL
+instances, which are secured by Ubuntu Pro and that can be managed by Landscape.
+
+```{figure} ../diagrams/structurizr-SystemLandscape.png
+:name: user-interact-arch
+:alt: architecture diagram showing user interaction with Ubuntu Pro for WSL
+:align: center
+```
+
+### Components on the Windows host
+
+The Windows host is a single machine running the Windows OS. WSL instances can
+be created and instanced on this host. The UP4W application that is installed
+on the Windows host consists of a GUI front end and an agent that runs in the
+background.
+
+A user enters a Pro token and Landscape configuration using the GUI. When the
+GUI is launched it starts the Windows Agent, if it's not already running. The agent runs in the background
+on the Windows host and manages communication with other components, including
+the remote Landscape server and the Pro service running within each instance of
+Ubuntu WSL. The agent is responsible for managing the state of instances and
+acts as a bridge between those instances and Landscape. If the configuration
+details are valid, all new instances will have Ubuntu Pro enabled and will be
+able to communicate with the Landscape server.
+
+```{figure} ../diagrams/structurizr-SystemContainers.png
+:name: top-level-arch
+:alt: architecture diagram showing coordinating role of agent
+:align: center
+```
+
+It is possible to bypass the GUI and instead configure UP4W using the Windows
+registry. This may be the preferred option for those operating at scale. When
+UP4W is launched, a registry path is created that can be used to store a Pro
+token and a Landscape configuration. A system administrator can use a remote
+management solution like Intune to configure the registry on fleets of devices.
+
+### Components on Ubuntu WSL instances
+
+The WSL Pro service runs in each instance of Ubuntu WSL. From the host, the
+Windows agent communicates with this service. This allows commands to be sent
+from the host, which are then executed by the Pro service on each instance.
+When an Ubuntu WSL instance is started, the WSL Pro service runs and queries
+the Windows agent on the host for the status of the Pro subscription.
+If the Pro token is valid, it is retrieved from the Windows agent and
+passed to the Pro service running on Ubuntu WSL instances.
+If not, Ubuntu Pro is disabled on the instances.
+
+Pre-installed on each instance of Ubuntu WSL is an Ubuntu Pro client
+and a Landscape client.
+After a Pro token is provided, the Windows agent can send a
+command to the Ubuntu Pro client to execute pro-attach on active instances.
+Similarly, when a Landscape configuration is provided, the Windows agent
+can send a command to configure the Landscape client in each instance.
+
+The administrator of the Landscape server can also send commands to the agent
+to deploy new instances or delete existing instances.
+
+```{figure} ../diagrams/structurizr-Production.png
+:name: production-arch
+:alt: architecture diagram for production, with instances deployed from remote server
+:align: center
+```
+
+Ubuntu WSL instances that are deployed at scale can be extensively customised.
+The Landscape API can be used to automate the deployment of a custom rootfs. As
+of Ubuntu 24.04 LTS, cloud-init is pre-installed on Ubuntu WSL instances, which
+makes it possible to automate the configuration of instances created from that
+release.
+
+### Source code
+
+UP4W is open-source software. You can look at the code in the [GitHub
+repo](https://github.com/canonical/ubuntu-pro-for-wsl).
+
+The following technologies are used to build UP4W:
+
+* **Go**: Windows agent and WSL Pro service
+* **Flutter**: GUI front end
+* **gRPC**: communication between back end and front end

docs/index.md

@@ -15,7 +15,7 @@ Read our [getting started tutorial](tutorial/getting-started) to begin.
 
 ## In this documentation
 
-````{grid} 1 1 1 1
+````{grid} 1 1 2 2
 
 ```{grid-item-card} [Tutorials](tutorial/index)
 :link: tutorial/index
@@ -24,17 +24,16 @@ Read our [getting started tutorial](tutorial/getting-started) to begin.
 **Start here** with hands-on tutorials for new users, guiding you through your first-steps
 ```
 
-````
-
-````{grid} 1 1 2 2
-
 ```{grid-item-card} [How-to guides](howto/index)
 :link: howto/index
 :link-type: doc
 
 **Follow step-by-step** instructions for key operations and common tasks
 ```
 
+````
+
+````{grid} 1 1 2 2
 
 ```{grid-item-card} [Reference](reference/index)
 :link: reference/index
@@ -43,6 +42,13 @@ Read our [getting started tutorial](tutorial/getting-started) to begin.
 **Read technical descriptions** of important factual information relating to UP4W
 ```
 
+```{grid-item-card} [Explanation](explanation/index)
+:link: explanation/index
+:link-type: doc
+
+**Read an explanation** of UP4W's system architecture
+```
+
 ````
 
 ## Project and community
@@ -59,4 +65,5 @@ UP4W <self>
 Tutorial </tutorial/index>
 How-to guides </howto/index>
 Reference </reference/index>
+Explanation </explanation/index>
 ```

docs/reference/09-qa-process-reference.md

@@ -2,6 +2,12 @@
 
 ## Generalities
 
+```{note}
+We always use the latest Go version available. Information about specific Go
+versions on this page may be outdated, as the version used is periodically
+updated.
+```
+
 `wsl-pro-service` is seeded only on WSL images.
 
 ```

docs/reference/glossary_up4w_components.md

@@ -0,0 +1,65 @@
+(ref::glossary-up4w-components)=
+# Glossary of UP4W components
+
+The architecture of UP4W and how its components integrate together is covered in our detailed [explanation article](../explanation/ref-arch-explanation.md).
+This glossary includes concise descriptions of the components for reference.
+
+(ref::up4w-gui)=
+## GUI front end
+
+UP4W has a small GUI that helps users provide an Ubuntu Pro token and
+[configure Landscape](ref::landscape-config).
+
+When the GUI starts, it attempts to establish a connection to the [UP4W Windows Agent](ref::up4w-windows-agent). If this fails, the agent is restarted. For troubleshooting purposes, you can restart the agent by first stopping the Windows process `ubuntu-pro-agent-launcher.exe` in Windows Task Manger or by issuing the following command in a PowerShell terminal:
+
+```text
+Stop-Process -Name ubuntu-pro-agent.exe
+```
+
+You can then launch the GUI to complete the restart.
+
+(ref::landscape-client)=
+## Landscape client
+
+The Landscape client is a `systemd` unit running inside every Ubuntu WSL instance. It sends information about the system to the Landscape server. The server, in turn, sends instructions that the client executes.
+
+The Landscape client comes pre-installed in your distro as part of the package `landscape-client`.
+
+You can check the status of the Landscape client in any particular Ubuntu WSL instance by starting a shell in that instance and running:
+
+```text
+systemctl status landscape-client.service
+```
+
+(ref::ubuntu-pro-client)=
+## Ubuntu Pro client
+
+The Ubuntu Pro client is a command-line utility that manages the
+different offerings of your Ubuntu Pro subscription. In UP4W, this executable
+is used within each of the managed WSL distros to enable [Ubuntu
+Pro](https://documentation.ubuntu.com/pro/) services within that distro.
+
+This executable is provided as part of the `ubuntu-pro-client` package,
+which comes pre-installed in Ubuntu WSL instances since Ubuntu 24.04 LTS.
+
+(ref::up4w-windows-agent)=
+## Windows agent
+
+UP4W's Windows agent is a Windows application running in the background. It starts automatically when the user logs in to Windows. If it stops for any reason, it can be started by launching the UP4W GUI or running the executable from the terminal, optionally with `-vvv` for verbose logging:
+
+```text
+ubuntu-pro-agent.exe -vvv
+```
+
+The Windows agent is UP4W's central hub that communicates with all the components to coordinate them.
+
+(ref::up4w-wsl-pro-service)=
+## WSL Pro service
+
+This is a `systemd` unit running inside every Ubuntu WSL instance. The [Windows agent](ref::up4w-windows-agent) running on the Windows host sends commands that the WSL Pro Service executes, such as pro-attaching or configuring the [Landscape client](ref::landscape-client).
+
+You can check the current status of the WSL Pro Service in any particular distro with:
+
+```text
+systemctl status wsl-pro.service
+```

docs/reference/index.md

@@ -3,14 +3,14 @@
 # Reference
 
 This section contains concise references relating to how UP4W is designed,
-configured and developed:
+configured and developed.
 
-Descriptions of key UP4W components can be found here:
+A glossary of key UP4W system components can be found here:
 
 ```{toctree}
 :titlesonly:
 
-index_up4w_components
+glossary_up4w_components
 ```
 
 Details on firewall configuration, Landscape setup and using the Windows