Architecture.md

+This document describes the high-level blocks present in SysOTA.
+
+# Boot Protocol
+
+Boot protocol defines how SysOTA interacts with the boot system. The protocol assumes the A/B update system.
+
+The protocol defines the following operations
+
+1. `Query`: Check if A or B is currently active for booting.
+2. `Try`: prepare the inactive slot for one-off boot.
+3. `Commit`: make the inactive slot active.
+4. `Rollback`: clean up files prepared by `Try`.  
+
+It is important to note that `Rollback` is only about the cleanup process and does not affect correctness. The `Try` operation allows the inactive slot to boot exactly once and the system returns to booting the active slot automatically.
+
+
+## Pi Boot
+
+Pi Boot is an implementation of the boot protocol. This module relies on the mutable boot partition and on the `tryboot.txt` feature offered by the platform firmware. The boot directory is used as follows:
+
+The `slot-a/` and `slot-b/` directories contain boot assets specific to each slot.
+The `config.txt` and `tryboot.txt` files are read and modified automatically to use the slot directories. This is done with the `os_prefix=slot-{a,b}/` parameter.
+
+The pre-install handler copies the boot assets to the slot-specific directory. The kernel command line file is also modified. The try operation creates `tryboot.txt` based on slot-specific `config.txt`. The post-install handler reboots the system with the "0 tryboot" argument to trigger the one-time-boot behavior. The commit operation renames `tryboot.txt` to `config.txt`. The rollback operation removes both `tryboot.txt` and the slot-specific directory corresponding to the inactive slot.
+
+Other boot assets in the root of the boot partition are not updated since this presents atomicity challenges. This affects `bootcode.bin`, `start.elf` and `fixup.dat`. It does not affect the overlays as those participate in the `os_prefix=` mechanism.
+
+The boot partition contains stale boot assets that are not used after the first update. Those are not removed yet.
+
+# RAUC Adapter
+
+This component bridges the concrete implementation of the boot protocol with RAUC. It is visible as a set of RAUC handlers (bootloader, pre-install and post-install) that all call into SysOTA service.
+
+This component is stateful. It remembers the boot mode (`try` or `normal`) that the system is in. Note that this is to allow detecting automatic rollback and performing cleanup, not for correctness of the boot protocol atomicity guarantees.
+
+# NetOTA Client
+
+This component interacts with a NetOTA repository and allows performing the upgrade if the local package name and source revision are different to what is published online. This component is both stateful and configurable. State consists of the installed package name, installed package version and source revision. Configuration consist of the URL of the NetOTA server, package name and stream name.
\ No newline at end of file