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

lws10-core/diagrams/lws10-core.c4

@@ -0,0 +1,122 @@
+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 {
+  agent = actor 'Agent' {
+    description 'An agent 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 controlled-identifier 'Controlled Identifier' {
+      description 'An identifier that is controlled by an agent and used to identify the agent to the LWS system'
+    }
+    component identity-provider 'Identity Provider' {
+      description 'Confirms user identity and issues signed credentials. MAY be an external system'
+    }
+    component lws-server 'LWS Server' {
+      description 'An HTTP server that complies with the LWS Protocol'
+
+      component authorization-server "Authorization Server" {
+        description 'An OAuth 2.0 authorization server that issues access tokens. MAY be an external system'
+      }
+      component resource-server 'Resource Server' {
+        description 'Manages data resources, containers, containment and linksets'
+      }
+      component storage 'Storage' {
+        description 'A set of hierarchically organized HTTP resources managed per LWS conventions'
+        style {
+          multiple true
+        }
+      }
+
+    }
+
+    agent -> lws-client 'agent requests'
+    controlled-identifier -> agent 'identifies'
+    lws-client -> lws-server 'HTTP requests'
+    lws-client -> identity-provider 'authenticates'
+    lws-client -> authorization-server 'requests access token'
+    lws-client -> resource-server 'sends request'
+    authorization-server -> controlled-identifier 'verifies identity provider'
+    authorization-server -> identity-provider 'validates credentials'
+  }
+//}
+
+views {
+
+  view fig-system-context {
+    title 'System Context Diagram'
+    include *
+  }
+
+  view fig-container-diagram of lws-server {
+    title 'Container Diagram'
+    autoLayout TopBottom
+    include *, identity-provider, agent
+    exclude storage
+  }
+
+  view fig-resource-server of resource-server {
+    title 'Resource Server Component Diagram'
+    autoLayout TopBottom
+    include *
+  }
+
+  view fig-storage of storage {
+    title 'LWS Resource Type Hierarchy'
+    autoLayout LeftRight
+    include *
+  }
+}

lws10-core/index.html

@@ -115,7 +115,29 @@ <h2>Document Conventions</h2>
     <section id="introduction">
       <h2>Introduction</h2>
       <p>
+        This specification defines the Linked Web Storage (LWS) Protocol, which enables client applications to access and manage web resources stored externally, based on the identity and permissions of the user.
       </p>
+      <p>
+        By standardising how an LWS server manages and provides access to a hierarchy of linked resources, the protocol enables users to use different LWS client applications to interact with the same stored data. These linked resources are defined through containers and containment relationships that describe where things are located, and metadata that describes how the resources relate to each other.
+      </p>
+      <p>
+        The protocol defines standard operations on these resources to create, read, update, and delete. Resources, their containment, and their metadata are managed by the server as a set of JSON-LD documents (and other representations). Each resource is identified by a URI. A client navigates the resource hierarchy from a root container, discovering contained resources and their relations through links provided in server responses.
+      </p>
+      <p>
+        A user's identity is confirmed through an identity provider that can be external to the Linked Web Storage server. This separation means the server does not manage credentials directly; rather, it receives and validates a signed authentication credential as a token issued by a trusted identity provider. A user can therefore present their existing identity to any compliant server, without needing a new or existing separate account on that server. User authentication is defined in companion specifications for OpenID Connect, SAML 2.0, and self-signed controlled identifiers (CIDs).
+      </p>
+      <p>
+        Authorization determines whether a requesting user has permission to access a resource or perform an operation on it. A compliant LWS server designates a resource manager for each resource that determines whether a resource is private (i.e., available only to its owner), restricted (i.e., available to a defined set of users), or public (i.e., available to any user). The server enforces the access decisions of the resource manager when handling each client request.
+      </p>
+      <p>This specification is intended to be used by:</p>
+      <ul>
+        <li>Developers building client applications that access a user's LWS resources</li>
+        <li>Server implementers building compliant LWS servers that mediate access to a user's web resources</li>
+      </ul>
+      <p>
+        Different compliant servers each maintain their own hierarchy of linked resources. A user can navigate across servers using the same identity, with access to each server's resources determined by the permissions granted by that servers resource managers.
+      </p>
+
 
       <section id="resource-access">
         <h2>Resource Access</h2>
@@ -155,11 +177,46 @@ <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: System Context shows the LWS System and its major pieces.
+        </p>
+        <figure id="fig-system-context">
+          <img src="diagrams/fig-system-context.png" 
+              alt="Figure: System Context shows the LWS System and its major pieces"/>
+          <figcaption>System Context (C4 Level 1)</figcaption>
+        </figure>
+
+        <p>
+          Figure: Container Diagram breaks out the LWS Server.
+        </p>
+        <figure id="fig-container-diagram">
+          <img src="diagrams/fig-container-diagram.png"
+              alt="Figure Container Diagram breaks out the LWS Server"/>
+          <figcaption>Container diagram (C4 Level 2)</figcaption>
+        </figure>
+
+        <p>
+          Figure: Resource Server (currently Storage Server in the spec)
+        </p>
+        <figure id="fig-resource-server">
+          <img src="diagrams/fig-resource-server.png"
+              alt="Figure Relationship of Resource Server to Storage"/>
+          <figcaption>Resource Server</figcaption>
+        </figure>
+
+      </section>
+
+    </section>
     <section id="terminology">
       <h2>Terminology</h2>
       <p>
@@ -203,7 +260,7 @@ <h2>Terminology</h2>
 
       <div class="issue atrisk" title="Section may be removed">
       <p>
-        This specification defines <a>operations</a> on <a>served resources</a>, the resulting change of state, and a <a>response</a> intended to give the <a>requesting agent</a> requested infomation or inform them of the outcome of the <a>operation</a>.
+        This specification defines <a>operations</a> on <a>served resources</a>, the resulting change of state, and a <a>response</a> intended to give the <a>requesting agent</a> requested information or inform them of the outcome of the <a>operation</a>.
         An <dfn>operation</dfn> is any of the following actions that can be performed on a <a>served resource</a>:
       </p>
       <ul>
@@ -214,7 +271,7 @@ <h2>Terminology</h2>
       </ul>
 
       <p>
-        The folowing section will describe the semantics and <dfn>responses</dfn> of these operations but the following <dfn>core responses</dfn> apply to any operation:
+        The following section will describe the semantics and <dfn>responses</dfn> of these operations but the following <dfn>core responses</dfn> apply to any operation:
       </p>
       <ul>
         <li><dfn>success</dfn> - the operation is believed to have completed. This may be accompanied by a <dfn>resource representation</dfn> conveying the contents of a <a>served resource</a>. A <a>success</a> response is not defined for the <a>create resource</a> operation. See instead <a href="#dfn-created">created</a>.</li>