Skip to content

lulufoo/lulu-board / skills/mermaid

mermaid

Verified

List Mermaid types, or draw an open catalog type and open it on the public viewer.

references/design/c4.md

View on GitHub
# c4

Keywords: `C4Context` / `C4Container` / `C4Component` / `C4Dynamic` / `C4Deployment`.
Invariant: one view level per diagram. Arrows are relationships, not next step.

Drawer renders through Pele. Properties edit Title. Source edits the body.
Change the first-line keyword to switch view level.

# C4 view levels

Three levels in v1. Level is the primary discriminator.
Within a level, pick **minimal** (default) or **rich**.

## How to choose a sample

1. Choose Context / Container / Component by what must be visible.
2. Use **minimal** for a quick boundary sketch.
3. Use **rich** when externals, `title`, and verb-phrase `Rel` labels matter.

## Disambiguation

| Need to show… | Level |
|---------------|-------|
| People and systems around *our* system | Context |
| Apps, DBs, queues inside one system | Container |
| Modules inside one container | Component |
| Classes / functions inside one component | Code (v1: defer) |

## Shared rules

1. Arrows are relationships (uses, calls, reads/writes), not “next step”.
2. Prefer Mermaid C4 dialect first; flowchart approximation only as fallback.
3. **rich** samples should keep: `title`, external systems when relevant,
   and `Rel(..., "动词短语")`.

---

## 1. Context

### minimal

```mermaid
C4Context
  title System Context — Example
  Person(user, "User", "Uses the product")
  System(app, "Example System", "Our system")
  System_Ext(mail, "Email", "Notifications")
  Rel(user, app, "Uses")
  Rel(app, mail, "Sends email")
```

### rich

```mermaid
C4Context
  title System Context — Workbench Agent 集成
  Person(user, "Workbench 用户", "在应用内发起 Agent 任务")
  System(wb, "Lulu Workbench", "桌面应用;本地 Host + UI")
  System_Ext(api, "Cloud Agents API", "创建/调度 Agent Run")
  System_Ext(vm, "Cloud Agent 环境", "托管执行;读写文件/工具")
  System_Ext(gh, "GitHub", "可选:clone / push / PR")
  System_Ext(mcp, "远程 MCP", "可选:外部工具")
  Rel(user, wb, "输入 prompt、查看结果")
  Rel(wb, api, "HTTPS + API Key")
  Rel(api, vm, "创建 Agent、调度 Run")
  Rel(vm, gh, "仓库读写(若配置)")
  Rel(vm, mcp, "MCP 调用(若配置)")
```

**Flowchart approximation (if C4 unsupported):**

```mermaid
flowchart LR
  user([User]) --> wb[Workbench]
  wb --> api[Cloud Agents API]
  api --> vm[Cloud VM]
  vm --> gh[GitHub]
  vm --> mcp[MCP]
```

---

## 2. Container

### minimal

```mermaid
C4Container
  title Containers — Example System
  Person(user, "User", "")
  System_Boundary(b, "Example System") {
    Container(web, "Web App", "React", "UI")
    Container(api, "API", "Host", "Commands")
    ContainerDb(db, "Store", "Files/SQLite", "SSOT")
  }
  Rel(user, web, "Uses")
  Rel(web, api, "Calls")
  Rel(api, db, "Reads/Writes")
```

### rich

Use multiple boundaries when a side path must stay visually isolated.

```mermaid
C4Container
  title Containers — 主链路与旁路门闩
  System_Boundary(main, "主工作流") {
    Container(facts, "facts 产物", "文件", "上游产出")
    Container(runner, "runner SKILL", "流程", "按维度执行探针")
    Container(dims, "dimension-defs", "文件集", "维度定义")
  }
  System_Boundary(gate, "旁路门闩") {
    Container(ctl, "fidelity control", "CLI", "init / paths / mark-passed")
    Container(state, "fidelity state", "文件", "旁路状态;不切入主评估态")
  }
  Container(next, "下游入口", "CLI", "依赖 gate=passed")
  Rel(facts, ctl, "init 绑定")
  Rel(ctl, state, "读写状态")
  Rel(dims, runner, "提供维度")
  Rel(runner, ctl, "汇报结果")
  Rel(ctl, next, "passed 后放行")
```

**Flowchart approximation:**

```mermaid
flowchart TB
  user([User]) --> web[Web App]
  subgraph sys["Example System"]
    web --> api[API]
    api --> db[(Store)]
  end
```

---

## 3. Component

### minimal

```mermaid
C4Component
  title Components — API container
  Container_Boundary(api, "API") {
    Component(cmd, "Commands", "TS/Rust", "Entry")
    Component(svc, "Services", "", "Domain logic")
    Component(store, "Store access", "", "Persistence")
  }
  Rel(cmd, svc, "Uses")
  Rel(svc, store, "Uses")
```

### rich

Fill technology + responsibility; show externals that inject or coexist.

```mermaid
C4Component
  title Components — Assistant Host
  Container_Boundary(host, "Assistant Host") {
    Component(api, "Binding API", "契约", "Set/Reset/回调形状")
    Component(state, "绑定态机", "Runtime", "bound / unbound")
    Component(exec, "执行管线", "Runtime", "对话与工具调度")
    Component(iso, "隔离边界", "Runtime", "按业务隔离会话")
    Component(corner, "角位编排", "Shell", "与既有入口共存")
  }
  System_Ext(biz, "业务域", "Tool Impl + Prompt;经 Set 注入")
  System_Ext(fab, "全局入口", "既有角位")
  Rel(biz, api, "Set / Reset / 回调")
  Rel(api, state, "应用 / 清空绑定")
  Rel(state, exec, "仅 bound 可执行")
  Rel(exec, iso, "使用隔离空间")
  Rel(corner, fab, "共存编排")
```

**Flowchart approximation:**

```mermaid
flowchart LR
  subgraph api["API"]
    cmd[Commands] --> svc[Services] --> store[Store access]
  end
```

---

## Anti-patterns

1. Mixing Context people with Component-level modules in one diagram.
2. Using decision diamonds or UI event labels — that belongs to `flowchart`.
3. Drawing every class/file at Component level (Code; defer in v1).
4. Inventing a fourth ad-hoc level name when Context/Container/Component fit.


---

## 4. Dynamic (minimal)

Keyword: `C4Dynamic`. Numbered interactions over time.

```mermaid
C4Dynamic
  title Dynamic — Example
  Person(user, "User", "Uses the product")
  System(app, "Example System", "Our system")
  RelIndex(1, user, app, "Opens")
  RelIndex(2, app, user, "Shows result")
```

---

## 5. Deployment (minimal)

Keyword: `C4Deployment`. Where containers run.

```mermaid
C4Deployment
  title Deployment — Example
  Deployment_Node(host, "Host", "Ubuntu") {
    Container(app, "App", "Runtime", "Serves requests")
  }
```
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 196kUpdated Claude CodeCodexVerifiedInstall