Quartz 4

Conventions

10 min readvitalii shyliuk

Правила ведення документації

В цьому розділі описано: типи сторінок, шапки, теги, обов’язкові секції — довідник формату для автора (людини або AI) у момент написання.

Шпаргалка

Сутність в документаціїКартка
Фронт та його поведінкуUI
Бек-логіку яка займається конкретною задачеюService
Крон логікаWorker
RMQ / БД / зовнішній APIIntegration
Бізнес-фіча її взаємодіяFeature
Колекцію / таблицю БДEntity
Індекс папки або root сервісуIndex
Послідовність кроківFlow

Спільне для всіх типів (шапка, теги, іменування, лінки, глибина) — у Спільній базі нижче.

Принципи

  1. Один файл — одна одиниця. Не треба плодити кучу нод, які будуть переплітатись лінками. Кожна нода повинна бути відображена в змісті (index).

  2. Людська мова. Описуємо що відбувається — без назв полів, ключів, параметрів і умов з коду. Документ читає людина, яка хоче зрозуміти систему, а не той хто дебажить змінні.

    Неправильно: Якщо status === 'pending' і isBlocked === false — запит проходить. Правильно: Якщо заявка ще не оброблена і акаунт не заблокований — запит проходить.

    Перевірка: прочитай опис вголос — якщо звучить як людська мова, добре. Якщо звучить як grep по коду — переписати.

    Винятки — залишати як є:

    • Числа, таймаути, ліміти: 30 сек, 3 спроби. Мілісекунди — переводь у секунди (500 мс → 0.5 сек).
    • Назви ролей і сутностей: Lady, Operator, Course.
    • Назви полів у секції ## Поля entity-сторінок, ключі settings/env, назви колекцій і RMQ-черг — те, що читач шукатиме дослівно.

  3. Рішення, не реалізація. Якщо рішення неочевидне — фіксуємо чому так зробили, не як зроблено.

  4. В документації так само дуже важлива архітектура. Треба уникати дублювання інформації, подальше підтримування дублів буде неможливе (це не код який зламається).

  5. Є сенс проганяти АІ агента, щоб він порівняв результат документації і реальний код з якого вона писалась. З великим шансом він помітить відмінність описаної умови чи значення (інтервалу) з реальним.

Спільна база

Шапка сторінки (обов’язковий початок)

#Тег1 #Тег2
 
[[назва-файлу]]
 
# Людська назва
 
`шлях у коді або "(UI-елемент)"` — одна фраза: що це і навіщо.
  • Теги — тип сторінки + стан. Один рядок, без ком.
  • Backlink [[назва-файлу]] — для зворотного пошуку в Obsidian.
  • H1 — як звемо в розмові (UI) або назва класу/сервісу (бек).
  • Контекстна стрічка — для бек: шлях `src/...`; для UI: (UI-елемент); ролі/ентіті-огляди пропускають шлях. Одна фраза опису обов’язкова — це «що це» для читача, який потрапив сюди з пошуку.

Скелет незаповненої сторінки

Коли сторінка створюється наперед (знань ще нема) — мінімальний чесний скелет, не полотно здогадок:

#Service #TODO
 
[[назва-файлу]]
 
# НазваСервісу
 
`src/шлях/` — одна фраза що це (з коду або від юзера).
 
**UI:** [[ui/сторінка]] або «немає».
 
## Заповнити
 
- відкриті питання списком
  • Верифіковані факти — одразу в ## Нюанси; невідоме — питаннями в ## Заповнити. Не змішувати.
  • Здогадки не пишемо навіть з «мабуть» — тільки питання.

Теги типу

ТипТегВміст
UI-елемент#UIекран, секція, колонка, діалог
Сервіс#Serviceбек-логіка: контролер + сервіс
Воркер#Service #workerфонова задача по таймеру/черзі
Інтеграція#Service #integrationRMQ, ClickHouse, зовнішні API
Фіча#Feature (root) · #Service #feature (сервісна)бізнес-концепт цілком
Сутність#Entityколекція, таблиця, структура даних
Процес#Flowпослідовність кроків
Система#Systemінфраструктура без бізнес-логіки
Архітектура#Architectureкрос-сервісна картина, тільки root
Мета#Metaконвенції, індекси, глосарії

