From f55ed6bf45b3523b2b5976aed79a1dc945d8b889 Mon Sep 17 00:00:00 2001 From: archipelago Date: Fri, 7 Aug 2026 19:41:20 -0400 Subject: [PATCH] docs(architecture): correct the "apps run as Quadlet units" overstatement MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The overview stated apps install as user.slice Quadlet units. Verified against prod_orchestrator.rs: use_quadlet_backends defaults to false, so regular apps install via the raw podman path today; the companion UI containers are the ones that run as Quadlet units (companion.rs owns them), and the Quadlet flip to default for all apps is opt-in/held. Reworded both places (the layer diagram and the App Platform section) to match reality and the container-lifecycle / quadlet-compilation dev docs: the orchestrator owns and self-heals app containers; companion UIs run as Quadlet units, the validated path being flipped to default. Everything else in the doc verified accurate — crate table, module map, data paths, security model, and the note that the four orphan crates still exist. Co-Authored-By: Claude Opus 5 (1M context) --- docs/architecture.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index 06e493f3..8c6e19e1 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -29,8 +29,8 @@ │ Podman REST API socket + systemd Quadlet units ┌──────────────────────┴───────────────────────────────┐ │ ROOTLESS PODMAN CONTAINERS │ -│ 50+ manifest-driven apps as user.slice Quadlet │ -│ units — survive backend restarts, self-heal │ +│ 50+ manifest-driven apps the orchestrator owns and │ +│ self-heals; companion UIs run as systemd Quadlet │ └──────────────────────────────────────────────────────┘ ┌──────────────────────────────────────────────────────┐ @@ -104,9 +104,11 @@ never appear in `podman inspect` or unit files), `generated_secrets` / `generated_certs` (self-healing), `network_aliases`, `data_uid`, and allow-listed `post_install` hooks that run inside the app's own sandbox. -**Install** compiles the manifest to a rootless **Quadlet unit under -`user.slice`** — containers survive backend restarts and reboots. -Multi-container apps (BTCPay, Mempool, Immich, NetBird, IndeeHub) are sets of +**Install** creates a rootless container the orchestrator owns; the companion +UI containers run as systemd **Quadlet units under `user.slice`** (the +validated path being flipped to default for all apps), so those survive backend +restarts and reboots outright, and the reconciler rebuilds any container that +vanishes. Multi-container apps (BTCPay, Mempool, Immich, NetBird, IndeeHub) are sets of per-member manifests installed via the stack orchestrator on an app-local network with readiness gates and generated cross-service secrets. A level-triggered **boot reconciler** converges actual state to desired state