From d3fd0f5cb132fa99c4d053831cb39be2ad8a8fc4 Mon Sep 17 00:00:00 2001
From: Ed Nielsen <ed@edcore.dk>
Date: Wed, 18 Mar 2026 21:25:21 +0100
Subject: [PATCH] docs: add architecture overview

---
 docs/architecture.md | 206 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 206 insertions(+)
 create mode 100644 docs/architecture.md

diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 0000000..f6cc436
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,206 @@
+# 🧠 Update Manager Architecture
+
+This document describes how Update Manager is structured internally and how data flows through the system.
+
+---
+
+## Overview
+
+Update Manager is a lightweight, SSH-based system for managing updates across multiple Linux hosts.
+
+It consists of two main layers:
+
+* **UI layer** – interactive menu (`update-manager-ui.sh`)
+* **Core engine** – update logic (`update-manager.sh`)
+
+The system is designed to be simple, transparent, and dependency-light.
+
+---
+
+## High-Level Flow
+
+```text
+User
+  ↓
+UI (update-manager-ui.sh)
+  ↓
+Core (update-manager.sh)
+  ↓
+SSH → Remote Hosts
+  ↓
+Results
+  ↓
+Logging (/opt/update-manager/log)
+  ↓
+UI / User
+```
+
+---
+
+## Components
+
+### UI Layer (`update-manager-ui.sh`)
+
+Responsible for:
+
+* Displaying menu (via `dialog`)
+* Handling user input
+* Managing hosts (add/remove/edit)
+* Providing access to logs
+* Delegating actions to core engine
+
+The UI does **not perform updates directly**.
+
+---
+
+### Core Engine (`update-manager.sh`)
+
+Responsible for:
+
+* Reading configuration
+* Parsing hosts file
+* Executing SSH commands
+* Checking for updates (`apt list --upgradable`)
+* Handling connection errors
+* Writing structured logs
+
+This is the **execution layer** of the system.
+
+---
+
+### Hosts Configuration
+
+File:
+
+```bash
+/opt/update-manager/hosts.conf
+```
+
+Format:
+
+```text
+name    ip    user
+```
+
+Example:
+
+```text
+lanx-www    172.16.5.140    ed
+lanx-ai     172.16.5.135    ed
+```
+
+Each line represents a target system accessed via SSH.
+
+---
+
+### Logging System
+
+Log file:
+
+```bash
+/opt/update-manager/log/update-manager.log
+```
+
+Log format:
+
+```text
+YYYY-MM-DD HH:MM:SS [LEVEL] host - message
+```
+
+Example:
+
+```text
+2026-03-18 20:45:01 [INFO] lanx-www - Checking updates
+2026-03-18 20:45:03 [OK] lanx-www - 3 updates available
+2026-03-18 20:45:05 [ERR] lanx-db - Connection failed
+```
+
+#### Log Levels
+
+* `INFO` – informational messages
+* `OK` – successful operations
+* `ERR` – errors or failures
+
+Logging is centralized and written locally.
+
+---
+
+## Execution Flow
+
+For each host:
+
+1. Read host entry from `hosts.conf`
+2. Establish SSH connection
+3. Execute:
+
+```bash
+apt list --upgradable
+```
+
+4. Parse output
+5. Determine:
+
+   * Up-to-date
+   * Updates available
+   * Connection failure
+6. Write result to:
+
+   * terminal output
+   * log file
+
+---
+
+## Configuration
+
+Primary config:
+
+```bash
+/etc/update-manager.conf
+```
+
+Fallback:
+
+```bash
+./update-manager.conf
+```
+
+Supported options:
+
+* `HOSTS_FILE`
+* `SSH_OPTIONS`
+
+---
+
+## Design Principles
+
+* **No agents** – uses standard SSH only
+* **Simple over complex** – minimal dependencies
+* **Transparent behavior** – everything is visible/logged
+* **CLI-first** – designed for terminal environments
+* **Modular growth** – prepared for future extensions
+
+---
+
+## Future Architecture Direction
+
+Planned extensions:
+
+* Plugin system (modular features)
+* Web interface (optional UI layer)
+* Notification system (alerts)
+* Metrics / monitoring
+* Integration with Lanx AI
+
+---
+
+## Summary
+
+Update Manager follows a clean separation:
+
+* UI = interaction
+* Core = execution
+* Config = data
+* Log = output
+
+This keeps the system predictable, debuggable, and easy to extend.
+