Architecture

---

---

🧠 Architecture.md

# Architecture

This system is built around:

- systemd service + timer
- OverlayFS
- Stage-based state machine
- Cooldown window
- Watchdog fail-safe recovery

The goal is to guarantee:

- Safe upgrade
- SD card protection
- Automatic overlay recovery

---

## Core files

| File | Purpose |
|------|----------|
| overlay-auto-update.sh | Main controller |
| overlay-auto-update.timer | Weekly scheduler |
| overlay-auto-update.service | Controlled execution |
| STATE_FILE | Stage & cooldown bookmark |


## Work flow
                 ┌───────────────────┐
                 │   systemd timer   │
                 └─────────┬─────────┘　　　[STAGE2 guard]
                           |　      　　　　　- if DONE_AT exists -> cooldown
                           v
                      ┌────┴────┐
                      │ STAGE 0 │  (Overlay ON)
                      └────┬────┘
                           |
                disable overlay + reboot (systemd timer -> script rerun)
                           |
                           v
                      ┌────┴────┐
                      │ STAGE 1 │ (Overlay OFF)
                      └────┬────┘
                           |
                      apt upgrade
                           |
                      set_stage 2
                           |
                        reboot (systemd timer -> script rerun)
                           |
                           v
                      ┌────┴────┐
                      │ STAGE 2 │
                      └────┬────┘
                           |
        +------------------+------------------+
        |                                     |
    Overlay OFF                          Overlay ON
 restore overlay + reboot                  cleanup
        |
        v
   Normal mode