docs: convert standard diagrams from draw.io PNGs to inline Mermaid

Gitea renders mermaid inline, so the flow/state/hierarchy/DAG diagrams move to text-in-markdown: auto-layout (removes the manual overlap-prone draw.io step), diffable source, no committed binaries, and a dark-text theme so labels stay legible. Keep draw.io PNGs only for the two complex bespoke diagrams (logical architecture, env2 topology) where pixel control still wins. All 24 mermaid blocks validated by rendering.
2026-06-01 00:23:00 -04:00
parent e3ca5ac0cf
commit 43228185b4
65 changed files with 848 additions and 2145 deletions
@@ -167,8 +167,55 @@ Keepalive settings are configurable via `CommunicationOptions`:

 ## Topology

-![communication-topology](diagrams/communication-topology.png)
-<!-- source: diagrams/communication-topology.drawio — edit, then re-export with export-drawio.sh -->
+```mermaid
+%%{init: {'theme':'base', 'themeVariables': {'textColor':'#111111','lineColor':'#555555','edgeLabelBackground':'#ffffff','fontSize':'15px'}}}%%
+flowchart LR
+    subgraph Central["Central Cluster"]
+        CCA["ClusterClient<br/>(command/control)"]
+        CCB["ClusterClient<br/>(command/control)"]
+        CCN["ClusterClient<br/>(command/control)"]
+        GRPCC["SiteStreamGrpcClient<br/>(real-time data)"]
+    end
+
+    subgraph SiteA["Site A Cluster"]
+        SACOMM["SiteCommunicationActor<br/>(via Receptionist)"]
+        SAGRPC["SiteStreamGrpcServer<br/>(Kestrel HTTP/2, port 8083)"]
+        SACC["ClusterClient to Central<br/>(CentralCommunicationActor)"]
+    end
+
+    subgraph SiteB["Site B Cluster"]
+        SBCOMM["SiteCommunicationActor<br/>(via Receptionist)"]
+        SBGRPC["SiteStreamGrpcServer"]
+    end
+
+    subgraph SiteN["Site N Cluster"]
+        SNCOMM["SiteCommunicationActor<br/>(via Receptionist)"]
+        SNGRPC["SiteStreamGrpcServer"]
+    end
+
+    CCA -->|command/control| SACOMM
+    CCB -->|command/control| SBCOMM
+    CCN -->|command/control| SNCOMM
+
+    SAGRPC -->|"gRPC stream (real-time data)"| GRPCC
+    SBGRPC -->|gRPC stream| GRPCC
+    SNGRPC -->|gRPC stream| GRPCC
+
+    SACC -.->|command/control| Central
+
+    NOTE["Sites do NOT communicate with each other.<br/>All inter-cluster communication flows through Central."]
+
+    classDef start fill:#d5e8d4,stroke:#82b366,color:#111111;
+    classDef proc fill:#dae8fc,stroke:#6c8ebf,color:#111111;
+    classDef dec fill:#fff2cc,stroke:#d6b656,color:#111111;
+    classDef alt fill:#e1d5e7,stroke:#9673a6,color:#111111;
+    classDef muted fill:#f5f5f5,stroke:#999999,color:#666666;
+    class CCA,CCB,CCN,SACOMM,SACC,SBCOMM,SNCOMM dec
+    class GRPCC,SAGRPC,SBGRPC,SNGRPC start
+    class NOTE muted
+    class Central proc
+    class SiteA,SiteB,SiteN alt
+```

 - Sites do **not** communicate with each other.
 - All inter-cluster communication flows through central.