Add scope diagrams section with C4 Level 1 and Level 2 diagrams

lws10-core/diagrams/README.md

@@ -0,0 +1,62 @@
+# Diagrams
+
+The figures in this folder are generated from `../lws10-core.c4`, a
+[LikeC4](https://likec4.dev) model of the specification's architecture. Do not
+edit the `.svg` files directly — edit the `.c4` source and regenerate.
+
+None of the tooling below should be installed inside this repository. Everything
+is run from a separate folder on your own machine; only the resulting `.svg`
+files ever get committed here.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org) (for `npx`/`npm`)
+- [Graphviz](https://graphviz.org) — provides the `dot` command
+  ```bash
+  brew install graphviz        # macOS
+  apt-get install graphviz     # Debian/Ubuntu
+  ```
+
+No headless browser is required for this workflow — `dot` output goes straight
+to real vector SVG.
+
+## 1. Install LikeC4 (outside this repo)
+
+Set up a scratch folder somewhere outside the repo, e.g. under your home
+directory, and install LikeC4 there:
+
+```bash
+mkdir -p ~/tools/likec4-tooling && cd ~/tools/likec4-tooling
+npm init -y
+npm install likec4
+```
+
+You only need to do this once. Run every command below from inside
+`~/tools/likec4-tooling`.
+
+## 2. Generate `.dot` files from the model
+Your `lws-protocol` repo is at `/path/to/`
+```
+export DOTPATH=/path/to/lws-protocol
+```
+
+And we need to delete the index.dot because we don't need it.
+```bash
+npx likec4 gen dot $DOTPATH/lws10-core/diagrams
+rm $DOTPATH/lws10-core/diagrams/index.dot
+```
+
+This reads `lws10-core.c4` and writes one `.dot` file per view into `diagrams/`,
+named after the view id (e.g. `fig-container-diagram.dot`). These files carry the
+model's actual layout parameters and theme color.
+
+## 3. Render `.dot` → `.svg`
+
+```bash
+cd $DOTPATH
+for f in *.dot; do
+  dot -Tsvg "$f" -o "./$(basename "${f%.dot}").svg"
+done
+```
+
+This writes the SVGs directly into this `diagrams/` folder.

lws10-core/diagrams/fig-container-diagram.dot

@@ -0,0 +1,143 @@
+digraph {
+    graph [TBbalance=min,
+        bgcolor=transparent,
+        compound=true,
+        fontname=Arial,
+        fontsize=20,
+        labeljust=l,
+        labelloc=t,
+        layout=dot,
+        likec4_viewId="fig-container-diagram",
+        nodesep=1.528,
+        outputorder=nodesfirst,
+        pad=0.209,
+        rankdir=TB,
+        ranksep=1.667,
+        splines=spline
+    ];
+    node [color="#2563eb",
+        fillcolor="#3b82f6",
+        fontcolor="#eff6ff",
+        fontname=Arial,
+        penwidth=0,
+        shape=rect,
+        style=filled
+    ];
+    edge [arrowsize=0.75,
+        color="#8D8D8D",
+        fontcolor="#C9C9C9",
+        fontname=Arial,
+        fontsize=14,
+        penwidth=2,
+        style=""
+    ];
+    subgraph "cluster_lws-server" {
+        graph [color="#0d374e",
+            fillcolor="#0f4460",
+            label=<<FONT POINT-SIZE="11" COLOR="#b6ecf7b3"><B>LWS SERVER</B></FONT>>,
+            likec4_depth=2,
+            likec4_id="lws-server",
+            likec4_level=0,
+            margin=40,
+            style=filled
+        ];
+        subgraph "cluster_resource-server" {
+            graph [color="#0b3c57",
+                fillcolor="#0d4b6c",
+                label=<<FONT POINT-SIZE="11" COLOR="#b6ecf7b3"><B>RESOURCE SERVER</B></FONT>>,
+                likec4_depth=1,
+                likec4_id="lws-server.resource-server",
+                likec4_level=1,
+                margin=32,
+                style=filled
+            ];
+            storage [color="#0369a1",
+                fillcolor="#0284c7",
+                fontcolor="#f0f9ff",
+                height=2.5,
+                label=<<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="4"><TR><TD><FONT POINT-SIZE="20">Storage</FONT></TD></TR><TR><TD><FONT POINT-SIZE="15" COLOR="#B6ECF7">A set of hierarchically organized HTTP<BR/>resources managed per LWS conventions</FONT></TD></TR></TABLE>>,
+                likec4_id="lws-server.resource-server.storage",
+                likec4_level=2,
+                margin="0.223,0.223",
+                width=4.445];
+        }
+        "authorization-server" [color="#0369a1",
+            fillcolor="#0284c7",
+            fontcolor="#f0f9ff",
+            height=2.5,
+            label=<<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="4"><TR><TD><FONT POINT-SIZE="20">Authorization Server</FONT></TD></TR><TR><TD><FONT POINT-SIZE="15" COLOR="#B6ECF7">An OAuth 2.0 authorization server that issues<BR/>access tokens. MAY be an external system</FONT></TD></TR></TABLE>>,
+            likec4_id="lws-server.authorization-server",
+            likec4_level=1,
+            margin="0.223,0.223",
+            width=4.445];
+    }
+    "lws-client" [color="#0369a1",
+        fillcolor="#0284c7",
+        fontcolor="#f0f9ff",
+        height=2.5,
+        label=<<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="4"><TR><TD><FONT POINT-SIZE="20">LWS Client</FONT></TD></TR><TR><TD><FONT POINT-SIZE="15" COLOR="#B6ECF7">An HTTP client that complies with the LWS<BR/>Protocol</FONT></TD></TR></TABLE>>,
+        likec4_id="lws-client",
+        likec4_level=0,
+        margin="0.223,0.223",
+        width=4.445];
+    "lws-client" -> "authorization-server" [arrowhead=normal,
+        label=<<TABLE BORDER="0" CELLPADDING="3" CELLSPACING="0" BGCOLOR="#18191BA0"><TR><TD ALIGN="TEXT" BALIGN="LEFT"><FONT POINT-SIZE="14">requests access token</FONT></TD></TR></TABLE>>,
+        likec4_id="9zky4r",
+        style=solid];
+    "identity-provider" [color="#0369a1",
+        fillcolor="#0284c7",
+        fontcolor="#f0f9ff",
+        height=2.5,
+        label=<<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="4"><TR><TD><FONT POINT-SIZE="20">Identity Provider</FONT></TD></TR><TR><TD><FONT POINT-SIZE="15" COLOR="#B6ECF7">Confirms user identity and issues signed<BR/>credentials. MAY be an external system</FONT></TD></TR></TABLE>>,
+        likec4_id="identity-provider",
+        likec4_level=0,
+        margin="0.223,0.223",
+        width=4.445];
+    "lws-client" -> "identity-provider" [arrowhead=normal,
+        label=<<TABLE BORDER="0" CELLPADDING="3" CELLSPACING="0" BGCOLOR="#18191BA0"><TR><TD ALIGN="TEXT" BALIGN="LEFT"><FONT POINT-SIZE="14">authenticates</FONT></TD></TR></TABLE>>,
+        likec4_id=ydrjak,
+        style=solid,
+        weight=2];
+    "lws-client" -> storage [arrowhead=normal,
+        lhead="cluster_resource-server",
+        likec4_id="1mtvne",
+        minlen=1,
+        style=solid,
+        xlabel=<<TABLE BORDER="0" CELLPADDING="3" CELLSPACING="0" BGCOLOR="#18191BA0"><TR><TD ALIGN="TEXT" BALIGN="LEFT"><FONT POINT-SIZE="14">sends request</FONT></TD></TR></TABLE>>];
+    "controlled-identifier" [color="#0369a1",
+        fillcolor="#0284c7",
+        fontcolor="#f0f9ff",
+        height=2.5,
+        label=<<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="4"><TR><TD><FONT POINT-SIZE="20">Controlled Identifier</FONT></TD></TR><TR><TD><FONT POINT-SIZE="15" COLOR="#B6ECF7">An identifier that is controlled by an agent<BR/>and used to identify the agent to the LWS<BR/>system</FONT></TD></TR></TABLE>>,
+        likec4_id="controlled-identifier",
+        likec4_level=0,
+        margin="0.223,0.223",
+        width=4.445];
+    "authorization-server" -> "controlled-identifier" [arrowhead=normal,
+        label=<<TABLE BORDER="0" CELLPADDING="3" CELLSPACING="0" BGCOLOR="#18191BA0"><TR><TD ALIGN="TEXT" BALIGN="LEFT"><FONT POINT-SIZE="14">verifies identity provider</FONT></TD></TR></TABLE>>,
+        likec4_id="19toz03",
+        style=solid];
+    "authorization-server" -> "identity-provider" [arrowhead=normal,
+        label=<<TABLE BORDER="0" CELLPADDING="3" CELLSPACING="0" BGCOLOR="#18191BA0"><TR><TD ALIGN="TEXT" BALIGN="LEFT"><FONT POINT-SIZE="14">validates credentials</FONT></TD></TR></TABLE>>,
+        likec4_id=lkcm0d,
+        style=solid];
+    agent [color="#525252",
+        fillcolor="#737373",
+        fontcolor="#fafafa",
+        height=2.5,
+        label=<<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="4"><TR><TD><FONT POINT-SIZE="20">Agent</FONT></TD></TR><TR><TD><FONT POINT-SIZE="15" COLOR="#d4d4d4">An agent of the LWS system</FONT></TD></TR></TABLE>>,
+        likec4_id=agent,
+        likec4_level=0,
+        margin="0.223,0.223",
+        width=4.445];
+    "controlled-identifier" -> agent [arrowhead=normal,
+        label=<<TABLE BORDER="0" CELLPADDING="3" CELLSPACING="0" BGCOLOR="#18191BA0"><TR><TD ALIGN="TEXT" BALIGN="LEFT"><FONT POINT-SIZE="14">identifies</FONT></TD></TR></TABLE>>,
+        likec4_id="123ygk7",
+        style=solid,
+        weight=2];
+    agent -> "lws-client" [arrowhead=normal,
+        label=<<TABLE BORDER="0" CELLPADDING="3" CELLSPACING="0" BGCOLOR="#18191BA0"><TR><TD ALIGN="TEXT" BALIGN="LEFT"><FONT POINT-SIZE="14">agent requests</FONT></TD></TR></TABLE>>,
+        likec4_id=u6f8pb,
+        style=solid,
+        weight=2];
+}