Приклади Mermaid-діаграм

Стенд із прикладами всіх типів діаграм які підтримує Quartz. Тримаємо для довідки — щоб коли треба намалювати щось, було видно який тип як виглядає і коли підходить.

Як писати: обгорнути код у fenced block з мовою mermaid. Все рендериться автоматично і в Obsidian (preview), і на сайті (Quartz).

Тип	Коли використовувати	Де ставимо
`flowchart` / `graph`	Мапа компонентів, потоків даних, залежностей. Заміна Canvas.	Початок індекс-сторінки сервісу
`sequenceDiagram`	Багатоетапний flow з 2+ учасниками: логін, обмін через RMQ, запит-відповідь	Сторінка-flow в `flows/`
`erDiagram`	Структура даних — поля, зв’язки між сутностями	Сторінки в `entities/`
`stateDiagram-v2`	Життєвий цикл, стани і переходи (інвайт: pending→sent→replied)	Сторінка ентіті або сервісу
`classDiagram`	Структура коду — класи і їх методи. Рідко варте, бо швидко старіє	Якщо реально треба показати ієрархію
`gantt`	Roadmap, план	Презентації, рідко в доці

1. Flowchart — мапа компонентів

Блоки і стрілки, з кліками на цільові сторінки. Це наш основний інструмент — заміна Canvas-нодів для веб-перегляду.

flowchart TB
    subgraph Frontend
        client[stack-client]
        electron[stack-electron]
    end

    stack[stack<br/>orchestrator + auth]

    subgraph "Domain backends"
        golden[stack-golden]
        prime[stack-prime]
        udate[stack-udate]
        chathouse[stack-chathouse]
    end

    subgraph "Окремі сервіси"
        academy[stack-academy]
        ai[stack-ai]
    end

    client --> stack
    electron --> stack
    electron -->|/electron-api| golden
    stack --> golden
    stack --> prime
    stack --> udate
    stack --> chathouse
    stack --> academy
    stack --> ai

    classDef done fill:#e3f2fd,stroke:#1976d2;
    classDef wip fill:#fff3e0,stroke:#f57c00;
    classDef todo fill:#fafafa,stroke:#9e9e9e;

    class electron,golden done;
    class client,stack wip;
    class prime,udate,chathouse,academy,ai todo;

    click electron "/services/electron/" "Stack Electron docs"
    click golden "/services/golden/" "Stack Golden docs"

Корисні patterns:

subgraph "Назва" — групування блоків (як group у Canvas)
[Title] — звичайний блок, (Title) — округлений, {Title} — ромб (рішення), {{Title}} — гексагон
click ID "/url" "tooltip" — клікабельна нода
classDef name fill:#col,stroke:#col; + class node1,node2 name; — стилі/кольори
--> — стрілка з підписом (-->|тригерить|), -.- — пунктир, === — товста
~~~ — повністю невидимий лінк (без лінії і без стрілки). Створює топологічний звʼязок (для розкладки), але візуально нічого не показує

1.1. N-колонкова мапа без стрілок

Коли треба показати каталог по категоріях (Сутності / Сервіси / System), а не потік даних — стрілки тільки шумлять. Робимо «німу» сітку колонок.

flowchart TB
    h_a["[Категорія A]"]:::header
    h_b["[Категорія B]"]:::header
    h_c["[Категорія C]"]:::header

    a1["A1"]
    a2["A2"]
    a3["A3"]

    b1["B1"]
    b2["B2"]
    b3["B3"]
    b4["B4"]

    c1["C1"]

    h_a ~~~ a1
    h_b ~~~ b1
    h_c ~~~ c1

    a1 ~~~ a2 ~~~ a3
    b1 ~~~ b2 ~~~ b3 ~~~ b4

    classDef header fill:transparent,stroke:transparent,stroke-width:8px,font-weight:bold

Як це працює:

flowchart TB (top-bottom) — натуральний потік згори вниз
Один header-нод на колонку (h_a, h_b, h_c) — це rank 0
Від кожного хедера ~~~ вниз → перший елемент колонки → стає rank 1
Далі ланцюг ~~~ усередині колонки — кожен наступний елемент opadає на наступний rank
Mermaid укладає всі ноди одного rank-у в горизонтальний ряд → колонки рівні з самого початку
Без cross-column лінків (a1 ~~~ b1) — створили б зайву залежність і зміщення

Чому саме так (грабельки які зловили):

