Refactor documentation structure for GraphQL, WebSocket, and SSE APIs

Author: mkjsix

_includes/docs-sidebar.html

@@ -59,10 +59,9 @@ <h3 class="mt-2">MongoDB REST API</h3>
 
   <div class="part">
     <a data-bs-toggle="collapse" href="#part3" role="button">
-      <h3 class="mt-2">GraphQL & WebSocket</h3>
+      <h3 class="mt-2">GraphQL API</h3>
     </a>
     <ul id="part3" class="collapse">
-      <li class="subsection fw-bold">GraphQL API</li>
       <li><a href="/docs/graphql/">Overview</a></li>
       <li><a href="/docs/graphql/tutorial"><strong>Tutorial</strong></a></li>
       <li><a href="/docs/graphql/getting-started">Getting Started</a></li>
@@ -73,14 +72,26 @@ <h3 class="mt-2">GraphQL & WebSocket</h3>
       <li><a href="/docs/graphql/complex-app-example">Advanced Example</a></li>
       <li><a href="/docs/graphql/n-plus-one">Performance</a></li>
       <li><a href="/docs/graphql/best-practices">Best Practices</a></li>
+    </ul>
+  </div>
 
-      <li class="subsection fw-bold mt-2">WebSocket API</li>
+  <div class="part">
+    <a data-bs-toggle="collapse" href="#part-websocket" role="button">
+      <h3 class="mt-2">WebSocket API</h3>
+    </a>
+    <ul id="part-websocket" class="collapse">
       <li><a href="/docs/websocket/">Overview</a></li>
       <li><a href="/docs/websocket/tutorial"><strong>Tutorial</strong></a></li>
       <li><a href="/docs/websocket/change-streams">Change Streams</a></li>
       <li><a href="/docs/websocket/variables">Variables</a></li>
+    </ul>
+  </div>
 
-      <li class="subsection fw-bold mt-2">SSE API</li>
+  <div class="part">
+    <a data-bs-toggle="collapse" href="#part-sse" role="button">
+      <h3 class="mt-2">SSE API</h3>
+    </a>
+    <ul id="part-sse" class="collapse">
       <li><a href="/docs/sse/">Overview</a></li>
       <li><a href="/docs/sse/tutorial"><strong>Tutorial</strong></a></li>
       <li><a href="/docs/sse/custom-service">Custom SseService</a></li>