Стан-теги

Документ за замовчуванням — чорновик (часто AI-генерація). Стан-теги — в тому ж рядку, що тег типу.

ТегСенс
#reviewedлюдина перевірила відповідність реальності. Суттєво змінив документ — зніми
#draftдокументація яка пишеться до реалізації, а не по фактичній
#TODOнезавершений або має відкриті питання (## Заповнити не порожній)
#fixописана логіка — костиль/борг; документуємо як є, при рефакторингу переписати і код, і док

Сервісні теги (автоматичні)

Кожен файл під services/<service>/ на сайті отримує тег сервісу (#golden, #electron, …) — це робить inject-doc-meta при білді, руками не писати. Виняток: root-документ, який переважно про один сервіс — тоді сервісний тег додаємо руками.

Іменування

РівеньСтильЯк виходить
Top-level stack-docs (Architecture, Features…)Title Casetitle: у frontmatter index.md
Сервіс (Stack Golden, Stack AI…)Stack Xauto-inject у CI
Папки всередині сервісуlowercase, kebab-caseслаг папки; title: не ставити
Файли (всі без винятку)kebab-case lowercaseназва файлу
  • Файли завжди kebab-case lowercase (course-service.md, login.md) — навіть для бек-класів; зв’язок з класом (CourseService) — через H1 і контекстну стрічку. Зміст всередині — українською.
  • Home.md не використовуємо — вхід через Canvas.canvas і index.md.

Папки сервісу (<service>/docs/): кожен сервіс бере тільки потрібне.

docs/
├── Canvas.canvas         # локальна мапа сервісу
├── index.md              # root-індекс (картка Index)
├── glossary.md           # сервіс-специфічні терміни (опційно)
├── ui/                   # фронт-екрани (фронт-сервіси)
├── ui-triggered/         # бек-логіки через фронтенд
├── services/             # generic бек-сервіси
├── workers/              # фонові задачі
├── integrations/         # зовнішні контракти
├── features/             # бізнес-фічі сервісу
├── entities/             # колекції / структури
└── flows/                # процеси

Без вкладеності. Потрібна підгрупа — нова top-level папка (senders/, intervals/), не services/workers/. Папок верхнього рівня може бути багато, вкладеності — ні.

Лінки

  • Всередині сервісу: [[назва-файлу]].
  • На root: повний шлях — [[glossary#ролі|роллю operator]], [[entities/Lady]], [[features/statistics]].
  • На інший сервіс: через services/ — [[services/golden/workers/index|воркери golden]]. У режимі «один сервіс» такі лінки в Obsidian сірі — на сайті працюють, це не баг.
  • Swagger deeplink: звичайний URL на конкретний endpoint у Swagger UI.
  • Не дублюй reverse-лінк на index/menu. Backlinks-панель сама покаже вхідні. Wikilinks у Зв'язки — тільки семантичні (читає, тригерить, залежить).

Межа глибини

Описуємо: числа (таймаути, ліміти, пороги) · умови, фільтри, порядок кроків · залежності (хто кого тригерить) · неочевидні нюанси і чому. Не описуємо: синтаксис викликів · транспорт без впливу на поведінку · очевидні з коду поля й типи · запит/відповідь ендпоінтів (це Swagger).

Правило великого пальця: без цього факту читач прийме помилкове рішення → описуємо. Це лише «як зроблено» → пропускаємо. Сумнів → коротко в «Нюанси».

Картки типів

Картка — все потрібне для сторінки свого типу. Спільне (шапка, теги, лінки, глибина) — вище, у картках не повторюється.

Картка UI

  • Коли: новий екран, вкладка, колонка, діалог у фронт-сервісі.
  • Де: ui/ фронт-сервісу (у client — ui-family/, ui-shared/).
  • Шапка: #UI; H1 — як звемо в команді («колонка фаворитів»), не ім’я компонента.
  • Обов’язкові секції:
    • ## Use cases — хто (роль) і за яким сценарієм заходить. Абзац; якщо ролей з різними сценаріями кілька — bullets за ролями. Бізнес-контекст, не механіка кліків.
    • Таблиця кліків-фіч — карта екрану: рядок = дія/під-екран; колонки на роль, якщо доступ відрізняється. Деталі фіч — окремими секціями нижче.
    • Ендпоінти — deeplinks на Swagger + 2-3 слова «що робить». Single-backend (ui-shared/*): таблиця Endpoint | Що робить під кожною фічею. Per-Family (ui-family/*): одна таблиця, рядок = під-фіча, колонки golden / prime / udate / chathouse; немігроване — *TODO*.
    • ## Зв'язки — звідки дані, що тригерить.
  • Опційні: розбіжності полів по Family (таблиця «поле × Family» з ✓/—) · Числа / Обмеження · Нюанси.
  • Не писати: верстку, стилі, компоненти, пропси · форму запиту/відповіді · бек-архітектуру (мігрований/legacy/routing-controllers — читачу фронт-доки байдуже).
  • Приклад: Courses (single-backend) · Favorites (per-Family).

Картка Service

  • Коли: бек-логіка, яку викликає фронт / Electron / розширення / інший HTTP-клієнт.
  • Де: ui-triggered/ (тригер — UI).
  • Шапка: #Service; контекстна стрічка — шлях у коді, обов’язково.
  • Обов’язкові:
    • Рядки **UI:** (лінк на ui-сторінку або «немає») і **Swagger:** (deeplink на тег).
    • ## Логіка — порядок кроків, умови, фільтри (коли сторінка заповнена; у скелеті замість неї ## Заповнити).
  • Опційні: ## Числа · ## Нюанси (найцінніше: stop-листи, watchdog, захисти від подвійного запуску, рандомізації) · ## Зв'язки · ## Чому так.
  • Не писати: перелік ендпоінтів і контракти (Swagger) · ролі-гварди дослівно (Swagger показує; описуй тільки бізнес-причину обмеження, якщо неочевидна).
  • Приклад: заповнена — Dashboard.

Картка Worker

  • Коли: фонова задача — cron, Bull-черга, інтервал, разовий job.
  • Де: workers/.
  • Шапка: #Service #worker; шлях у коді.
  • Обов’язкові: ## Інтервал (розклад, число) · ## Логіка (кроки) · ## Зв'язки (що читає/пише, кого тригерить).
  • Опційні: ## Нюанси — захист від подвійного запуску, isBusy, watchdog, чому такий таймаут · ## Чому так.
  • Не писати: механіку Bull/планувальника — платформа, описана в stack-docs.
  • Приклад: воркери golden — 12 заповнених.

Картка Integration

  • Коли: сервіс говорить із зовнішнім світом — RMQ-події, OLAP-таблиці, партнерський HTTP API.
  • Де: integrations/.
  • Шапка: #Service #integration; шлях у коді, якщо є один вузол.
  • Обов’язкові: контракт сервісу — що публікує/слухає (події, routing-keys), що пише/читає (таблиці), що викликає (ендпоінти партнера) — і навіщо.
  • Опційні: Числа (TTL сесій, ліміти) · Нюанси (retry, обробка помилок) · Зв’язки.
  • Не писати: як влаштовані RMQ / ClickHouse самі по собі — платформа, у stack-docs.
  • Приклад: Official API.

Картка Feature

  • Коли: продуктовий концепт, що живе наскрізь: UI + бек + дані (Statistics, Favorites, Sender).
  • Де і як: глобальний опис — раз у stack-docs/features/ (#Feature); сервісний — <service>/docs/features/ (#Service #feature) з лінком на глобальний.
  • Обов’язкові (глобальна): суть фічі одним абзацом · де по Family · ролі, що користуються.
  • Обов’язкові (сервісна): лінк на глобальну [[features/<name>]] · що специфічно саме для цього бека.
  • Не писати: дублювання глобального опису в сервісній сторінці — тільки дельта.
  • Не плутати з Entity: ентіті — структури даних, фічі — продуктові концепти.
  • Приклад: Statistics (root) · Statistics (golden).

Картка Entity

  • Коли: колекція/таблиця БД або крос-сервісна структура даних.
  • Де: локальні — <service>/docs/entities/; глобальні (RMQ-обмін, спільні таблиці, 2+ сервіси) — stack-docs/entities/.
  • Шапка: #Entity; контекстна стрічка — `шлях до схеми` · колекція `ім'я` (для SQL — таблиця).
  • Обов’язкові: ## Поля — bullet-list полів з бізнес-значенням: **name** — опис. Типи вказуй тільки неочевидні (enum, кастомний DTO, ObjectId-ref); тривіальні required/default не описуй.
  • Опційні: ## Нюанси — індекси, каскадні видалення, кешовані поля, transform-плагіни. Загальний toJSON-плагін сервісу сюди не пиши (він у CLAUDE.md) · лінки на сервіси-продюсери/споживачі.
  • Не писати: Swagger request/response DTO — Entity-сторінка про storage shape, не API contract.
  • Реєстр колекцій: сервіс з ≥3 сутностями веде entities/index.md (#Meta) — список усіх колекцій, включно з тими, що без своєї сторінки: групи жирним підписом, рядок `колекція` — опис → [[Name]] або → —. Кілька сховищ — H2 на сховище. Без полів — це індекс.
  • Приклад реєстру: entities golden. (не готово)

Картка Index

  • Коли: кожна папка з файлами + root сервісу. Без index Quartz показує голий автолістинг.
  • Шапка: frontmatter tags: [Meta]. title: — тільки в root сервісу (Stack X; для акронімів типу Stack AI — вручну); у папкових НЕ ставити, інакше сайдбар зламає lowercase-канон.
  • Папковий index: призначення папки 1-2 фрази. ≤4-5 сторінок — bullets з описами; більше — таблиця з мітками покриття, групована по H2, зверху підсумок X ✅ · Y 🟡 · Z ⬜ (з N).
  • Root-index сервісу: опис сервісу 1-3 речення людською мовою · таблиця ## Розділи (Розділ | Що там | ✅ | 🟡 | ⬜ | Разом + рядок Разом) · рядок «Окремі сторінки» (glossary, tech-debt…) · для беків ## Swagger — лінк на live Swagger UI + API Map.
  • Мітки покриття: ✅ заповнено · 🟡 частково · ⬜ скелет. Це повнота опису, не стан-теги: сторінка може бути ✅ і нести #TODO, коли борг у коді. Цифри підтримуємо вручну: підняв ⬜→✅ — поправ підіндекс і root-таблицю.
  • Не писати в root-index: лінки на CONVENTIONS/AUTHORING (авторська мета — у CLAUDE.md) · платформенний стек · правила глибини · «як ми пишемо доки». Розділ з іншою одиницею виміру (entities: колекції, не сторінки) — прочерки в цифрах, пояснення в описі.
  • Приклад: Stack Golden (root) · ui-triggered (папковий).

Картка Flow

  • Коли: послідовність кроків — логін, логаут, ініціалізація.
  • Де: flows/ сервісу; крос-сервісні (2+ сервіси, RMQ) — stack-docs/architecture/flows/.
  • Шапка: #Flow.
  • Формат: пронумерований список кроків. ≤3 кроки — один файл; ≥4 — оглядова сторінка зі списком + окремий файл на крок. Кожен крок: Що робить · Нюанси (якщо є) · Зв'язки.

Canvas

Canvas.canvas — візуальна мапа документації.

  • Глобальний architecture/Canvas.canvas — мапа сервісів: ноди = сервіси, стрілки = HTTP/RMQ. Оновлюємо тільки при новому сервісі чи зміні топології.
  • Локальний <service>/docs/Canvas.canvas — ноди = файли docs/ цього сервісу.

Кольори по типах

ТипКолірHex
UIблакитний#2196f3
Serviceзелений#66bb6a
Entityфіолетовий#ab47bc
Flowпомаранчевий#ffa726
Systemсіро-зелений#78909c
Metaчервоний#e03131

Стрілки (підпис обов’язковий)

тригерить · оновлює · читає · стартує · викликає (крос-сервіс HTTP) · публікує / слухає (RMQ).

Групи

Обводимо ≥3 ноди одного типу в групу з кольоровим підписом («Інтервали оператора», «Сервіси TU»).

Graph View

Backlinks