From 32c9fd657028a9de6d50534455cf4b0094fc5e51 Mon Sep 17 00:00:00 2001 From: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com> Date: Tue, 7 Jul 2026 07:47:40 +0800 Subject: [PATCH] docs: convert ASCII flow/architecture diagrams to Mermaid Replace 17 hand-drawn ASCII diagrams with rendered Mermaid across the docs, using the site's existing Mermaid support. Directory trees, wire formats, grammar, and code blocks are deliberately left as monospace text (Mermaid can't represent them). - getting-started: the build-loop (index + build-with-claude-code recap) - concepts/architecture: the four usage-pattern flows - protocol: version-deprecation timeline, plugin-install state machine (stateDiagram-v2), Configuration-over-Code comparison (subgraphs), realtime sticky-session + Redis pub/sub topology - references: marketplace/app-store/developer-portal journeys, seed-loader and package-upgrade flows, the skills chain All diagrams verified rendering in the browser (flowchart, stateDiagram, subgraph, and bidirectional edges) with no Mermaid parse errors. Co-Authored-By: Claude Opus 4.8 --- content/docs/ai/skills-reference.mdx | 5 +++-- content/docs/concepts/architecture.mdx | 20 ++++++++++------- .../build-with-claude-code.mdx | 12 +++++----- content/docs/getting-started/index.mdx | 12 ++++++---- .../docs/protocol/backward-compatibility.mdx | 10 ++++----- content/docs/protocol/objectos/lifecycle.mdx | 17 +++++++++----- .../protocol/objectos/realtime-protocol.mdx | 22 +++++++++---------- content/docs/protocol/objectui/index.mdx | 16 +++++++++----- content/docs/references/cloud/app-store.mdx | 7 +++--- .../references/cloud/developer-portal.mdx | 7 +++--- content/docs/references/cloud/marketplace.mdx | 18 +++++---------- content/docs/references/data/seed-loader.mdx | 21 ++++++------------ .../references/kernel/package-upgrade.mdx | 21 ++++++------------ 13 files changed, 91 insertions(+), 97 deletions(-) diff --git a/content/docs/ai/skills-reference.mdx b/content/docs/ai/skills-reference.mdx index 928c3e5e10..c1cef10f81 100644 --- a/content/docs/ai/skills-reference.mdx +++ b/content/docs/ai/skills-reference.mdx @@ -216,8 +216,9 @@ Use the [Quick Reference](#quick-reference) table to find the skill that matches Most real-world work spans multiple domains. A typical CRM feature chains: -``` -Data → Query → UI → Automation → API +```mermaid +flowchart LR + Data --> Query --> UI --> Automation --> API ``` ### 3. Load Formula alongside its host diff --git a/content/docs/concepts/architecture.mdx b/content/docs/concepts/architecture.mdx index 653e6138d8..96f76184cf 100644 --- a/content/docs/concepts/architecture.mdx +++ b/content/docs/concepts/architecture.mdx @@ -622,30 +622,34 @@ Datasource Protocol (Connection Config) UI auto-generated from data definitions: -``` -Object → Field → View → Page → App +```mermaid +flowchart LR + Object --> Field --> View --> Page --> App ``` ### Pattern 2: Custom UI with Data Binding Custom UI connected to data: -``` -Page → Component → View (Custom) → Query → Object +```mermaid +flowchart LR + Page --> Component --> View["View (Custom)"] --> Query --> Object ``` ### Pattern 3: Automation & Integration Business logic automation: -``` -Object → Hook → Flow → Automation → API/Webhook +```mermaid +flowchart LR + Object --> Hook --> Flow --> Automation --> API["API / Webhook"] ``` ### Pattern 4: AI-Enhanced Applications AI capabilities on top of data: -``` -Object → RAG Pipeline → Agent → Conversation → UI +```mermaid +flowchart LR + Object --> RAG["RAG Pipeline"] --> Agent --> Conversation --> UI ``` diff --git a/content/docs/getting-started/build-with-claude-code.mdx b/content/docs/getting-started/build-with-claude-code.mdx index 4add949061..76d21a73b6 100644 --- a/content/docs/getting-started/build-with-claude-code.mdx +++ b/content/docs/getting-started/build-with-claude-code.mdx @@ -315,12 +315,12 @@ a client. ## Recap — where each guardrail sat -``` - describe ─▶ Claude authors ─▶ os validate ─▶ you verify in UI ─▶ iterate ─▶ MCP - │ │ │ - skills+AGENTS.md the gate rejects Console is the - taught the rules silent-runtime human review - up front mistakes loudly surface +```mermaid +flowchart LR + D["Describe"] --> A["Claude Code authors
skills + AGENTS.md taught the rules"] + A --> V["os validate
the gate rejects silent mistakes"] + V --> C["You verify in the UI
Console = the human review surface"] + C --> I["Iterate"] --> M["MCP
app is AI-operable"] ``` - **Skills + `AGENTS.md`** meant the agent authored to the protocol, not from diff --git a/content/docs/getting-started/index.mdx b/content/docs/getting-started/index.mdx index e7418e505a..da6e34d8f0 100644 --- a/content/docs/getting-started/index.mdx +++ b/content/docs/getting-started/index.mdx @@ -12,10 +12,14 @@ import { Database, Layout, Cog } from 'lucide-react'; ObjectStack is designed around one workflow: **an AI agent authors the app; you verify it in a visual UI; guardrails keep the agent from shipping mistakes.** -``` - describe ─▶ Claude Code authors ─▶ os validate ─▶ you verify in ─▶ iterate ─▶ MCP - in plain the typed metadata (the gate) the Console (app is - language AI-operable) +```mermaid +flowchart LR + A["Describe
in plain language"] --> B["Claude Code authors
the typed metadata"] + B --> G{"os validate
the gate"} + G -->|fails| B + G -->|passes| V["You verify in
the Console"] + V -->|iterate| A + V -->|ship| M["MCP — your app
is AI-operable"] ``` You say what you want; Claude Code (or Cursor, Copilot, …) writes the typed diff --git a/content/docs/protocol/backward-compatibility.mdx b/content/docs/protocol/backward-compatibility.mdx index 695c41e6b2..e7af5834ab 100644 --- a/content/docs/protocol/backward-compatibility.mdx +++ b/content/docs/protocol/backward-compatibility.mdx @@ -67,11 +67,11 @@ When a feature, schema property, or API is deprecated, ObjectStack follows a str ### Timeline Summary -``` -v3.2.0 → Feature deprecated (warning emitted) -v3.3.0 → Migration period continues -v3.4.0 → Migration period continues (minimum 2 minor releases) -v4.0.0 → Feature removed (earliest possible removal) +```mermaid +flowchart TD + A["v3.2.0 — feature deprecated (warning emitted)"] --> B["v3.3.0 — migration period continues"] + B --> C["v3.4.0 — migration continues (minimum 2 minor releases)"] + C --> D["v4.0.0 — feature removed (earliest possible removal)"] ``` diff --git a/content/docs/protocol/objectos/lifecycle.mdx b/content/docs/protocol/objectos/lifecycle.mdx index 04cc1a985d..965bf298ef 100644 --- a/content/docs/protocol/objectos/lifecycle.mdx +++ b/content/docs/protocol/objectos/lifecycle.mdx @@ -219,12 +219,17 @@ async function installPlugin(packageName: string, version: string) { A plugin progresses through these states: -``` -NOT_INSTALLED → DOWNLOADING → VALIDATING → INSTALLING → INSTALLED → ENABLED - ↓ ↓ ↓ - [ERROR] [ERROR] [ERROR] - ↓ ↓ ↓ - FAILED_DOWNLOAD FAILED_VALIDATION FAILED_INSTALL +```mermaid +stateDiagram-v2 + [*] --> NOT_INSTALLED + NOT_INSTALLED --> DOWNLOADING + DOWNLOADING --> VALIDATING + VALIDATING --> INSTALLING + INSTALLING --> INSTALLED + INSTALLED --> ENABLED + DOWNLOADING --> FAILED_DOWNLOAD: error + VALIDATING --> FAILED_VALIDATION: error + INSTALLING --> FAILED_INSTALL: error ``` ### Dependency Resolution diff --git a/content/docs/protocol/objectos/realtime-protocol.mdx b/content/docs/protocol/objectos/realtime-protocol.mdx index 25c4f64902..1de66e9423 100644 --- a/content/docs/protocol/objectos/realtime-protocol.mdx +++ b/content/docs/protocol/objectos/realtime-protocol.mdx @@ -641,11 +641,10 @@ Each connection consumes server resources. WebSocket connections are sticky sessions: -``` -Client → Load Balancer → Server A - (remembers) - -Client reconnects → Server A (same server) +```mermaid +flowchart LR + C["Client"] --> LB["Load Balancer
(remembers via session-ID cookie)"] --> S["Server A"] + C2["Client reconnects"] -.->|routed to same server| S ``` **Why sticky sessions:** @@ -657,13 +656,12 @@ Client reconnects → Server A (same server) For multi-server deployments, ObjectStack uses Redis pub/sub: -``` -Server A ←→ Redis Pub/Sub ←→ Server B - ↓ ↓ -Client 1 Client 2 - -# Data changes on Server A -Server A publishes to Redis → Server B receives → Client 2 gets update +```mermaid +flowchart LR + C1["Client 1"] --> SA["Server A"] + SA <-->|pub/sub| R["Redis Pub/Sub"] + R <-->|pub/sub| SB["Server B"] + SB --> C2["Client 2"] ``` **How it works:** diff --git a/content/docs/protocol/objectui/index.mdx b/content/docs/protocol/objectui/index.mdx index ade1737aa6..946bb1f3e2 100644 --- a/content/docs/protocol/objectui/index.mdx +++ b/content/docs/protocol/objectui/index.mdx @@ -354,12 +354,16 @@ ListView.create({ UI changes should **never** require rebuilding: -``` -Traditional: Change Code → Build → Test → Deploy → (iOS) App Store Wait - ────────────────────── 2-14 days ────────────────────────── - -ObjectUI: Change Config → Refresh Page - ───────── 5 seconds ───────── +```mermaid +flowchart LR + subgraph T["Traditional — 2–14 days"] + direction LR + C1["Change Code"] --> B1["Build"] --> Te1["Test"] --> D1["Deploy"] --> A1["(iOS) App Store wait"] + end + subgraph O["ObjectUI — 5 seconds"] + direction LR + C2["Change Config"] --> R2["Refresh Page"] + end ``` **Why:** Business requirements change daily. Code deployment cycles are weekly at best. diff --git a/content/docs/references/cloud/app-store.mdx b/content/docs/references/cloud/app-store.mdx index 0077cbc064..8ccccfb6ac 100644 --- a/content/docs/references/cloud/app-store.mdx +++ b/content/docs/references/cloud/app-store.mdx @@ -21,10 +21,9 @@ installing, and managing marketplace apps from within ObjectOS. ## Customer Journey -``` - -Discover → Evaluate → Install → Configure → Use → Rate/Review → Manage - +```mermaid +flowchart LR + Discover --> Evaluate --> Install --> Configure --> Use --> Rate["Rate / Review"] --> Manage ``` ## Key Concepts diff --git a/content/docs/references/cloud/developer-portal.mdx b/content/docs/references/cloud/developer-portal.mdx index 6dd328f84e..142a6c4ded 100644 --- a/content/docs/references/cloud/developer-portal.mdx +++ b/content/docs/references/cloud/developer-portal.mdx @@ -11,10 +11,9 @@ Defines schemas for the developer-facing side of the marketplace ecosystem. Covers the complete developer journey: -``` - -Register → Create App → Develop → Validate → Build → Submit → Monitor → Iterate - +```mermaid +flowchart LR + Register --> Create["Create App"] --> Develop --> Validate --> Build --> Submit --> Monitor --> Iterate ``` ## Architecture Alignment diff --git a/content/docs/references/cloud/marketplace.mdx b/content/docs/references/cloud/marketplace.mdx index 025b13d553..47ddbdc459 100644 --- a/content/docs/references/cloud/marketplace.mdx +++ b/content/docs/references/cloud/marketplace.mdx @@ -47,18 +47,12 @@ platform, and customers who install plugins. ## Platform Management Flow -``` - -1. Receive → Accept submissions from verified publishers - -2. Scan → Automated security scan and compatibility check - -3. Review → Human review for quality and policy compliance - -4. Catalog → Index in marketplace search catalog - -5. Monitor → Track installs, ratings, issues, and enforce SLAs - +```mermaid +flowchart LR + A["1 · Receive
accept submissions from verified publishers"] --> B["2 · Scan
automated security + compatibility check"] + B --> C["3 · Review
human review for quality + policy"] + C --> D["4 · Catalog
index in marketplace search"] + D --> E["5 · Monitor
track installs, ratings, issues, SLAs"] ``` diff --git a/content/docs/references/data/seed-loader.mdx b/content/docs/references/data/seed-loader.mdx index 6986738a48..cd479c7a1f 100644 --- a/content/docs/references/data/seed-loader.mdx +++ b/content/docs/references/data/seed-loader.mdx @@ -21,20 +21,13 @@ relationship resolution, dependency ordering, and multi-pass insertion. ## Loading Flow -``` - -1. Build object dependency graph from field metadata (lookup/master_detail) - -2. Topological sort → determine insert order (parents before children) - -3. Pass 1: Insert/upsert records, resolve references via externalId - -4. Pass 2: Fill deferred references (circular/delayed dependencies) - -5. Validate & report unresolved references - -6. Return structured result with per-object stats - +```mermaid +flowchart TD + A["1 · Build object dependency graph
from field metadata (lookup / master_detail)"] --> B["2 · Topological sort
→ insert order (parents before children)"] + B --> C["3 · Pass 1 — insert/upsert records,
resolve references via externalId"] + C --> D["4 · Pass 2 — fill deferred references
(circular / delayed dependencies)"] + D --> E["5 · Validate & report unresolved references"] + E --> F["6 · Return structured result
with per-object stats"] ``` diff --git a/content/docs/references/kernel/package-upgrade.mdx b/content/docs/references/kernel/package-upgrade.mdx index f1d3ca6423..ae99a8c1f0 100644 --- a/content/docs/references/kernel/package-upgrade.mdx +++ b/content/docs/references/kernel/package-upgrade.mdx @@ -25,20 +25,13 @@ and rollback capabilities. ## Upgrade Flow -``` - -1. PreCheck → Validate compatibility, check dependencies - -2. Plan → Generate upgrade plan with metadata diff - -3. Snapshot → Backup current state (metadata + customizations) - -4. Execute → Apply new package metadata with 3-way merge - -5. Validate → Run post-upgrade health checks - -6. Commit → Finalize upgrade (or Rollback on failure) - +```mermaid +flowchart LR + A["1 · PreCheck
validate compatibility, deps"] --> B["2 · Plan
upgrade plan + metadata diff"] + B --> C["3 · Snapshot
backup metadata + customizations"] + C --> D["4 · Execute
apply new metadata (3-way merge)"] + D --> E["5 · Validate
post-upgrade health checks"] + E --> F["6 · Commit
finalize (or Rollback on failure)"] ```