From 415c9757a661f41fd3a39561858a1e14cd36578f Mon Sep 17 00:00:00 2001
From: deeaitch <himrodim@gmail.com>
Date: Wed, 29 Jul 2026 16:51:54 -0400
Subject: [PATCH] reference design ADR

---
 .../decisions/ADR-003-reference-design.md     | 120 ++++++++++++++++++
 1 file changed, 120 insertions(+)
 create mode 100644 reference/decisions/ADR-003-reference-design.md

diff --git a/reference/decisions/ADR-003-reference-design.md b/reference/decisions/ADR-003-reference-design.md
new file mode 100644
index 0000000..24e967d
--- /dev/null
+++ b/reference/decisions/ADR-003-reference-design.md
@@ -0,0 +1,120 @@
+# ADR-003: Build a Reference Design, Not a Production Framework
+
+* **Status:** Accepted
+* **Date:** 2026-07-29
+
+## Context
+
+OTA update systems differ significantly between products.
+
+Their architecture depends on factors such as:
+
+* hardware platform;
+* bootloader;
+* storage layout;
+* operating system;
+* security model;
+* network availability;
+* fleet size;
+* update frequency;
+* bandwidth limitations;
+* safety and regulatory requirements;
+* manufacturing and key-provisioning processes.
+
+A generic production-ready OTA framework would need to support many combinations of hardware, bootloaders, update artifacts, deployment systems, security policies, and fleet-management requirements.
+
+Building such a framework would significantly increase the project scope and could distract from its primary goal: explaining how reliable and secure OTA systems are designed.
+
+The project should demonstrate engineering principles and concrete implementation choices without claiming universal applicability.
+
+## Decision
+
+The project will be developed as a practical OTA reference design.
+
+It will provide:
+
+* documented requirements;
+* architecture descriptions;
+* Architecture Decision Records;
+* update-state models;
+* security analysis;
+* reliability analysis;
+* diagrams;
+* example implementations;
+* failure-injection tests;
+* at least one working embedded Linux implementation.
+
+The initial implementation may use Raspberry Pi as a practical demonstration platform, but the architecture will not be presented as Raspberry Pi-specific.
+
+The project will not claim to be:
+
+* a production-ready OTA framework;
+* a complete fleet-management service;
+* a universal update client;
+* a certified safety-critical solution;
+* a replacement for established commercial OTA platforms.
+
+## Alternatives Considered
+
+### Build a Reusable OTA Framework
+
+A reusable framework could provide common APIs, backend services, bootloader integrations, and platform adapters.
+
+It was not selected because it would require a much larger scope, long-term compatibility guarantees, extensive platform testing, and a stable public API.
+
+It would also shift the project away from architecture and engineering analysis toward product development and maintenance.
+
+### Build a Raspberry Pi-Specific OTA Tutorial
+
+A platform-specific tutorial would be easier to implement and explain.
+
+It was not selected because the main engineering principles—atomicity, rollback, artifact verification, health checks, boot control, and failure recovery—apply to many embedded Linux devices.
+
+Tying the project too closely to Raspberry Pi would unnecessarily limit its usefulness.
+
+### Publish Documentation Without a Working Implementation
+
+A documentation-only project would allow broader architectural discussion without platform-specific complexity.
+
+It was not selected because a working implementation is necessary to validate assumptions and demonstrate real failure modes.
+
+Without practical experiments, the project could remain too theoretical.
+
+### Build Only an OTA Update Client
+
+A standalone client would provide a concrete software artifact.
+
+It was not selected because OTA reliability depends on the complete system, including the bootloader, storage layout, update metadata, health checking, rollback, signing, and deployment process.
+
+The client alone would not demonstrate the full architecture.
+
+## Consequences
+
+### Positive
+
+* The project can focus on engineering reasoning and architecture.
+* Design decisions and trade-offs can be documented clearly.
+* The implementation can remain understandable and suitable for learning.
+* Platform-specific details can be isolated from general principles.
+* Additional reference implementations can be added later.
+* The project can evolve without promising a stable production API.
+* Failure scenarios can be explored openly without presenting the design as universally safe.
+
+### Negative
+
+* Users cannot assume the code is ready for direct production deployment.
+* Some components may be simplified for clarity.
+* Platform integration may require significant additional work.
+* The project may not cover manufacturing, provisioning, compliance, or very large fleet operations.
+* Readers must evaluate whether each design decision applies to their own product.
+* The boundary between a complete reference implementation and a framework must remain clearly documented.
+
+## Notes
+
+The repository README should contain a visible disclaimer similar to:
+
+> This repository contains an educational OTA reference design for embedded Linux. It demonstrates one possible approach to reliable and secure system updates. It is not a production-ready framework and must be adapted, reviewed, tested, and hardened for each target product.
+
+The project should prefer explicit architectural decisions over hidden assumptions.
+
+When a design choice is platform-specific, it should be documented separately from the general OTA architecture.