docs: add getting started overview

Author: strahe

.github/workflows/docs.yml

@@ -34,15 +34,12 @@ jobs:
           cache: pnpm
           cache-dependency-path: docs/pnpm-lock.yaml
 
-      - name: Install dependencies
-        run: pnpm --dir docs install --frozen-lockfile
-
       - name: Build docs
         env:
           VITEPRESS_SITE_URL: ${{ vars.VITEPRESS_SITE_URL }}
           VITEPRESS_BASE: ${{ vars.VITEPRESS_BASE }}
           VITEPRESS_GTAG_ID: ${{ vars.VITEPRESS_GTAG_ID }}
-        run: pnpm --dir docs run build
+        run: make docs-build
 
       - name: Configure Pages
         if: github.event_name == 'push' && github.ref == 'refs/heads/main' && vars.SKIP_DOCS_DEPLOY != 'true'

Makefile

@@ -12,7 +12,7 @@ LDFLAGS  := -X $(MODULE)/internal/buildinfo.Version=$(VERSION) \
             -X $(MODULE)/internal/buildinfo.Commit=$(COMMIT) \
             -X $(MODULE)/internal/buildinfo.Date=$(DATE)
 
-.PHONY: all build build-go test test-fast test-race test-docker-entrypoint lint fmt check verify-fast verify-race clean run ui-install ui-build ui-dev
+.PHONY: all build build-go docs-build test test-fast test-race test-docker-entrypoint lint fmt check verify-fast verify-race clean run ui-install ui-build ui-dev
 
 all: build
 
@@ -22,6 +22,10 @@ ui-install:
 ui-build: ui-install
 	cd ui && pnpm run build
 
+docs-build:
+	cd docs && pnpm install --frozen-lockfile
+	cd docs && pnpm run build
+
 build: ui-build build-go
 
 build-go:

README.md

