fleet/ARCHITECTURE.html

@@ -211,6 +211,19 @@
     text-align: center;
     overflow-x: auto;
   }
+  .diagram {
+    background: var(--paper);
+    border: 1px solid var(--rule);
+    border-radius: 8px;
+    padding: 1.2rem;
+    margin: 1.5rem 0;
+    overflow-x: auto;
+  }
+  .diagram img {
+    display: block;
+    width: 100%;
+    height: auto;
+  }
   hr {
     border: none;
     border-top: 1px solid var(--rule);
@@ -257,13 +270,13 @@ each layer adds one idea on top of the previous one.</p>
 
 <h2><span class="layer">Layer 0</span> One picture</h2>
 
-<p>Topologie physique. Tout ce qui n'est pas un humain ou un device
-tourne <b>dans le cluster Kubernetes</b> : Fleet Operator, NATS +
-JetStream, l'Auth Callout, Zitadel — tous des pods. Les devices
-(Raspberry Pi, VM, bare-metal) sont à l'extérieur, et se branchent
-sur NATS via la callout pour s'authentifier. Un opérateur pousse
-les déploiements depuis le haut via le dashboard ou <code>kubectl</code>;
-un sysadmin enrôle chaque device une fois en SSH.</p>
+<p>Physical topology. Everything that is not a human or an edge device
+runs <b>inside the Kubernetes cluster</b>: Fleet Operator, NATS +
+JetStream, the auth callout, and Zitadel — all as pods. Devices
+(Raspberry Pi, VM, bare-metal) live outside the cluster and connect to
+NATS through the callout-authenticated path. An operator pushes
+deployments from the top via the dashboard or <code>kubectl</code>; a
+sysadmin enrolls each device once over SSH.</p>
 
 <div class="mermaid">
 flowchart TB
@@ -278,7 +291,7 @@ flowchart TB
 
   subgraph CLUSTER [Kubernetes cluster &nbsp;k3d / OKD / any]
     direction LR
-    KAPI["Kubernetes Control Plane<br/><i>deployment.harmony</i>, <i>device.harmony</i> CRDs"]:::kube
+    KAPI["Kubernetes Control Plane<br/><i>Deployment</i> and <i>Device</i> CRDs"]:::kube
     OP["Harmony Fleet Operator<br/>reconciles CRDs ↔ KV"]:::kube
     KV[("NATS JetStream<br/>desired-state · device-info<br/>device-state · device-heartbeat")]:::bus
     CALLOUT["NATS Auth Callout"]:::auth
@@ -286,7 +299,7 @@ flowchart TB
 
     KAPI --- OP
     OP -- writes / watches KV --> KV
-    KV -- delegates auth --> CALLOUT
+    KV -- NATS delegates auth --> CALLOUT
     CALLOUT -- validates JWT --> ZITADEL
   end
 
@@ -447,7 +460,7 @@ sequenceDiagram
     <tr>
       <td><code>device-info</code></td>
       <td>Agent</td>
-      <td>Operator (reflects to <code>Device</code> CR)</td>
+      <td>Operator (watches; creates/patches <code>Device</code> CR)</td>
       <td><code>info.&lt;device&gt;</code></td>
       <td>Routing labels, inventory snapshot, agent version</td>
     </tr>
@@ -461,24 +474,12 @@ sequenceDiagram
   </tbody>
 </table>
 
-<div class="mermaid">
-flowchart LR
-  OP[Operator]
-  AG[Agent]
-  DS[(desired-state)]
-  ST[(device-state)]
-  IN[(device-info)]
-  HB[(device-heartbeat)]
-
-  OP -- writes --> DS
-  DS -- watches --> AG
-  AG -- writes --> ST
-  AG -- writes --> IN
-  AG -- writes --> HB
-  ST -- watches --> OP
-  IN -- reflects to Device CR --> OP
-  HB -. queries .- OP
-</div>
+<figure class="diagram">
+  <img
+    src="harmony-fleet-assets/layer-3-kv-buckets.svg"
+    alt="Layer 3 KV bucket data flow between the operator, NATS stores, and agent"
+  >
+</figure>
 
 <p>These four bucket names are <b>the contract</b> between agent and operator. They live in one place to keep cross-component drift from happening:</p>
 
@@ -551,8 +552,8 @@ sequenceDiagram
   <li>Drops the agent binary at <code>/usr/local/bin/fleet-agent</code>.</li>
   <li>Enables <code>fleet-agent.service</code> (systemd).</li>
   <li>Agent boots, connects to NATS with bearer token from the keyfile.</li>
-  <li>Agent publishes initial DeviceInfo into <code>device-info.&lt;device_id&gt;</code>.</li>
-  <li>Agent starts watching <code>desired-state.&lt;device_id&gt;.&gt;</code>.</li>
+  <li>Agent publishes initial DeviceInfo into the <code>device-info</code> bucket at key <code>info.&lt;device_id&gt;</code>.</li>
+  <li>Agent starts watching the <code>desired-state</code> bucket for keys matching <code>&lt;device_id&gt;.&gt;</code>.</li>
   <li>Agent answers <code>device-commands.&lt;device_id&gt;.ping</code>.</li>
 </ol>
 
@@ -590,7 +591,7 @@ flowchart TB
   OP <-->|in-cluster NATS| NATS
   NATS -. callout .- CO
   CO -. JWT introspect .- ZT
-  OP --- ZT
+  OP -. dashboard SSO / JWKS .- ZT
 </div>
 
 <hr>