Merge pull request 'adding arch docs' (#1) from oaz/arch into main

Reviewed-on: omarabdul3ziz/zosbuilder#1

arch.md

@@ -0,0 +1,65 @@
+## Arch
+
+![](./arch.png)
+
+## Components
+
+- **EFI Image**  
+  Minimal kernel providing a boot environment and network setup.
+
+- **Identity**  
+  Manages node lifecycle: registration, updates, and identity.
+
+- **Supervisor**  
+  Message router for registration procedures and authentication.
+
+- **Runners**  
+  Workers listening on a job queue to execute tasks like VM CRUD operations.
+
+- **SALs (System Abstraction Layers)**  
+  Wrappers around tools such as `cloud-hypervisor`, `btrfs`, and networking utilities.
+
+- **Coord (Coordinator)**  
+  Workflow manager that selects the supervisor and ensures task completion.
+
+- **Ledger**  
+  Centralized registration service for nodes, identity manager for users, and persistent store.
+
+- **Rhai Scripts**  
+  Minimal scripts to execute high-level operations like VM deployment.
+
+---
+
+## Node Lifecycle Flow
+
+1. Build and push the **EFI image** to the bootstrap system.  
+2. Bootstrap flashes the image on a USB stick or generates an iPXE image.  
+3. Once booted and network is set up, the **Identity Manager** triggers.  
+4. Identity Manager contacts the centralized control plane (**Ledger/Coord**) for registration.  
+5. Node state (identity and keys) is saved, and uptime reports are sent periodically.  
+
+---
+
+## Deployment Flow
+
+1. Client prepares a signed **Rhai script** with deployment specs, including loops and logic.  
+2. Script is sent to the **Coord**, which federates it to the relevant **Supervisor**, tracking execution and retries.  
+3. **Supervisor** verifies signatures, validates the script, and places jobs into the **Redis queue**.  
+4. Multiple **Runners** pick jobs from the queue and execute the corresponding **SALs**.
+
+---
+
+## Features and Workloads
+
+### Networking
+- Only Mycelium supported.  
+- No WireGuard/Yggdrasil/public overlays (public IPs only for gateway nodes).  
+
+### Workloads
+- Machines (VMs/containers)  
+- HeroDB  
+- Potential gateway support in the future (centralized Traefik)  
+- No QSFS/ZDB support  
+
+### Filesystem
+- Btrfs