# 03. OTA System Architecture: How the Parts Work Together

The previous chapter looked at what we update: a system image, an application, or data. Now let’s look at who does the work.

An OTA update starts with a tested release and ends with a device running it successfully. Several parts of the system help it get there.

## 1. The Big Picture

```text
Build and test a release
          |
          v
Publish update files
          |
          v
Server offers the release to selected devices
          |
          v
Device downloads and checks the update
          |
          v
Install -> Activate -> Check that it works
          |
          v
Report the result to the server
```

The server decides which devices should receive a release. The device checks whether it can update now, carries out the work, and reports the result.

Alongside the update files, it needs a few details: which version this is, which devices it supports, and how to verify it. The server also needs feedback. “Update offered” and “new version running” are different things.

## 2. Who Does What?

**Release preparation and storage.** The software is built, tested, given a version, and published for download. The release includes information needed to check that the files are intact and come from an authorized source. Storage can be as simple as a file server.

**Deployment management.** This part chooses which devices receive which release and tracks their progress. For example, an operator might offer a release to a small test group before making it available to everyone.

**OTA manager.** On the device, the manager organizes the update. It checks whether the release fits the device and whether local conditions allow the work. A device might download an update while busy, then wait until its current task finishes before restarting.

**Installer.** This part knows how to install the software: write an image, install a package, or prepare a new set of files. Depending on the tool, it may also handle downloading and verification. The manager decides when to proceed; the installer knows how to do the installation.

**Activation and boot control.** Installed software is not necessarily running yet. A system update may need a reboot into the new version. An application update may need only a service restart. For system updates, boot components must also handle cases where the new system cannot start the OTA manager.

**Health checks.** These check whether the new version can do its job. Linux starting successfully may not be enough: the main application might still fail. The results help the device decide whether to keep the new version or start recovery.

These are roles, not a shopping list of separate services. One tool may cover several of them. What matters is knowing who handles each step.

The following view shows the roles and the server/device boundary for the system-update example used in the next chapter.

![OTA roles and device boundary](../diagrams/rendered/ota-architecture.png)

[PlantUML source](../diagrams/plantuml/ota-architecture.puml)

## 3. One Update, Start to Finish

Imagine a device running version 1. Version 2 is ready. In this example, the device can prepare the new system while keeping the previous one available for recovery.

1. The device checks with the server, which returns version 2 as an available update for this device.
2. The OTA manager checks that it fits this device and that an update is allowed now.
3. The installer downloads, verifies, and prepares version 2. Version 1 is still running.
4. When the device can restart, boot control selects version 2 and the device reboots.
5. Health checks test the essential functions. If they pass, the device confirms version 2. If they fail, it starts recovery. If the system cannot boot at all, the boot recovery mechanism must handle that earlier failure.
6. The device reports the outcome, including which version is now running.

What if the network disappears? In this example, once the required files and verification information are available, the device can finish the local steps without the server. It sends its report when the connection returns. A broken connection alone does not mean the new software is broken.

If the update itself is interrupted, the device needs enough saved information to work out what happened before continuing. We will look at storage, boot behavior, and recovery in later chapters.

[ADR-011: Device-Initiated Update Checks](../adr/ADR-011-device-initiated-update-checks.md) explains how a device checks for updates at power-on, on a schedule, or at the operator’s request.

Next, we will follow [the startup of an updated system or service](04-starting-an-updated-system-or-service.md). We will look at recovery before the OTA manager starts, and at restoring an older package when an updated service fails.