Quartz 4

diagram-examples

4 min readBohdan Derkach

diagram-examples

Приклади 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Структура коду — класи і їх методи. Рідко варте, бо швидко старієЯкщо реально треба показати ієрархію
ganttRoadmap, планПрезентації, рідко в доці

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; — стилі/кольори
  • --> — стрілка з підписом (-->|тригерить|), -.- — пунктир, === — товста

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) для потоків даних.

Graph View

Backlinks