direction TB усередині subgraph Quartz mermaid ігнорує. Subgraph не зробити вертикальним стовпчиком. Тому замість subgraph — голий ланцюг.
--> залишає стрілку навіть якщо linkStyle stroke:transparent — потрібен саме ~~~.
Header без рамки робиться через fill:transparent,stroke:transparent. Але stroke:none урізає текст до останнього символу — тому stroke:transparent + stroke-width:8px.
Кириличні слова з кінцевим символом типу і клипаються (mermaid недооцінює гліф з акцентом). Workaround: загорнути сам лейбл у квадратні дужки — ["[Назва]"]. Останній символ стає ] (ASCII, вузький), mermaid рахує правильно. Ще й виглядає як «тег/розділ».

2. Sequence — багатоетапний flow

Зверху вниз — час; учасники як стовпчики; стрілки — повідомлення.

sequenceDiagram
    actor Op as Оператор
    participant E as Electron
    participant S as stack
    participant G as Golden

    Op->>E: натискає Login
    E->>S: POST /login (email, password)
    S->>S: validate credentials
    S-->>E: JWT token
    E->>G: GET /electron-api/getOperatorLadies (з токеном)
    G-->>E: список TU оператора
    E-->>Op: відкривається Workspace

Patterns:

actor X as Назва — людина (з іконкою)
participant X as Назва — система
->> — синхронний виклик, -->> — відповідь, -x — невдача

3. ER — структура сутностей

Сутності і зв’язки. Особливо корисно для entities/.

erDiagram
    TU ||--o{ Invite : "має шаблони"
    RU ||--o{ Invite : "отримує"
    Invite }o--|| Sender : "розсилається через"
    TU ||--o{ Task : "має задачі"
    Operator ||--o{ TU : "працює від імені"

    TU {
        string ladyId
        string name
        int age
    }
    RU {
        string manId
        string name
        string country
    }
    Invite {
        string id
        date sentAt
        string status
        string text
    }
    Task {
        string id
        string type
        date deadline
    }

Cardinalities: || — один обов’язково, o| — нуль/один, }o — нуль/багато, }| — один/багато.

4. State — життєвий цикл

Стани і переходи. Для опису машинерії: статус інвайту, етап оператора.

stateDiagram-v2
    [*] --> Draft: створено в whitelist
    Draft --> Queued: додано в чергу сендера
    Queued --> Sent: sender відправив RU
    Sent --> Replied: RU відповів
    Sent --> Ignored: 24 год без відповіді
    Replied --> [*]
    Ignored --> [*]

    Draft --> Discarded: забраний з whitelist
    Discarded --> [*]

5. Class — ієрархія класів

Рідко корисно — код міняється швидше ніж діаграма. Тільки якщо ієрархія має бізнес-сенс і не очевидна з коду.

classDiagram
    class BaseController {
        +bindRoutes(routes)
        #ok(res, data)
        #next(error)
    }

    class ElectronApiController {
        +getOperatorLadies(query)
        +getFavorites(query)
        +sendLogFile(req)
        +downloadUpdate(res)
    }

    class StatisticsControllerV2 {
        +getStats(query)
        +exportReport(body)
    }

    class AdminController {
        +create(body)
        +edit(body)
        +list()
    }

    BaseController <|-- ElectronApiController
    BaseController <|-- StatisticsControllerV2
    BaseController <|-- AdminController

    note for ElectronApiController "routing-controllers,&#xA;guard([operator])"

6. Gantt — таймлайн

Майже не для повсякденної доки — для презентацій або планування.

gantt
    title Roadmap документації
    dateFormat  YYYY-MM-DD
    axisFormat  %b

    section Готове
    electron docs              :done, 2025-04-01, 2026-04-30
    stack-docs root            :done, 2026-04-29, 2d

    section В роботі
    golden docs (api скелет)   :active, 2026-04-30, 60d
    routing-controllers міграція :active, 2026-04-15, 90d

    section План
    stack docs                 :2026-06-15, 30d
    prime/udate/chathouse      :2026-07-15, 60d
    client/electron CLAUDE     :2026-08-01, 14d

Поради

Не намагайся вмістити все в одну діаграму. Краще 3 фокусовані ніж 1 перевантажена.
Без таймстемпів — діаграми старіють, не пиши там «створено», «змінено».
Кольори дисципліновано — постав 1 систему (статус / тип / роль) і дотримуйся.
Кліки на ноди — для flowchart це must-have. Робить діаграму інтерактивною мапою.
flowchart TB (top-bottom) для ієрархій, LR (left-right) для потоків даних.

Quartz 4

Explorer

diagram-examples