Stack Docs — гід для AI
Це root-репо документації проєкту. Тут лежать глобальні речі (конвенції формату, процес, глосарій, ролі, ентіті, мапа сервісів) і збирається єдиний сайт docs.besocial.tech з документацій усіх сервісів.
Перед роботою з doc-файлами обов’язково прочитай
- CONVENTIONS.md — правила формату (типи сторінок, шапка, теги, лінки, Canvas)
- AUTHORING.md — процес створення/оновлення (сценарії: новий сервіс, новий UI, нова роль, оновлення під зміну коду)
Без них не створюй і не редагуй жоден .md чи .canvas.
Структура
stack-docs/
├── README.md # людська шпаргалка про систему
├── CONVENTIONS.md # правила формату
├── AUTHORING.md # процес
├── glossary.md # глобальні терміни
├── roles.md # каталог ролей
├── architecture/ # мапа сервісів, RMQ, пайплайн доки
├── entities/ # крос-сервісні сутності
├── scripts/ # inject-doc-meta, build-changelog, sync, sync-shared-docs
├── quartz-overrides/ # override для Quartz при білді сайту
└── services/ # symlinks/snapshots сервісних доків (gitignored)
Принципи в одному реченні
Довідник, не туторіал. UI-хребет, бек-картки. API — це Swagger, не markdown. Один файл — одна одиниця. Wikilinks тільки на ноди Canvas.
Якщо тебе попросили…
- Створити новий файл — визнач тип сторінки (UI / Service / Entity / Flow / System / Role / API / Architecture), використай шаблон з CONVENTIONS, додай ноду в
Canvas.canvas. - Оновити CONVENTIONS / AUTHORING / glossary / roles — це глобальні зміни. Пройдись по сервісам у
services/*і перевір чи не треба синхронізувати. - Додати ноду на
architecture/Canvas.canvas— лише коли з’являється новий сервіс або змінюється топологія взаємодії (нова RMQ-черга, новий HTTP-канал). - Не вистачає інформації — задай 3-5 вузьких запитань. Не вигадуй. Краще лиши
TODO: уточнити Xніж напиши неправду.
CI пайплайн і деплой
- Пайплайн і триггери — Docs-pipeline.md
- При змінах у
scripts/,quartz-overrides/,.github/workflows/docs.yml— звір з пайплайном і онови сторінку якщо ламаєш контракт.
Коміти
Conventional Commits. Префікс обов’язковий — feat: / fix: / refactor: / docs: / chore: / style:. Опис англійською, теперішній час.