Modak-Labs · addu390 · Aug 15, 2026 · Aug 15, 2026
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -5,6 +5,9 @@ on:
     branches: [main]
     paths:
       - "docs/**"
+      - "server/openapi.yml"
+      - "frontend/ds/openapi.yml"
+      - "frontend/s2/openapi.yml"
       - ".github/workflows/docs.yml"
   workflow_dispatch:
 

diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -1,4 +1,6 @@
 import { defineConfig } from 'vitepress';
+import { useSidebar } from 'vitepress-openapi';
+import { adminSpec, dsSpec, s2Spec } from './specs';
 
 function sideItem(label: string, link: string, path: string) {
   return {
@@ -7,6 +9,102 @@ function sideItem(label: string, link: string, path: string) {
   };
 }
 
+function operationItems(spec: object, prefix: string) {
+  return useSidebar({ spec, linkPrefix: prefix })
+    .generateSidebarGroups({ linkPrefix: prefix })
+    .flatMap((group) => group.items ?? []);
+}
+
+const docsSidebar = [
+  sideItem(
+    'Introduction',
+    '/introduction',
+    '<path d="M6 4.5h9.5A2.5 2.5 0 0 1 18 7v13H8.5A2.5 2.5 0 0 0 6 17.5V4.5Z" stroke="currentColor" stroke-width="1.7"/><path d="M6 4.5A2.5 2.5 0 0 0 3.5 7v10.5A2.5 2.5 0 0 1 6 17.5" stroke="currentColor" stroke-width="1.7"/>',
+  ),
+  sideItem(
+    'Quickstart',
+    '/quickstart',
+    '<path d="M8 6.5v11l10-5.5L8 6.5Z" stroke="currentColor" stroke-width="1.7" stroke-linejoin="round"/>',
+  ),
+  sideItem(
+    'Benchmark',
+    '/benchmark',
+    '<path d="M3 16l5.2-5.2 3.6 3.6L21 5" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round"/>',
+  ),
+  {
+    ...sideItem(
+      'Protocol',
+      '/protocol',
+      '<path d="M5 8h14M5 12h14M5 16h9" stroke="currentColor" stroke-width="1.7" stroke-linecap="round"/><path d="M4 6.5h16v11H4z" stroke="currentColor" stroke-width="1.7"/>',
+    ),
+    collapsed: false,
+    items: [
+      {
+        ...sideItem(
+          'Durable Streams',
+          '/protocol/durable-streams',
+          '<path d="M4 12c2-4 4-4 6 0s4 4 6 0 4-4 4 0" stroke="currentColor" stroke-width="1.7" stroke-linecap="round"/>',
+        ),
+        collapsed: true,
+        items: operationItems(dsSpec, '/protocol/durable-streams/'),
+      },
+      {
+        ...sideItem(
+          'S2',
+          '/protocol/s2',
+          '<path d="M7 8h7.5a3.5 3.5 0 1 1 0 7H9.5a3.5 3.5 0 1 0 0 7H17" stroke="currentColor" stroke-width="1.7" stroke-linecap="round"/>',
+        ),
+        collapsed: true,
+        items: operationItems(s2Spec, '/protocol/s2/'),
+      },
+    ],
+  },
+  {
+    ...sideItem(
+      'Deployment',
+      '/deployment',
+      '<path d="M12 3v10M8 7l4-4 4 4" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round"/><path d="M5 14.5v3A2.5 2.5 0 0 0 7.5 20h9a2.5 2.5 0 0 0 2.5-2.5v-3" stroke="currentColor" stroke-width="1.7" stroke-linecap="round"/>',
+    ),
+    collapsed: false,
+    items: [
+      sideItem(
+        'AWS',
+        '/deployment/aws',
+        '<path d="M12 3.5 20 8v8l-8 4.5L4 16V8l8-4.5Z" stroke="currentColor" stroke-width="1.7" stroke-linejoin="round"/><path d="M12 12v8.5M12 12 4 8M12 12l8-4" stroke="currentColor" stroke-width="1.7" stroke-linecap="round"/>',
+      ),
+      sideItem(
+        'Fly.io',
+        '/deployment/fly',
+        '<path d="M5 19L20 12L5 5l4.2 7L5 19Z" stroke="currentColor" stroke-width="1.7" stroke-linejoin="round"/><path d="M9.2 12H20" stroke="currentColor" stroke-width="1.7" stroke-linecap="round"/>',
+      ),
+    ],
+  },
+  {
+    ...sideItem(
+      'Operations',
+      '/operations',
+      '<path d="M4 8h16M4 16h16M9 5v6M15 13v6" stroke="currentColor" stroke-width="1.7" stroke-linecap="round"/>',
+    ),
+    collapsed: false,
+    items: [
+      sideItem(
+        'Durability',
+        '/operations/durability',
+        '<path d="M12 3.5 19 7v5.5c0 4.2-2.8 7.4-7 8.5-4.2-1.1-7-4.3-7-8.5V7l7-3.5Z" stroke="currentColor" stroke-width="1.7" stroke-linejoin="round"/>',
+      ),
+      {
+        ...sideItem(
+          'Admin',
+          '/operations/api',
+          '<path d="M8 7h8M8 12h8M8 17h5" stroke="currentColor" stroke-width="1.7" stroke-linecap="round"/><path d="M5 5h14v14H5z" stroke="currentColor" stroke-width="1.7"/>',
+        ),
+        collapsed: true,
+        items: operationItems(adminSpec, '/operations/api/'),
+      },
+    ],
+  },
+];
+
 export default defineConfig({
   title: 'Stream Stack',
   description: 'A durable stream engine on object storage.',
@@ -16,6 +114,11 @@ export default defineConfig({
   srcDir: 'pages',
   vite: {
     publicDir: 'assets',
+    server: {
+      fs: {
+        allow: ['..'],
+      },
+    },
   },
   markdown: {
     theme: 'github-dark',
@@ -35,43 +138,7 @@ export default defineConfig({
       { text: 'Home', link: '/' },
       { text: 'Docs', link: '/introduction' },
     ],
-    sidebar: [
-      sideItem(
-        'Introduction',
-        '/introduction',
-        '<path d="M6 4.5h9.5A2.5 2.5 0 0 1 18 7v13H8.5A2.5 2.5 0 0 0 6 17.5V4.5Z" stroke="currentColor" stroke-width="1.7"/><path d="M6 4.5A2.5 2.5 0 0 0 3.5 7v10.5A2.5 2.5 0 0 1 6 17.5" stroke="currentColor" stroke-width="1.7"/>',
-      ),
-      sideItem(
-        'Quickstart',
-        '/quickstart',
-        '<path d="M8 6.5v11l10-5.5L8 6.5Z" stroke="currentColor" stroke-width="1.7" stroke-linejoin="round"/>',
-      ),
-      sideItem(
-        'Benchmark',
-        '/benchmark',
-        '<path d="M3 16l5.2-5.2 3.6 3.6L21 5" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round"/>',
-      ),
-      {
-        ...sideItem(
-          'Deployment',
-          '/deployment',
-          '<path d="M12 3v10M8 7l4-4 4 4" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round"/><path d="M5 14.5v3A2.5 2.5 0 0 0 7.5 20h9a2.5 2.5 0 0 0 2.5-2.5v-3" stroke="currentColor" stroke-width="1.7" stroke-linecap="round"/>',
-        ),
-        collapsed: false,
-        items: [
-          sideItem(
-            'AWS',
-            '/deployment/aws',
-            '<path d="M12 3.5 20 8v8l-8 4.5L4 16V8l8-4.5Z" stroke="currentColor" stroke-width="1.7" stroke-linejoin="round"/><path d="M12 12v8.5M12 12 4 8M12 12l8-4" stroke="currentColor" stroke-width="1.7" stroke-linecap="round"/>',
-          ),
-          sideItem(
-            'Fly.io',
-            '/deployment/fly',
-            '<path d="M5 19L20 12L5 5l4.2 7L5 19Z" stroke="currentColor" stroke-width="1.7" stroke-linejoin="round"/><path d="M9.2 12H20" stroke="currentColor" stroke-width="1.7" stroke-linecap="round"/>',
-          ),
-        ],
-      },
-    ],
+    sidebar: docsSidebar,
     search: {
       provider: 'local',
     },
@@ -86,4 +153,9 @@ export default defineConfig({
       copyright: '© 2026 Modak Labs. Apache 2.0.',
     },
   },
+  transformPageData(pageData) {
+    if (pageData.params?.pageTitle) {
+      pageData.title = pageData.params.pageTitle;
+    }
+  },
 });
diff --git a/docs/.vitepress/specs.ts b/docs/.vitepress/specs.ts
@@ -0,0 +1,14 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+import { parseSpec } from 'vitepress-openapi';
+
+const streamstack = resolve(fileURLToPath(new URL('../..', import.meta.url)));
+
+function loadSpec(rel: string) {
+  return parseSpec(readFileSync(resolve(streamstack, rel), 'utf8'));
+}
+
+export const dsSpec = loadSpec('frontend/ds/openapi.yml');
+export const s2Spec = loadSpec('frontend/s2/openapi.yml');
+export const adminSpec = loadSpec('server/openapi.yml');
diff --git a/docs/.vitepress/theme/custom.css b/docs/.vitepress/theme/custom.css
@@ -234,14 +234,12 @@
 }
 
 .VPDoc h1 {
-  font-size: clamp(2.25rem, 5vw, 3.5rem);
-  line-height: 1.05;
+  font-size: clamp(1.7rem, 3vw, 2.05rem);
+  line-height: 1.15;
 }
 
-.vp-doc h2:first-of-type {
-  margin-top: 1.25rem;
-  padding-top: 0;
-  border-top: none;
+.vp-doc h2 {
+  margin-top: 2rem;
 }
 
 .vp-doc div[class*="language-"] {

diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts
@@ -1,11 +1,13 @@
 import DefaultTheme from 'vitepress/theme';
 import { h } from 'vue';
 import type { Theme } from 'vitepress';
+import { theme as openapiTheme } from 'vitepress-openapi/client';
 import ColorSwitch from './ColorSwitch.vue';
 import HeroDither from './HeroDither.vue';
 import HomeChips from './HomeChips.vue';
 import HomeBento from './HomeBento.vue';
 import SiteLogo from './SiteLogo.vue';
+import 'vitepress-openapi/dist/style.css';
 import './custom.css';
 
 export default {
@@ -21,4 +23,7 @@ export default {
         h('p', { class: 'ss-doc-copyright' }, '© 2026 Modak Labs. Apache 2.0.'),
     });
   },
+  enhanceApp({ app }) {
+    openapiTheme.enhanceApp({ app });
+  },
 } satisfies Theme;