move to deparate adr folder

docs/00-series-overview.md

@@ -0,0 +1,262 @@
+# OTA Reference Design
+
+> A practical guide to designing reliable, secure, and maintainable over-the-air (OTA) update systems for embedded Linux devices.
+
+---
+
+## About This Repository
+
+This repository presents a practical reference design for building over-the-air (OTA) update systems for embedded Linux devices.
+
+Rather than documenting a particular framework or vendor-specific solution, it focuses on the engineering principles that make OTA systems reliable, secure, and maintainable.
+
+The goal is to explain **why** modern OTA systems are designed the way they are, what problems they solve, and what trade-offs different approaches involve.
+
+Although many examples use Raspberry Pi as a demonstration platform, the concepts are applicable to a wide range of embedded Linux systems.
+
+---
+
+## Why This Repository Exists
+
+There is no shortage of documentation for OTA frameworks.
+
+You can easily find documentation for tools such as:
+
+- Mender
+- RAUC
+- SWUpdate
+- OSTree
+- A/B Updates
+
+However, these resources usually explain **how to use a particular tool**, not **why OTA systems are designed this way**.
+
+Questions like these are often left unanswered:
+
+- Why do many devices use A/B partitions?
+- Why are bootloaders involved in the update process?
+- Why is rollback necessary?
+- What happens if power is lost during an update?
+- Why are update images signed?
+- Why are atomic updates important?
+- How do production devices remain recoverable after failures?
+
+This repository attempts to answer those engineering questions.
+
+---
+
+## What You'll Learn
+
+Throughout this series we will explore topics including:
+
+- OTA architecture
+- Boot process
+- Update strategies
+- Full-image vs package updates
+- A/B partition layouts
+- Bootloader interaction
+- Rollback mechanisms
+- Atomic updates
+- Image verification
+- Digital signatures
+- Secure Boot
+- Failure recovery
+- Delta updates
+- Version management
+- Testing strategies
+- Production deployment considerations
+
+The emphasis is always on understanding the underlying design rather than memorizing a particular implementation.
+
+---
+
+## Repository Structure
+
+```text
+ota-reference-design/
+│
+├── docs/
+│   ├── 00-series-overview.md
+│   ├── 01-ota-introduction.md
+│   ├── 02-update-strategies.md
+│   ├── ...
+│
+├── diagrams/
+│   └── plantuml/
+│
+├── examples/
+│   ├── raspberry-pi/
+│   ├── qemu/
+│   └── simulations/
+│
+├── adr/
+│   ├── ADR-001-repository-name.md
+│   ├── ADR-002-license.md
+│   └── ADR-003-reference-design.md
+│
+└── README.md
+```
+
+---
+
+## Learning Path
+
+The chapters are designed to build on each other.
+
+```text
+Introduction
+      │
+      ▼
+Update Strategies
+      │
+      ▼
+System Architecture
+      │
+      ▼
+Boot Process
+      │
+      ▼
+Storage Layout
+      │
+      ▼
+Atomic Updates
+      │
+      ▼
+Rollback
+      │
+      ▼
+Security
+      │
+      ▼
+Testing
+      │
+      ▼
+Production Deployment
+```
+
+While each chapter can be read independently, following the series in order provides a much deeper understanding of the complete system.
+
+---
+
+## Engineering Philosophy
+
+This repository is intentionally different from product documentation.
+
+Instead of presenting a single "correct" solution, every topic discusses:
+
+- why a particular design exists;
+- which problem it solves;
+- what alternatives are available;
+- what trade-offs each approach introduces;
+- when another solution may be more appropriate.
+
+Real-world engineering is rarely about choosing the only correct answer.
+
+It is about understanding constraints and making informed decisions.
+
+---
+
+## The Reference Design
+
+The architecture presented throughout this repository is a coherent reference design.
+
+Real products may use different technologies or frameworks while following the same architectural principles.
+
+For example, one project may use RAUC, another SWUpdate, and another a completely custom implementation.
+
+The implementation details may differ.
+
+The underlying engineering principles usually do not.
+
+---
+
+## Practical Examples
+
+Where possible, theoretical discussions are accompanied by practical material, including:
+
+- architecture diagrams
+- boot sequence walkthroughs
+- storage layout examples
+- failure scenarios
+- Raspberry Pi demonstrations
+- QEMU-based experiments
+- implementation notes
+
+The objective is to connect high-level architecture with practical implementation.
+
+---
+
+## Intended Audience
+
+This repository is intended for:
+
+- Embedded Linux developers
+- Firmware engineers
+- Embedded software engineers
+- System architects
+- Students learning embedded systems
+- Engineers preparing for technical interviews
+- Anyone interested in understanding OTA system design
+
+No prior experience with OTA frameworks is assumed.
+
+---
+
+## How to Read This Repository
+
+If you are new to OTA systems, simply start with Chapter 1 and continue in order.
+
+If you already have embedded Linux experience, feel free to jump directly to topics that interest you.
+
+If you are looking for implementation details, the accompanying examples provide practical demonstrations of the concepts discussed in the documentation.
+
+---
+
+## OTA at a Glance
+
+The following diagram illustrates the overall update lifecycle that will be explored throughout this repository.
+
+```text
+                 OTA Server
+                      │
+               Signed Update
+                      │
+          ┌───────────▼───────────┐
+          │   Download Manager    │
+          └───────────┬───────────┘
+                      │
+              Verify Signature
+                      │
+              Verify Integrity
+                      │
+                Install Update
+                      │
+               Mark Boot Target
+                      │
+                Reboot Device
+                      │
+             Bootloader Decision
+             ┌─────────┴─────────┐
+             │                   │
+        Boot Success        Boot Failure
+             │                   │
+             ▼                   ▼
+         Commit Update      Rollback
+```
+
+Each stage of this process will be examined in detail in the chapters that follow.
+
+---
+
+## Contributing
+
+Contributions, suggestions, and discussions are welcome.
+
+If you have ideas for improvements, additional examples, or alternative approaches, feel free to open an issue or submit a pull request.
+
+---
+
+## License
+
+This repository is released under the MIT License.
+
+See the LICENSE file for details.