Skip to content

Commit 9479dd8

Browse files
os-zhuangclaude
os-zhuang
and
claude
authored
docs: convert ASCII flow/architecture diagrams to Mermaid (#2667)
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: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
1 parent 5bb7a65 commit 9479dd8

13 files changed

Lines changed: 91 additions & 97 deletions

File tree

‎content/docs/ai/skills-reference.mdx‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -216,8 +216,9 @@ Use the [Quick Reference](#quick-reference) table to find the skill that matches
216216

217217
Most real-world work spans multiple domains. A typical CRM feature chains:
218218

219-
```
220-
Data → Query → UI → Automation → API
219+
```mermaid
220+
flowchart LR
221+
Data --> Query --> UI --> Automation --> API
221222
```
222223

223224
### 3. Load Formula alongside its host

‎content/docs/concepts/architecture.mdx‎

Lines changed: 12 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -622,30 +622,34 @@ Datasource Protocol (Connection Config)
622622

623623
UI auto-generated from data definitions:
624624

625-
```
626-
Object → Field → View → Page → App
625+
```mermaid
626+
flowchart LR
627+
Object --> Field --> View --> Page --> App
627628
```
628629

629630
### Pattern 2: Custom UI with Data Binding
630631

631632
Custom UI connected to data:
632633

633-
```
634-
Page → Component → View (Custom) → Query → Object
634+
```mermaid
635+
flowchart LR
636+
Page --> Component --> View["View (Custom)"] --> Query --> Object
635637
```
636638

637639
### Pattern 3: Automation & Integration
638640

639641
Business logic automation:
640642

641-
```
642-
Object → Hook → Flow → Automation → API/Webhook
643+
```mermaid
644+
flowchart LR
645+
Object --> Hook --> Flow --> Automation --> API["API / Webhook"]
643646
```
644647

645648
### Pattern 4: AI-Enhanced Applications
646649

647650
AI capabilities on top of data:
648651

649-
```
650-
Object → RAG Pipeline → Agent → Conversation → UI
652+
```mermaid
653+
flowchart LR
654+
Object --> RAG["RAG Pipeline"] --> Agent --> Conversation --> UI
651655
```

‎content/docs/getting-started/build-with-claude-code.mdx‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -315,12 +315,12 @@ a client.
315315

316316
## Recap — where each guardrail sat
317317

318-
```
319-
describe ─▶ Claude authors ─▶ os validate ─▶ you verify in UI ─▶ iterate ─▶ MCP
320-
│ │ │
321-
skills+AGENTS.md the gate rejects Console is the
322-
taught the rules silent-runtime human review
323-
up front mistakes loudly surface
318+
```mermaid
319+
flowchart LR
320+
D["Describe"] --> A["Claude Code authors<br/>skills + AGENTS.md taught the rules"]
321+
A --> V["os validate<br/>the gate rejects silent mistakes"]
322+
V --> C["You verify in the UI<br/>Console = the human review surface"]
323+
C --> I["Iterate"] --> M["MCP<br/>app is AI-operable"]
324324
```
325325

326326
- **Skills + `AGENTS.md`** meant the agent authored to the protocol, not from

‎content/docs/getting-started/index.mdx‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -12,10 +12,14 @@ import { Database, Layout, Cog } from 'lucide-react';
1212
ObjectStack is designed around one workflow: **an AI agent authors the app; you
1313
verify it in a visual UI; guardrails keep the agent from shipping mistakes.**
1414

15-
```
16-
describe ─▶ Claude Code authors ─▶ os validate ─▶ you verify in ─▶ iterate ─▶ MCP
17-
in plain the typed metadata (the gate) the Console (app is
18-
language AI-operable)
15+
```mermaid
16+
flowchart LR
17+
A["Describe<br/>in plain language"] --> B["Claude Code authors<br/>the typed metadata"]
18+
B --> G{"os validate<br/>the gate"}
19+
G -->|fails| B
20+
G -->|passes| V["You verify in<br/>the Console"]
21+
V -->|iterate| A
22+
V -->|ship| M["MCP — your app<br/>is AI-operable"]
1923
```
2024

2125
You say what you want; Claude Code (or Cursor, Copilot, …) writes the typed

‎content/docs/protocol/backward-compatibility.mdx‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -67,11 +67,11 @@ When a feature, schema property, or API is deprecated, ObjectStack follows a str
6767

6868
### Timeline Summary
6969

70-
```
71-
v3.2.0 → Feature deprecated (warning emitted)
72-
v3.3.0 → Migration period continues
73-
v3.4.0 → Migration period continues (minimum 2 minor releases)
74-
v4.0.0 → Feature removed (earliest possible removal)
70+
```mermaid
71+
flowchart TD
72+
A["v3.2.0 — feature deprecated (warning emitted)"] --> B["v3.3.0 — migration period continues"]
73+
B --> C["v3.4.0 — migration continues (minimum 2 minor releases)"]
74+
C --> D["v4.0.0 — feature removed (earliest possible removal)"]
7575
```
7676

7777
<Callout type="warn">

‎content/docs/protocol/objectos/lifecycle.mdx‎

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -219,12 +219,17 @@ async function installPlugin(packageName: string, version: string) {
219219

220220
A plugin progresses through these states:
221221

222-
```
223-
NOT_INSTALLED → DOWNLOADING → VALIDATING → INSTALLING → INSTALLED → ENABLED
224-
↓ ↓ ↓
225-
[ERROR] [ERROR] [ERROR]
226-
↓ ↓ ↓
227-
FAILED_DOWNLOAD FAILED_VALIDATION FAILED_INSTALL
222+
```mermaid
223+
stateDiagram-v2
224+
[*] --> NOT_INSTALLED
225+
NOT_INSTALLED --> DOWNLOADING
226+
DOWNLOADING --> VALIDATING
227+
VALIDATING --> INSTALLING
228+
INSTALLING --> INSTALLED
229+
INSTALLED --> ENABLED
230+
DOWNLOADING --> FAILED_DOWNLOAD: error
231+
VALIDATING --> FAILED_VALIDATION: error
232+
INSTALLING --> FAILED_INSTALL: error
228233
```
229234

230235
### Dependency Resolution

‎content/docs/protocol/objectos/realtime-protocol.mdx‎

Lines changed: 10 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -641,11 +641,10 @@ Each connection consumes server resources.
641641

642642
WebSocket connections are sticky sessions:
643643

644-
```
645-
Client → Load Balancer → Server A
646-
(remembers)
647-
648-
Client reconnects → Server A (same server)
644+
```mermaid
645+
flowchart LR
646+
C["Client"] --> LB["Load Balancer<br/>(remembers via session-ID cookie)"] --> S["Server A"]
647+
C2["Client reconnects"] -.->|routed to same server| S
649648
```
650649

651650
**Why sticky sessions:**
@@ -657,13 +656,12 @@ Client reconnects → Server A (same server)
657656

658657
For multi-server deployments, ObjectStack uses Redis pub/sub:
659658

660-
```
661-
Server A ←→ Redis Pub/Sub ←→ Server B
662-
↓ ↓
663-
Client 1 Client 2
664-
665-
# Data changes on Server A
666-
Server A publishes to Redis → Server B receives → Client 2 gets update
659+
```mermaid
660+
flowchart LR
661+
C1["Client 1"] --> SA["Server A"]
662+
SA <-->|pub/sub| R["Redis Pub/Sub"]
663+
R <-->|pub/sub| SB["Server B"]
664+
SB --> C2["Client 2"]
667665
```
668666

669667
**How it works:**

‎content/docs/protocol/objectui/index.mdx‎

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -354,12 +354,16 @@ ListView.create({
354354

355355
UI changes should **never** require rebuilding:
356356

357-
```
358-
Traditional: Change Code → Build → Test → Deploy → (iOS) App Store Wait
359-
────────────────────── 2-14 days ──────────────────────────
360-
361-
ObjectUI: Change Config → Refresh Page
362-
───────── 5 seconds ─────────
357+
```mermaid
358+
flowchart LR
359+
subgraph T["Traditional — 2–14 days"]
360+
direction LR
361+
C1["Change Code"] --> B1["Build"] --> Te1["Test"] --> D1["Deploy"] --> A1["(iOS) App Store wait"]
362+
end
363+
subgraph O["ObjectUI — 5 seconds"]
364+
direction LR
365+
C2["Change Config"] --> R2["Refresh Page"]
366+
end
363367
```
364368

365369
**Why:** Business requirements change daily. Code deployment cycles are weekly at best.

‎content/docs/references/cloud/app-store.mdx‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -21,10 +21,9 @@ installing, and managing marketplace apps from within ObjectOS.
2121

2222
## Customer Journey
2323

24-
```
25-
26-
Discover → Evaluate → Install → Configure → Use → Rate/Review → Manage
27-
24+
```mermaid
25+
flowchart LR
26+
Discover --> Evaluate --> Install --> Configure --> Use --> Rate["Rate / Review"] --> Manage
2827
```
2928

3029
## Key Concepts

‎content/docs/references/cloud/developer-portal.mdx‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,10 +11,9 @@ Defines schemas for the developer-facing side of the marketplace ecosystem.
1111

1212
Covers the complete developer journey:
1313

14-
```
15-
16-
Register → Create App → Develop → Validate → Build → Submit → Monitor → Iterate
17-
14+
```mermaid
15+
flowchart LR
16+
Register --> Create["Create App"] --> Develop --> Validate --> Build --> Submit --> Monitor --> Iterate
1817
```
1918

2019
## Architecture Alignment

0 commit comments

Comments
 (0)