@@ -1,28 +1,35 @@
-![SynapS3 dashboard](docs/assets/readme-dashboard.png)
-
 # SynapS3
 
 [![CI](https://github.com/strahe/SynapS3/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/strahe/SynapS3/actions/workflows/ci.yml)
 [![Package](https://img.shields.io/badge/package-GHCR-blue?logo=github)](https://github.com/strahe/SynapS3/pkgs/container/synaps3)
 [![Go Report](https://goreportcard.com/badge/github.com/strahe/synaps3)](https://goreportcard.com/report/github.com/strahe/synaps3)
 [![Go Version](https://img.shields.io/github/go-mod/go-version/strahe/SynapS3?filename=go.mod)](go.mod)
 
-SynapS3 is an open-source, self-hosted S3-compatible gateway for storing objects on Filecoin.
+SynapS3 is an open-source, self-hosted S3-compatible gateway for Filecoin storage.
 
 ## Documentation
 
-- [Documentation](https://synaps3.strahe.com/)
+- [Documentation](https://synaps3.strahe.com/en/)
 - [中文文档](https://synaps3.strahe.com/zh/)
 
 ## Highlights
 
-- S3-compatible bucket and object APIs.
-- Filecoin-backed object storage through storage providers.
-- Open-source, self-hosted deployment with Docker or source builds.
-- Admin-authenticated dashboard for buckets, objects, wallet, tasks, topology, settings, and health.
-- Multipart uploads for large objects.
-- Wallet funding, USDFC deposit, and background task controls.
-- Coming soon: automatic replica repair when storage providers become unavailable.
+- S3-compatible bucket, object, versioning, and multipart APIs.
+- Cache-first reads and writes, with Filecoin upload handled in the background.
+- Admin dashboard for objects, wallet, tasks, topology, settings, and health.
+- Docker Compose or source build for single-node deployments.
+
+Coming soon: replica repair for provider outages.
+
+## Dashboard
+
+![SynapS3 dashboard](docs/assets/readme-dashboard.png)
+
+## Architecture
+
+![SynapS3 architecture](docs/public/architecture-overview.svg)
+
+Writes commit to local cache and metadata before returning success. Reads use local cache first, then committed Filecoin copies when available.
 
 ## Core S3 Compatibility
 
@@ -39,7 +46,7 @@ SynapS3 is an open-source, self-hosted S3-compatible gateway for storing objects
 | Object | `HeadObject` | ✅ | Reads object metadata |
 | Object | `DeleteObject` | ✅ | Creates a delete marker, or deletes a specific `versionId` |
 | Object | `DeleteObjects` | ✅ | Creates delete markers, or deletes specific `versionId` entries |
-| Object | `CopyObject` | ✅ | Source object must be readable from cache or committed provider storage |
+| Object | `CopyObject` | ✅ | Source object must be readable from cache or committed Filecoin storage |
 | Object | `ListObjects` | ✅ | Marker pagination |
 | Object | `ListObjectsV2` | ✅ | Continuation-token pagination |
 | Object | `ListObjectVersions` | ✅ | Lists object versions and delete markers |

docs/.vitepress/config.ts

@@ -49,14 +49,14 @@ gtag('config', ${encodedGtagId});`,
 }
 
 const enNav: DefaultTheme.NavItem[] = [
-  { text: 'Get Started', link: '/en/getting-started/quick-start' },
+  { text: 'Get Started', link: '/en/getting-started/overview' },
   { text: 'Deploy', link: '/en/getting-started/docker' },
   { text: 'Operate', link: '/en/operations/production-checklist' },
   { text: 'Reference', link: '/en/reference/s3-compatibility' },
 ]
 
 const zhNav: DefaultTheme.NavItem[] = [
-  { text: '入门', link: '/zh/getting-started/quick-start' },
+  { text: '入门', link: '/zh/getting-started/overview' },
   { text: '部署', link: '/zh/getting-started/docker' },
   { text: '运维', link: '/zh/operations/production-checklist' },
   { text: '参考', link: '/zh/reference/s3-compatibility' },
@@ -66,7 +66,7 @@ const enSidebar: DefaultTheme.Sidebar = [
   {
     text: 'Getting Started',
     items: [
-      { text: 'Overview', link: '/en/' },
+      { text: 'Overview', link: '/en/getting-started/overview' },
       { text: 'Quick Start', link: '/en/getting-started/quick-start' },
       { text: 'S3 Clients', link: '/en/getting-started/s3-clients' },
     ],
@@ -112,7 +112,7 @@ const zhSidebar: DefaultTheme.Sidebar = [
   {
     text: '入门',
     items: [
-      { text: '概览', link: '/zh/' },
+      { text: '概览', link: '/zh/getting-started/overview' },
       { text: '快速开始', link: '/zh/getting-started/quick-start' },
       { text: 'S3 客户端', link: '/zh/getting-started/s3-clients' },
     ],
@@ -154,6 +154,53 @@ const zhSidebar: DefaultTheme.Sidebar = [
   },
 ]
 
+type MarkdownFenceRenderer = (
+  tokens: Array<{ content: string; info: string; map: [number, number] | null }>,
+  idx: number,
+  options: unknown,
+  env: { path?: string; relativePath?: string } | undefined,
+  self: { renderToken: MarkdownFenceRenderer },
+) => string
+
+type MarkdownItLike = {
+  renderer: {
+    rules: {
+      fence?: MarkdownFenceRenderer
+    }
+  }
+}
+
+function stableHash(value: string) {
+  let hash = 0
+
+  for (let index = 0; index < value.length; index += 1) {
+    hash = Math.imul(31, hash) + value.charCodeAt(index)
+  }
+
+  return (hash >>> 0).toString(36)
+}
+
+function configureMermaidMarkdown(md: MarkdownItLike) {
+  const defaultFence = md.renderer.rules.fence
+
+  md.renderer.rules.fence = (tokens, idx, options, env, self) => {
+    const token = tokens[idx]
+    const language = token.info.trim().split(/\s+/, 1)[0]
+
+    if (language !== 'mermaid' && language !== 'mmd') {
+      return defaultFence
+        ? defaultFence(tokens, idx, options, env, self)
+        : self.renderToken(tokens, idx, options, env, self)
+    }
+
+    const source = `${env?.path || env?.relativePath || 'page'}:${idx}:${token.map?.join('-') || ''}`
+    const id = `mermaid-${stableHash(source)}`
+    const code = encodeURIComponent(token.content)
+
+    return `<ClientOnly><MermaidBlock id="${id}" code="${code}" /></ClientOnly>`
+  }
+}
+
 export default defineConfig({
   title: 'SynapS3',
   titleTemplate: ':title | SynapS3',
@@ -166,6 +213,9 @@ export default defineConfig({
     hostname: siteBaseUrl,
   },
   head,
+  markdown: {
+    config: configureMermaidMarkdown,
+  },
   transformPageData(pageData) {
     if (pageData.relativePath !== 'index.md') {
       return

docs/.vitepress/theme/MermaidBlock.vue

@@ -0,0 +1,76 @@
+<template>
+  <div class="mermaid-block">
+    <div v-if="error" class="mermaid-block__error">
+      <p>{{ error }}</p>
+      <pre>{{ decodedCode }}</pre>
+    </div>
+    <div v-else ref="container" class="mermaid-block__svg" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed, nextTick, onBeforeUnmount, onMounted, ref, watch } from 'vue'
+import { useData } from 'vitepress'
+
+const props = defineProps<{
+  id: string
+  code: string
+}>()
+
+const { isDark } = useData()
+const container = ref<HTMLElement | null>(null)
+const error = ref('')
+const decodedCode = computed(() => decodeURIComponent(props.code))
+let renderVersion = 0
+
+async function renderDiagram() {
+  if (!container.value) {
+    return
+  }
+
+  const currentVersion = ++renderVersion
+  error.value = ''
+
+  try {
+    const mermaid = (await import('mermaid')).default
+
+    mermaid.initialize({
+      securityLevel: 'strict',
+      startOnLoad: false,
+      theme: isDark.value ? 'dark' : 'default',
+    })
+
+    const { svg } = await mermaid.render(`${props.id}-${currentVersion}`, decodedCode.value)
+
+    if (currentVersion === renderVersion && container.value) {
+      container.value.innerHTML = svg
+    }
+  } catch (renderError) {
+    if (currentVersion !== renderVersion || !container.value) {
+      return
+    }
+
+    container.value.innerHTML = ''
+    error.value = renderError instanceof Error ? renderError.message : String(renderError)
+  }
+}
+
+onMounted(() => {
+  void renderDiagram()
+})
+
+onBeforeUnmount(() => {
+  renderVersion += 1
+
+  if (container.value) {
+    container.value.innerHTML = ''
+  }
+})
+
+watch(
+  () => [props.code, isDark.value],
+  () => {
+    void nextTick(renderDiagram)
+  },
+)
+</script>

docs/.vitepress/theme/index.ts

@@ -1,6 +1,10 @@
 import DefaultTheme from 'vitepress/theme'
+import MermaidBlock from './MermaidBlock.vue'
 import './styles.css'
 
 export default {
   extends: DefaultTheme,
+  enhanceApp({ app }) {
+    app.component('MermaidBlock', MermaidBlock)
+  },
 }

docs/.vitepress/theme/styles.css

@@ -37,3 +37,60 @@
 .dark .VPHomeHero .image-src {
   box-shadow: 0 16px 48px rgb(0 0 0 / 36%);
 }
+
+.architecture-overview {
+  display: block;
+  width: 100%;
+  height: auto;
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+}
+
+.architecture-overview--dark {
+  display: none;
+}
+
+.dark .architecture-overview--light {
+  display: none;
+}
+
+.dark .architecture-overview--dark {
+  display: block;
+}
+
+.mermaid-block {
+  margin: 24px 0;
+  overflow-x: auto;
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  background: var(--vp-c-bg-soft);
+}
+
+.mermaid-block__svg {
+  min-width: min-content;
+  padding: 20px;
+}
+
+.mermaid-block__svg svg {
+  display: block;
+  max-width: 100%;
+  height: auto;
+  margin: 0 auto;
+}
+
+.mermaid-block__error {
+  padding: 16px;
+  color: var(--vp-c-danger-1);
+}
+
+.mermaid-block__error p {
+  margin: 0 0 12px;
+  font-weight: 600;
+}
+
+.mermaid-block__error pre {
+  margin: 0;
+  overflow-x: auto;
+  color: var(--vp-c-text-1);
+  white-space: pre;
+}