@@ -239,7 +250,9 @@ <h3 class="mt-2">Reference</h3>
         const menuMapping = {
             'overview': 'part1',        // Foundations
             'mongodb': 'part2',         // MongoDB REST API
-            'graphql': 'part3',         // GraphQL & WebSocket
+            'graphql': 'part3',         // GraphQL API
+            'websocket': 'part-websocket', // WebSocket API
+            'sse': 'part-sse',          // SSE API
             'security': 'part4',        // Security
             'setup': 'part5',           // Deployment
             'framework': 'part6',       // Framework

docs/index.adoc

@@ -187,27 +187,27 @@ Choose the path that matches your goal:
 |link:/docs/foundations/quick-start[Quick Start] (15 min)
 
 |3
-|link:/docs/graphql-websocket/graphql/tutorial[GraphQL Tutorial] (30 min)
+|link:/docs/graphql/tutorial[GraphQL Tutorial] (30 min)
 
 |4
-|link:/docs/graphql-websocket/graphql/getting-started[Getting Started] (20 min)
+|link:/docs/graphql/getting-started[Getting Started] (20 min)
 
 |5
-|link:/docs/graphql-websocket/graphql/graphql-apps[GraphQL Apps] (20 min)
+|link:/docs/graphql/graphql-apps[GraphQL Apps] (20 min)
 
 |6
-|link:/docs/graphql-websocket/graphql/schema[Schema Design] (20 min)
+|link:/docs/graphql/schema[Schema Design] (20 min)
 
 |7
-|link:/docs/graphql-websocket/graphql/mappings[Mappings] (20 min)
+|link:/docs/graphql/mappings[Mappings] (20 min)
 
 |8
-|link:/docs/graphql-websocket/graphql/resolvers[Resolvers] (20 min)
+|link:/docs/graphql/resolvers[Resolvers] (20 min)
 |===
 
 **✓ You can now build GraphQL APIs with RESTHeart!**
 
-*Next steps:* Learn link:/docs/graphql-websocket/graphql/n-plus-one[Performance Optimization], study link:/docs/graphql-websocket/graphql/complex-app-example[Advanced Example], review link:/docs/graphql-websocket/graphql/best-practices[Best Practices]
+*Next steps:* Learn link:/docs/graphql/n-plus-one[Performance Optimization], study link:/docs/graphql/complex-app-example[Advanced Example], review link:/docs/graphql/best-practices[Best Practices]
 
 '''
 
@@ -225,37 +225,47 @@ Complete guide to the REST API - CRUD, queries, aggregations, transactions, and
 
 *Read this to use RESTHeart's MongoDB API without coding.*
 
-=== link:/docs/graphql-websocket/graphql/[Part 3: GraphQL & WebSocket APIs]
-GraphQL API for flexible queries and WebSocket API for real-time data.
+=== link:/docs/graphql/[Part 3: GraphQL API]
+GraphQL API for flexible queries and mutations on MongoDB.
 
-*Alternative APIs for specific use cases.*
+*Use when clients need to specify exactly the data shape they want.*
 
-=== link:/docs/security/overview[Part 4: Security]
+=== link:/docs/websocket/[Part 4: WebSocket API]
+Bidirectional real-time data streams backed by MongoDB change streams.
+
+*Use when clients need a persistent full-duplex connection.*
+
+=== link:/docs/sse/[Part 5: SSE API]
+Server-Sent Events for real-time server-push streams — both MongoDB change streams and custom plugin endpoints.
+
+*Use when clients only need to receive events (no client-to-server messages). Works over plain HTTP with native browser `EventSource` support and automatic reconnection.*
+
+=== link:/docs/security/overview[Part 6: Security]
 User management, authentication methods, authorization, and production security.
 
 *Essential for securing your APIs.*
 
-=== link:/docs/deployment/configuration[Part 5: Configuration & Deployment]
+=== link:/docs/deployment/configuration[Part 7: Configuration & Deployment]
 Configuration options, deployment scenarios, operations, and performance tuning.
 
 *Deploy RESTHeart to production.*
 
-=== link:/docs/framework/overview[Part 6: Extending RESTHeart]
+=== link:/docs/framework/overview[Part 8: Extending RESTHeart]
 Plugin development - Services, Interceptors, Providers, and Initializers.
 
 *Build custom functionality with the framework.*
 
-=== link:/docs/framework/overview[Part 7: Extending Security]
+=== link:/docs/framework/overview[Part 9: Extending Security]
 Develop custom authentication and authorization plugins.
 
 *Extend the security layer.*
 
-=== link:/docs/cloud/[Part 8: RESTHeart Cloud]
+=== link:/docs/cloud/[Part 10: RESTHeart Cloud]
 RESTHeart Cloud features, Sophia AI, and webhooks.
 
 *Use the managed cloud offering.*
 
-=== link:/docs/reference/faq[Part 9: Reference]
+=== link:/docs/reference/faq[Part 11: Reference]
 API reference, migration guides, FAQ, examples, and resources.
 
 *Quick reference and additional resources.*
@@ -307,15 +317,16 @@ API reference, migration guides, FAQ, examples, and resources.
 Hands-on guides to get you started:
 
 * link:/docs/mongodb-rest/tutorial[REST API Tutorial] - Learn the REST API through examples
-* link:/docs/graphql-websocket/graphql/tutorial[GraphQL Tutorial] - Build a GraphQL API
-* link:/docs/graphql-websocket/websocket/tutorial[WebSocket Tutorial] - Real-time data with WebSockets
+* link:/docs/graphql/tutorial[GraphQL Tutorial] - Build a GraphQL API
+* link:/docs/websocket/tutorial[WebSocket Tutorial] - Real-time data with WebSockets
+* link:/docs/sse/tutorial[SSE Tutorial] - Server-push streams over HTTP with MongoDB change streams
 * link:/docs/security/tutorial[Security Tutorial] - Set up authentication and authorization
 * link:/docs/framework/tutorial[Plugin Development Tutorial] - Build your first plugin
 
 == 🌟 Why RESTHeart?
 
 * **Zero Code Required** - Use MongoDB APIs out of the box
-* **Instant APIs** - REST, GraphQL, WebSocket for MongoDB
+* **Instant APIs** - REST, GraphQL, WebSocket, and SSE for MongoDB
 * **Secure by Default** - Built-in authentication and authorization
 * **Highly Extensible** - Simple plugin system in Java, Kotlin, or JavaScript
 * **High Performance** - Virtual threads for massive scalability

docs/sse/custom-service.adoc

@@ -2,7 +2,7 @@
 docs_version: 9
 title: Custom SseService Plugin
 layout: docs-adoc
-menu: graphql
+menu: sse
 applies_to: both
 ---
 

docs/sse/index.adoc

@@ -2,7 +2,7 @@
 docs_version: 9
 title: SSE API Overview
 layout: docs-adoc
-menu: graphql
+menu: sse
 applies_to: both
 ---
 

docs/sse/tutorial.adoc

@@ -2,7 +2,7 @@
 docs_version: 9
 title: "Tutorial: Change Streams over SSE"
 layout: docs-adoc
-menu: graphql
+menu: sse
 applies_to: both
 ---
 

docs/websocket/change-streams.adoc

@@ -2,7 +2,7 @@
 docs_version: 9
 title: Change streams
 layout: docs-adoc
-menu: graphql
+menu: websocket
 applies_to: both
 redirect_from:
   - /docs/graphql-websocket/websocket/change-streams

docs/websocket/index.adoc

@@ -2,7 +2,7 @@
 docs_version: 9
 title: WebSocket API Overview
 layout: docs-adoc
-menu: graphql
+menu: websocket
 applies_to: both
 redirect_from:
   - /docs/graphql-websocket/websocket/

docs/websocket/tutorial.adoc

@@ -2,7 +2,7 @@
 docs_version: 9
 title: WebSocket API Tutorial
 layout: docs-adoc
-menu: graphql
+menu: websocket
 liquid: true
 applies_to: both
 redirect_from:

docs/websocket/variables.adoc

@@ -2,7 +2,7 @@
 docs_version: 9
 title: Using Variables
 layout: docs-adoc
-menu: graphql
+menu: websocket
 applies_to: both
 redirect_from:
   - /docs/graphql-websocket/websocket/variables