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

lws10-core/diagrams/figures.md

@@ -0,0 +1,64 @@
+# Figures
+
+A set of composition diagrams that models the [Linked Web Storage Protocol](https://w3c.github.io/lws-protocol/lws10-core/) specification.
+
+## Figure 1 - System Context Diagram
+
+Shows the LWS System as a single unit and the person who uses it. Establishes scope only — no internal structure is shown.
+
+![Fig. 1 - System Context](./fig1-system-context.png)
+
+| Box | Description |
+|---|---|
+| LWS User | A user of the LWS system |
+| LWS System | A system that implements the LWS Protocol |
+
+## Figure 2 - Container Diagram
+
+Breaks the LWS System into its primary elements.
+
+![Fig. 2 - Container](./fig2-container-diagram.png)
+
+| Box | Description |
+|---|---|
+| LWS User | A user of the LWS system |
+| LWS System | A system that implements the LWS Protocol |
+| LWS Client | An HTTP client that complies with the LWS Protocol |
+| LWS Server | An HTTP server that complies with the LWS Protocol |
+
+## Figure 3 - LWS Server Component Diagram
+
+Decomposition of the LWS Server into components and their responsibilities from client request to storage access.
+
+![Fig. 3 - LWS Server Component](./fig3-lws-server-components.png)
+
+| Box | Description |
+|---|---|
+| LWS Client | An HTTP client that complies with the LWS Protocol |
+| LWS Server | An HTTP server that complies with the LWS Protocol |
+| Resource Manager | Manages data resources, containers, containment and linksets |
+| Authentication | Validates credentials against the identity provider |
+| Authorization | Enforces resource manager access decisions |
+| Storage Controller | Controls all resources in the storage directed by its client resource-manager |
+| Identity Provider | Confirms user identity and issues signed credentials. MAY be an external system |
+| Storage | A set of hierarchically organized HTTP resources managed per LWS conventions |
+
+## Figure 4 - LWS Resource Type Hierarchy
+
+The resource type taxonomy and relationship defined in the specification's Terminology section.
+
+![Fig. 4 - Resource Type Hierarchy](./fig4-resource-hierarchy.png)
+
+| Box | Description |
+|---|---|
+| Resource Manager | Manages data resources, containers, containment and linksets |
+| Storage | A set of hierarchically organized HTTP resources managed per LWS conventions |
+| LWS Resource | An HTTP resource that supports the read operations defined by LWS |
+| Container | An LWS resource able to enumerate a collection of LWS resources; may recursively contain other containers |
+| Data Resource | A data-bearing LWS resource such as a document, image, or structured information |
+| Auxiliary Resource | An LWS resource whose lifetime is bound to a primary resource |
+| Linkset Resource | An auxiliary resource conforming to RFC9264 |
+| Metadata Resource | An auxiliary resource, managed by a storage, that describes an LWS resource |
+| Storage Root | The container at the root of a containment hierarchy of a storage |
+| Storage Description | Enumerates the storage root and the services/capabilities of a storage |
+

lws10-core/diagrams/lws10-core.c4

@@ -0,0 +1,161 @@
+specification {
+  element actor {
+    style {
+      shape person
+      color amber
+    }
+  }
+  element system {
+    style {
+      color blue
+      opacity 30%
+    }
+  }
+  element externalSystem {
+    style {
+      color secondary
+      opacity 30%
+    }
+  }
+  element component
+
+  element resource {
+    style {
+      shape document
+      color indigo
+    }
+  }
+
+  relationship isA {
+    color gray
+    line dashed
+    head none
+  }
+  relationship contains {
+    color gray
+    head diamond
+  }
+  relationship boundTo {
+    color gray
+    line dotted
+    head none
+  }
+  relationship describes {
+    color gray
+    line dotted
+  }
+  relationship manages
+
+  tag optional
+}
+
+model {
+  lws-user = actor 'LWS User' {
+    description 'A user of the LWS system'
+  }
+
+  lws = system 'LWS System' {
+    description 'A system that implements the LWS Protocol'
+    component lws-client 'LWS Client' {
+      description 'An HTTP client that complies with the LWS Protocol'
+    }
+    component lws-server 'LWS Server' {
+      description 'An HTTP server that complies with the LWS Protocol'
+
+      component identity-provider 'Identity Provider' {
+        #optional
+        description 'Confirms user identity and issues signed credentials. MAY be an external system'
+      }
+      component resource-manager 'Resource Manager' {
+        description 'Manages data resources, containers, containment and linksets'
+      }
+      component authentication 'Authentication' {
+        description 'Validates credentials against the identity provider'
+      }
+      component authorization 'Authorization' {
+        description 'Enforces resource manager access decisions'
+      }
+      component storage 'Storage' {
+        description 'A set of hierarchically organized HTTP resources managed per LWS conventions'
+
+        lws-resource = resource 'LWS Resource' {
+          description 'An HTTP resource that supports the read operations defined by LWS'
+        }
+        container = resource 'Container' {
+          description 'An LWS resource able to enumerate a collection of LWS resources; may recursively contain other containers'
+        }
+        data-resource = resource 'Data Resource' {
+          description 'A data-bearing LWS resource such as a document, image, or structured information'
+        }
+        auxiliary-resource = resource 'Auxiliary Resource' {
+          description 'An LWS resource whose lifetime is bound to a primary resource'
+        }
+        linkset-resource = resource 'Linkset Resource' {
+          description 'An auxiliary resource conforming to RFC9264'
+        }
+        metadata-resource = resource 'Metadata Resource' {
+          description 'An auxiliary resource, managed by a storage, that describes an LWS resource'
+        }
+        storage-root = resource 'Storage Root' {
+          description 'The container at the root of a containment hierarchy of a storage'
+        }
+        storage-description = resource 'Storage Description' {
+          description 'Enumerates the storage root and the services/capabilities of a storage'
+        }
+
+        container -[isA]-> lws-resource
+        data-resource -[isA]-> lws-resource
+        auxiliary-resource -[isA]-> lws-resource
+        linkset-resource -[isA]-> auxiliary-resource
+        metadata-resource -[isA]-> auxiliary-resource
+        storage-root -[isA]-> container
+        storage-description -[isA]-> lws-resource
+
+        container -[contains]-> data-resource 'contains'
+
+        auxiliary-resource -[boundTo]-> lws-resource 'bound to primary resource'
+        metadata-resource -[describes]-> lws-resource 'describes'
+        storage-description -[describes]-> storage-root 'enumerates & describes'
+      }
+
+      component storage-controller 'Storage Controller' {
+        description 'Controls all resources in the storage directed by its client resource-manager'
+      }
+    }
+
+    lws-user -> lws-client 'user requests'
+    lws-client -> lws-server 'HTTP requests'
+    lws-client -> identity-provider 'authenticates'
+    lws-client -> resource-manager 'sends request'
+    resource-manager -> authentication 'authenticates request'
+    authentication -> identity-provider 'validates credentials'
+    resource-manager -> authorization 'checks permission'
+    resource-manager -> storage-controller 'acts as client to'
+    storage-controller -> storage 'controls'
+    resource-manager -[manages]-> storage-root 'manages'
+  }
+}
+
+views {
+  view fig1-system-context {
+    title 'System Context Diagram'
+    include lws-user, lws
+  }
+
+  view fig2-container-diagram of lws {
+    title 'Container Diagram'
+    include *
+  }
+
+  view fig3-lws-server-components of lws-server {
+    title 'LWS Server Component Diagram'
+    autoLayout TopBottom
+    include *
+  }
+
+  view fig4-resource-hierarchy of storage {
+    title 'LWS Resource Type Hierarchy'
+    autoLayout LeftRight
+    include *
+  }
+}

lws10-core/index.html

@@ -168,11 +168,115 @@ <h2>Security and Privacy</h2>
         </p>
 
         <p>
-          A <dfn>LWS Client</dfn> is an HTTP client [[!rfc9112]] that complies with all of the relevant "MUST" statements in this specification. Specifically, the relevant normative "MUST" statements in <a href="#operations"></a> of this document MUST be respected.
+          An <dfn>LWS Client</dfn> is an HTTP client [[!rfc9112]] that complies with all of the relevant "MUST" statements in this specification. Specifically, the relevant normative "MUST" statements in <a href="#operations"></a> of this document MUST be respected.
         </p>
       </section>
-    </section>
 
+      <section id="scope-diagrams">    <!-- becomes 2.4 Scope Diagrams -->
+        <h2>Scope Diagrams</h2>
+        <p>
+          The following diagrams are platform-independent models 
+          to guide implementation.
+        </p>
+        <p>
+          Figure 1 System Context shows the LWS System as a single unit and the person who uses it.
+        </p>
+        <figure id="fig-1-system-context">
+          <img src="diagrams/fig1-system-context.png" 
+              alt="Figure 1 System Context shows the LWS System as a single unit and the person who uses it."/>
+          <figcaption>System Context (C4 Level 1)</figcaption>
+        </figure>
+        <p>
+          <table>
+            <thead>
+              <tr><th>Box</th><th>Description</th></tr>
+            </thead>
+            <tbody>
+              <tr><td>LWS User</td><td>A user of the LWS system</td></tr>
+              <tr><td>LWS System</td><td>A system that implements the LWS Protocol</td></tr>
+            </tbody>
+          </table>
+        </p>
+
+        <p>
+          Figure 2 Container Diagram breaks the LWS System into its primary elements.
+        </p>
+        <figure id="fig-2-container-diagram">
+          <img src="diagrams/fig2-container-diagram.png"
+              alt="Figure 2 Container Diagram breaks the LWS System into its primary elements."/>
+          <figcaption>Container diagram (C4 Level 2)</figcaption>
+        </figure>
+        <p>
+          <table>
+            <thead>
+              <tr><th>Box</th><th>Description</th></tr>
+            </thead>
+            <tbody>
+              <tr><td>LWS User</td><td>A user of the LWS system</td></tr>
+              <tr><td>LWS System</td><td>A system that implements the LWS Protocol</td></tr>
+              <tr><td>LWS Client</td><td>An HTTP client that complies with the LWS Protocol</td></tr>
+              <tr><td>LWS Server</td><td>An HTTP server that complies with the LWS Protocol</td></tr>
+            </tbody>
+          </table>
+        </p>
+
+        <p>
+          Figure 3 Component Diagram decomposition of the LWS Server into components and their responsibilities from client request to storage access.
+        </p>
+        <figure id="fig-3-lws-server-components">
+          <img src="diagrams/fig3-lws-server-components.png"
+              alt="Figure 3 Component Diagram decomposition of the LWS Server into components and their responsibilities from client request to storage access."/>
+          <figcaption>Component diagram (C4 Level 3)</figcaption>
+        </figure>
+        <p>
+          <table>
+            <thead>
+              <tr><th>Box</th><th>Description</th></tr>
+            </thead>
+            <tbody>
+              <tr><td>LWS Client</td><td>An HTTP client that complies with the LWS Protocol</td></tr>
+              <tr><td>LWS Server</td><td>An HTTP server that complies with the LWS Protocol</td></tr>
+              <tr><td>Resource Manager</td><td>Manages data resources, containers, containment and linksets</td></tr>
+              <tr><td>Authentication</td><td>Validates credentials against the identity provider</td></tr>
+              <tr><td>Authorization</td><td>Enforces resource manager access decisions</td></tr>
+              <tr><td>Storage Controller</td><td>Controls all resources in the storage, directed by its client resource-manager</td></tr>
+              <tr><td>Identity Provider</td><td>Confirms user identity and issues signed credentials. MAY be an external system</td></tr>
+              <tr><td>Storage</td><td>A set of hierarchically organized HTTP resources managed per LWS conventions</td></tr>
+            </tbody>
+          </table>          
+        </p>
+
+        <p>
+          Figure 4 Resource Types show taxonomy and relationship defined in the specification's Terminology section.
+        </p>
+        <figure id="fig-4-resource-hierarchy">
+          <img src="diagrams/fig4-resource-hierarchy.png"
+              alt="Figure 4 Resource Types show taxonomy and relationship defined in the specification's Terminology section."/>
+          <figcaption>Resource hierarchy</figcaption>
+        </figure>
+        <p>
+          <table>
+            <thead>
+              <tr><th>Box</th><th>Description</th></tr>
+            </thead>
+            <tbody>
+              <tr><td>Resource Manager</td><td>Manages data resources, containers, containment and linksets</td></tr>
+              <tr><td>Storage</td><td>A set of hierarchically organized HTTP resources managed per LWS conventions</td></tr>
+              <tr><td>LWS Resource</td><td>An HTTP resource that supports the read operations defined by LWS</td></tr>
+              <tr><td>Container</td><td>An LWS resource able to enumerate a collection of LWS resources; may recursively contain other containers</td></tr>
+              <tr><td>Data Resource</td><td>A data-bearing LWS resource such as a document, image, or structured information</td></tr>
+              <tr><td>Auxiliary Resource</td><td>An LWS resource whose lifetime is bound to a primary resource</td></tr>
+              <tr><td>Linkset Resource</td><td>An auxiliary resource conforming to RFC9264</td></tr>
+              <tr><td>Metadata Resource</td><td>An auxiliary resource, managed by a storage, that describes an LWS resource</td></tr>
+              <tr><td>Storage Root</td><td>The container at the root of a containment hierarchy of a storage</td></tr>
+              <tr><td>Storage Description</td><td>Enumerates the storage root and the services/capabilities of a storage</td></tr>
+            </tbody>
+          </table>          
+        </p>
+
+      </section>
+
+    </section>
     <section id="terminology">
       <h2>Terminology</h2>
       <p>