Архітектура

Документ архітектури програмної системи — Software Architecture Document (SAD): як описати її зрозуміло й достатньо

Нова людина приєдналася до команди й шукає, що можна безпечно змінити. У репозиторії вона знаходить архітектурний опис із назвами React, PostgreSQL та…

Глава 13Заморожене українське видання

Нова людина приєдналася до команди й шукає, що можна безпечно змінити. У репозиторії вона знаходить архітектурний опис із назвами React, PostgreSQL та Kubernetes, але не бачить, що вже працює, хто відповідає за дані, де перевіряють вільний час і що команда має перевірити під час збою. Вона має пояснити, чому бронювання не можна підтверджувати лише після відповіді поштової служби. Самого переліку технологій для цього недостатньо: архітектурний документ має допомогти їй ухвалити безпечну зміну, а не просто назвати інструменти.

Документ архітектури програмної системи, або SAD (Software Architecture Document), має допомогти читачеві відновити важливі причини й межі системи: для кого її створено, із чого вона складається, які дані й дії належать кожній частині, як відбуваються ключові сценарії, що станеться під час помилки та які питання ще відкриті. Це не спроба записати кожен клас і параметр конфігурації. Це опис достатнього рівня, щоб люди могли ухвалювати зміни, знаходити код і перевіряти, чи реалізація ще відповідає задуму.

Після глави

Читач уміє:

  • визначити аудиторію, межу й мету архітектурного документа;
  • описати систему словами, таблицями та посиланнями так, щоб були зрозумілі відповідальності, зовнішні залежності й важливі потоки;
  • розділити поточну реалізацію, погоджений задум, пропозицію та припущення;
  • пов’язати документ із кодом, контрактами, рішеннями й операційними інструкціями;
  • знайти суперечність між написаним і кодом, не видаючи документацію за доказ фактичного розгортання;
  • визначити, що треба оновити після зміни системи, і призначити цьому власника та дату перегляду.

Передумови й межі

Глави 9–12 допомогли уточнити потреби, критерії приймання, характеристики якості й архітектурні компроміси. Тут ми збираємо потрібні відомості в опис, який команда може читати й перевіряти. Сторінка Neal Ford про Software Architecture: The Hard Parts описує її фокус як аналіз компромісів і документування рішень; це загальний контекст, а не доказ конкретної вимоги до SAD (сторінка автора). SAD доповнює вимоги й критерії приймання, записи архітектурних рішень та інструкції оператора; він не замінює їх.

У главі 14 модель C4 дасть спільні назви рівням структури; глава 15 розгляне ADR — записи окремих архітектурних рішень. SAD може посилатися на обидва матеріали, не копіюючи їх.

Для кого існує SAD

Документ корисний, коли допомагає конкретним людям виконати конкретну роботу. Власник продукту шукає зв’язок між цілями й технічними межами. Розробнику потрібні власники даних, контракти й місце зміни; рецензенту — твердження з перевірними посиланнями на код і контракти та чітке розрізнення поточного стану й майбутнього задуму. Оператор шукає залежності, сигнал відмови й спосіб відновлення, а фахівець із безпеки — межі довіри, ролі та місця перевірки доступу. Агенту потрібні підтверджені джерела, заборони й питання, на які не можна вгадувати. Це різні потреби: один документ має дати короткий огляд і навігацію, а не вимагати, щоб кожен читач однаково користувався всіма його розділами.

Не кожна людина мусить прочитати все. На початку дайте короткий огляд і навігацію до розділів за роллю або питанням. Називайте аудиторію прямо. Якщо документ розрахований лише на команду розробки, не обіцяйте, що його досить для аудиту чи відновлення після аварії.

Документація має бути пропорційною ризику й вартості зміни. Малому внутрішньому інструменту можуть вистачити однієї сторінки контексту, відповідальностей, запуску та відомих обмежень. Для платіжного сервісу, системи з медичними даними або критичної інфраструктури знадобляться глибші описи потоків, доступів, відновлення, доказів і погоджень. Число сторінок не доводить ані повноту, ані якість.

SAD не є синонімом усієї технічної документації

Чим документ архітектури відрізняється від інших технічних документів

Матеріал На яке питання відповідає Чого сам по собі не доводить
Вимоги продукту й критерії приймання Яку поведінку та якість очікує користувач або власник процесу? Як саме побудовано систему зараз
SAD Яка структура й взаємодія частин важливі для розуміння системи, і на яких фактах вони ґрунтуються? Що кожен описаний елемент уже розгорнуто або що користувач задоволений результатом
ADR (Architectural Decision Record — запис архітектурного рішення) Яке значуще рішення ухвалено, чому, які були альтернативи й наслідки? Повний опис усіх сценаріїв і стану системи
Контракт програмного інтерфейсу застосунку (API — Application Programming Interface) або схема даних Які точні поля, типи, операції, помилки та правила сумісності має інтеграція? Чому межу проведено саме так і що стається за межами контракту
Посібник експлуатації (runbook) Які кроки виконує оператор у конкретному інциденті чи під час обслуговування? Загальна карта компонентів і цілей продукту
Вихідний код, налаштування й історія версій Що саме збережено в конкретному коміті та як це змінювалося? Чи відповідає код актуальним потребам і чи має всі потрібні операційні процедури

Ці матеріали мають посилатися одне на одного там, де це заощаджує час, але не копіювати великі фрагменти, які неминуче розійдуться. SAD повідомляє, наприклад, де зберігається актуальний контракт; контракт містить точні поля; ADR пояснює, чому було обрано саме такий спосіб сумісності.

Відповідальний документ починається зі статусу й межі

Статус архітектурного опису та докази його актуальності

Найнебезпечніше формулювання архітектурного документа — безчасове «система робить». Воно може описувати задум, стару реалізацію, неперевірену заяву постачальника або майбутній етап. Відокремлюйте статус кожного важливого твердження:

  • Фактичний стан: підтверджений кодом, налаштуванням, перевіркою середовища чи надійним записом роботи системи; вкажіть дату або версію доказу.
  • Погоджений цільовий стан: рішення прийняте, але частина реалізації ще не завершена; назвіть, що лишилося зробити.
  • Пропозиція: варіант обговорюють; його не можна представляти як рішення.
  • Припущення або відкрите питання: відомостей бракує; назвіть власника відповіді, ризик і наступну перевірку, якщо вони відомі.
  • Застаріло / замінено: твердження більше не описує поточну систему; збережіть посилання на дату, причину або новіший матеріал, якщо це важливо для історії.

Умовний заголовок SAD може мати такий вигляд:

Назва: Система бронювання консультацій
Статус: фактичний стан v1; розділ 7 містить погоджений задум v1.1
Власник документа: команда бронювання
Система й межа: вебкабінет клієнта, серверна частина й сховище бронювань
Дата перевірки: 23 вересня 2026 року
Версія реалізації, яку звірено: реліз 1.4.2, коміт (commit) 8c21d3a
Наступна перевірка: після зміни правила підтвердження або початку міграції сховища;
перед перемиканням трафіку перевірити сумісність старої й нової схем, порядок розгортання,
перенесення та звіряння записів, точку відновлення й перевірений спосіб відкату.
Якщо безпечний відкат неможливий, зафіксувати план виправлення до початку переходу
Джерела: документ вимог до продукту (PRD, *Product Requirements Document*) № 17, ADR-004, контракт /docs/api/booking.yaml

Це навчальні ідентифікатори й дата прикладу, не запис про реальну систему. Коміт краще закріплює текст за конкретним станом коду, ніж слово «остання версія». Але навіть точний коміт не доводить, що продакшн розгорнув саме його. Для такого твердження потрібен окремий доказ розгортання.

Що має відповісти короткий, корисний SAD

Шаблон — набір питань, а не контрольний список для механічного заповнення. Офіційний шаблон arc42 має дванадцять частин: цілі, обмеження, контекст, стратегія, будівельні блоки, сценарії виконання, розгортання, наскрізні концепції, архітектурні рішення, вимоги до якості, ризики та словник. Його автори прямо дозволяють адаптувати обсяг під систему. Практичний висновок для невеликої глави чи проєкту: лишіть розділ, якщо він потрібен читачу; поясніть відсутність, якщо він важливий, але ще невідомий; не копіюйте повний шаблон заради галочок arc42: огляд шаблону, arc42: метод.

Корисний SAD зазвичай відповідає на ці запитання.

1. Який продукт описано і навіщо?

Коротко назвіть проблему, цільову аудиторію, важливі бізнес-результати й межу системи. Окремо запишіть, що документ не описує. Якщо в продукті кілька незалежних підсистем, звузьте сторінку до одного цілісного рішення або вкажіть, де починається інший документ.

2. Які обмеження та вимоги впливають на структуру?

Зазначте договірні чи нормативні межі, середовища, команди й важливі характеристики якості: наприклад, конфіденційність, доступність, затримку, відновлення або сумісність. Розрізняйте прийняту вимогу, виміряний факт і неперевірене число. Для кожного критичного порога вкажіть джерело й метод перевірки; це докладніше розглянуто в главі 11.

3. Хто або що перебуває за межами?

Назвіть людей і зовнішні системи, які взаємодіють із продуктом. Для кожної залежності зафіксуйте тип даних або запиту, напрямок, мету, важливий механізм доступу, відповідального постачальника та поведінку під час помилки. «Платіжна система» недостатньо: важливо зрозуміти, хто приймає платіж, хто зберігає стан замовлення й хто може підтвердити результат після тайм-ауту.

4. Які частини є всередині й що кожна відповідає?

Перелічіть логічні компоненти або модулі за відповідальністю, а не лише технологіями чи каталогами файлів. Для кожного вкажіть вхідні дані, результат, власника стану, інтерфейс і заборонені обов’язки. Визначте зовнішні залежності та те, що не входить до системи. Не називайте кожен пакет окремою архітектурною частиною.

Модель C4 допомагає узгоджено змінювати рівень деталізації: від системи й її оточення до застосунків/сховищ усередині, компонентів у них і, лише за потреби, конкретних елементів коду. Її автор підкреслює, що це модель опису статичної структури, а не процес розробки; питання стану й послідовності роботи можуть потребувати окремого текстового опису C4: офіційний сайт, абстракції, відповіді на поширені запитання про поєднання з arc42. У цій главі структура записана словами й таблицями; діаграми C4 — тема наступної глави.

5. Як проходять важливі сценарії?

Опишіть нормальний шлях і шляхи відмови: хто ініціює дію, яка частина перевіряє правило, де фіксується зміна, хто отримує повідомлення й що бачить людина за часткового збою. Не потрібно переказувати кожен запит. Виберіть сценарії, що впливають на якість, дані, безпеку чи дорогі архітектурні рішення.

6. Хто володіє даними та як вони захищені?

Назвіть джерело істини для кожного важливого факту, власника зміни, похідні копії, строк зберігання, процедуру відновлення й інтеграційні правила. Для міграції даних зазначте сумісність старої й нової схеми, послідовність переходу (наприклад, розгорнути сумісний код, перенести й звірити записи, лише тоді перемикнути читання), точку відновлення й перевірений спосіб відкату; якщо зворотний перехід не підтримано, назвіть безпечний план виправлення вперед до початку міграції. Для доступу вкажіть місце перевірки права, ролі та недовірені входи. Персональні дані, секрети, резервні копії й журнали мають бути згадані лише на рівні, потрібному для відповідного ризику; конкретний пароль або секрет у документі не зберігають.

7. Де й за яких умов система працює?

Відділіть поточне розгортання від цільового. Опишіть середовища, що запускає застосунок, фонові роботи, необхідні зовнішні служби, конфігураційні межі та процес повернення попередньої версії, якщо він підтверджений. Не стверджуйте, що є автоматичне відновлення або резервування, доки цього не звірено з реальною конфігурацією й операційною процедурою.

8. Що може піти не так і що лишилося невідомим?

Запишіть дорогі або ймовірні ризики, технічний борг, залежності від постачальників і припущення, здатні змінити структуру. Для кожного відкритого питання вкажіть, кого запитати або який факт перевірити. Твердження «потрібно масштабувати» без очікуваного навантаження, межі часу й даних про вузьке місце не є висновком.

9. Як читач перевірить опис?

Дайте посилання на вимоги, кодові каталоги, специфікації, ADR, експлуатаційні кроки й публічні джерела. Зазначте дату перевірки. Напишіть, які частини звірені з кодом, які з інфраструктурою, а які походять із погодженого задуму. Точне посилання на код із номером рядка може з часом зміститися; закріплений commit або стабільна назва модуля полегшують пошук.

Розібраний приклад 1: компактний SAD для сайту футбольної статистики й складів

Нижче повністю вигаданий навчальний приклад. Team A, Team B, ідентифікатори гравця й події, дати, ролі, метрики та варіанти зберігання не описують реальний клуб, постачальника чи розгортання. Припустімо, що умовний власник погодив цільову поведінку для першої версії; перед реалізацією команді все одно потрібні чинний контракт джерела даних і підтверджені права на публікацію. Приклад показує, які архітектурні відповіді треба зафіксувати, а не призначає універсальну технологію.

SAD — сайт футбольної статистики та складів, версія 1

Статус і власник. Це погоджений у межах навчального сценарію цільовий опис першого випуску, а не звіт про реалізований чи розгорнутий продукт. Вигадана команда спортивних даних володіє документом; власник продукту визначає публічні правила, а розпорядник даних погоджує джерело й виправлення. Документ переглядають після зміни контракту фіда, ідентифікації гравців і клубів, правил ефективної дати або політики публікації. Для тверджень про фактичний стан потрібні окремі докази коду й середовища.

Ціль. Читач бачить поточний склад клубу, історію переходів і статистику гравця за матчами та сезонами. У вигаданій події demo-017 офіційний фід повідомляє, що гравець P-42 переходить із Team A до Team B з ефективного часу 2026-08-31T00:00:00Z. Після настання цього часу поточний склад має показати Team B, а історичні матчі та статистика, записані для Team A, мають лишитися прив’язаними до Team A. Повідомлення фіда є доказом походження події, але не замінює перевірку її контракту, коректності та права на публікацію.

Поза межами. Прямі трансляції, прогнози, ставки, переговори про трансфер, медичні чи контактні дані гравців і редагування реєстру зовнішньої ліги не входять до системи. Сайт публікує лише дозволені для цього продукту дані. Власник має підтвердити ліцензію джерела, правила виправлення й межі публікації до запуску; приклад не припускає, що будь-який фід дозволяє повторне використання.

Люди та зовнішні системи. Публічний читач переглядає склади й матчеву статистику; аналітик читає дозволені агрегати; редактор даних розглядає події, які автоматична перевірка не може безпечно зіставити. У сценарії ліцензований постачальник змагання передає фід переходів і матчевих результатів із зовнішніми ідентифікаторами, ефективним часом, версією та походженням запису. Його роль і право на публікацію тут є умовами прикладу, що мають бути підтверджені договором і схемою. Постачальник не має прямого доступу до бази, а сайт не змінює його реєстр.

Ключова якість і межі. Для навчального вимірювання припустімо 200 одночасних читачів на репрезентативному наборі клубів, матчів і сезонів. Гіпотеза — p95 (95-й перцентиль затримки) читання картки гравця не перевищує 700 мс; окремо не менш ніж 99% запитів повертають коректний результат до двох секунд. Інша гіпотеза — прийнята й ефективна подія з’являється в публічному складі протягом п’яти хвилин після її валідованої доставки. Це навчальні цілі, а не погоджені гарантії. Перед висновком власник має затвердити вимірювані межі, період, вибірку, навантаження, критерій коректності та те, чи може контракт джерела підтримати таку свіжість.

Контейнери й внутрішні відповідальності. На контейнерному рівні навчальний задум має публічний вебсайт, API читання, фоновий імпортер і реляційне сховище. Таблиця уточнює відповідальні компоненти в цих межах і зовнішню інтеграцію; це логічний поділ цільового стану, а не твердження про конкретні технології чи розгорнуті процеси.

Контейнер або компонент Відповідальність і власний стан Межа й помилка
Публічний вебсайт Показує склад «на дату», історію переходів і статистику матчів Не визначає авторитетність фіда й не редагує клубну належність у браузері; показує час останнього оновлення
API читання Повертає публічні поля та формує поточний склад із затверджених інтервалів належності Не читає неперевірені повідомлення напряму з черги; відхиляє запит, який виходить за дозволений контракт
Імпортер і валідатор Перевіряє контракт, джерело, схему, стабільні ідентифікатори, ревізію та часову послідовність; невідомі випадки ставить у карантин Не вгадує особу за схожим ім’ям; повтор того самого (source_id, event_id, source_revision) із тим самим digest не дублює стан, а інший digest для цього ключа є конфліктом
Канонічне сховище Зберігає стабільні player_id і club_id, матчеві появи, інтервали членства, прийняті події, ревізії та походження Запис прийнятої події й зміна проєкції складу фіксуються транзакційно; виправлення додає версію, а не стирає історію мовчки
Зовнішній фід Постачає дані за погодженим контрактом Затримка, повтор, зміна схеми або відкликання даних можуть вимагати карантину, видимого статусу застарілості чи ручного розгляду

Сценарій успіху й належність у часі.

  1. Отримання. Імпортер отримує вигадану подію demo-017 із зовнішнім player_id, club_id Team A і Team B, ефективним часом 2026-08-31T00:00:00Z, ідентифікатором джерела та його версією.
  2. Фіксація. Після перевірки контракту й відповідностей транзакція записує незмінне походження події, закриває інтервал членства P-42 у Team A на ефективний час і створює інтервал Team B від цього часу. Запис матчевої появи має player_id, match_id і club_id команди, за яку гравець виступав у тому матчі; його не переприв’язують до поточного клубу.
  3. Читання на дату. Запит бере інтервали станом на обрану дату: до ефективного часу Team A лишається поточним клубом, після нього сторінка показує Team B і зберігає попередню історію. Якщо перехід запланований на майбутнє, поточний склад не перемикається завчасно.

Поле effective_at задає момент, від якого факт стає чинним; час отримання повідомлення лише показує, коли система його побачила. Їх не можна підміняти одне одним. Якщо контракт містить лише календарну дату без часового поясу, власник має визначити правило календаря ліги до реалізації — час приймання файлу не є безпечним запасним правилом. Матчева поява зберігає клуб, за який відбувся саме той матч, навіть якщо пізніше гравець перейшов до іншого.

Сценарій повтору та конфлікту.

  1. Точний повтор. Кортеж (source_id, event_id, source_revision) — це ідентифікатори джерела, події та її ревізії. Якщо джерело повторно надсилає той самий кортеж і той самий digest (хеш нормалізованого вмісту), це точний повтор. Система може записати метрику, але не створює другого переходу чи інтервалу.
  2. Змінився вміст. Якщо кортеж збігається, а digest відрізняється, обидва спостереження лишаються для звірки. Нове не відкидається мовчки й не перезаписує прийняту версію; канонічна подія та проєкція не змінюються, доки рішення не буде прийняте за контрактом джерела.
  3. Суперечливі дані. Якщо дві різні події конфліктують для того самого гравця й періоду або зовнішній ID не зіставлено з канонічним клубом, імпортер не обирає переможця за часом надходження й не підбирає сутність за назвою. Він ізолює записи для редактора. Власник має визначити правила сумісних реєстрацій, оренд і паралельних змагань для конкретної ліги: припущення «гравець завжди має лише один клуб» може бути хибним.

Сценарій відмови джерела.

  1. Зупинка. Якщо фід недоступний або його схема змінилася, імпортер не вигадує нового складу й не перезаписує канонічний стан. Оператор бачить час останнього успішного імпорту, затримку, помилки й чергу карантину. Коли дані виходять за межу свіжості, публічна сторінка позначає їх як застарілі й показує час останньої прийнятої синхронізації.
  2. Відновлення. Після повернення джерела стабільний ключ і версія дають змогу безпечно повторно обробити події. Якщо транзакцію сховища зафіксовано, але підтвердження фіду загубилося, повтор не створює другого членства. Якщо контракт вимагає відповіді джерелу, точний протокол підтвердження лишається відкритим питанням.

Дані та доступ. Канонічне сховище володіє прийнятою історією складів і статистики; зовнішній фід є джерелом-кандидатом із зафіксованим походженням, а не прямою базою для сторінки. Публічний API повертає лише погоджені поля. Роль редактора потрібна для ручного зіставлення та прийняття виправлення; зміна має містити автора, причину, джерело й часову мітку. Облікові дані фіда зберігаються в погодженому сховищі секретів із мінімальними правами та не потрапляють у код, журнали чи публічні помилки. Навіть статистика відомих гравців може мати ліцензійні обмеження; дозволені поля, зберігання сирого фіда, видалення й процедура відкликання даних лишаються умовами договору та відкритими питаннями, доки їх не підтвердить власник.

Розгортання та експлуатація. Цільова, ще не перевірена схема має вебсайт і API читання, окремий фоновий імпортер та реляційне сховище; постачальник хостингу, топологія, регіон, політика резервних копій і строк відновлення не обрані. На першому етапі не потрібен окремий кеш: якщо вимірювання доведе його користь, він буде похідною проєкцією з явним строком свіжості, а не джерелом істини. Операційні сигнали: час останнього успішного імпорту, затримка фіда, кількість повторів і конфліктних ревізій, розмір карантину, помилки читання, резервне копіювання та дата останньої перевірки відновлення. Посібник оператора має описувати повтор імпорту, ручне зіставлення й відкочення помилкової проєкції через нову перевірену версію, не приховуючи початкову подію.

Альтернативи, ризики й відкриті питання. Просте перезаписування current_club_id дешевше, але втрачає історію належності й може помилково приписати попередні матчі новому клубу. Повна event-sourced система (система, де поточний стан щоразу відтворюють із повного потоку подій) може бути зайвою складністю для першого випуску. У цьому прикладі достатньо зберігати версійовані події джерела та явні інтервали членства поруч із канонічними статистичними записами; деталі контракту й звіряння залишаються вирішальними. До реалізації треба відповісти: яке джерело й ліцензія авторитетні; як ідентифікувати гравця/клуб після перейменування; як представляти оренду, подвійне право реєстрації, виправлення та скасування переходу; який часовий пояс і календар визначає ефективність; які поля можна показувати та скільки зберігати сирий фід; яку свіжість і відновлення погодив власник. Невирішені відповіді не можна підміняти технічними припущеннями.

Перевірка задуму. До запуску контрактні й інтеграційні перевірки мають дати такі докази:

Перевірка Очікуваний результат
Перехід P-42 з Team A до Team B Поточний склад змінюється лише з effective_at; склад на попередню дату й матчі до переходу лишаються за Team A.
Точний повтор (source_id, event_id, source_revision) Той самий digest не створює другої події чи інтервалу.
Конфліктний digest або невідомий ID Спостереження зберігається для звірки, але не змінює прийняту версію чи публічну проєкцію до рішення за контрактом.
Недоступне джерело або загублене підтвердження Сторінка показує час останньої синхронізації; повтор після відновлення не створює дубля й не додає непідтверджених даних.
Доступ і відновлення Права редактора, обробка секретів і процедура відновлення перевірені окремо.

До того ж перевірка має підтвердити, що ефективність переходу не випереджає дату, яку визначає контракт; майбутній перехід не змінює поточний склад завчасно; матчевий запис не переходить до нового клубу разом із профілем гравця; конфліктні спостереження лишаються доступними редактору для звірки; а межа свіжості позначає дані застарілими, не підмінюючи їх неперевіреним знімком. Ці пункти конкретизують потрібну поведінку, а не є результатами вже виконаних тестів.

Ці критерії описують потрібні майбутні докази, а не перевірки, які вже пройшли.

Чому приклад допомагає

Статус, власник, джерела й відкриті питання показують, де закінчується цільовий опис і починаються неперевірені припущення. Перед упровадженням треба підтвердити контракт і ліцензію, визначити правило ефективних дат та звірити поведінку з вимогами змагання. Лише тоді твердження можна прив’язати до коду й окремого доказу розгортання.

Розібраний приклад 2: перетворити список технологій на відповідальний опис

Початковий уривок:

«Система побудована на React, PostgreSQL, Kafka і Kubernetes. Архітектура модульна та масштабована. Дані шифруються. Є повне автоматичне відновлення, доступність 99,99%. Після оплати надсилається лист».

Цей абзац не дає змоги ухвалити безпечну зміну. «Модульна» не називає модулі; «масштабована» не вказує вид навантаження; «шифруються» не визначає дані, межу чи ключі; «повне відновлення» не говорить, що відновлюють і за скільки часу; доступність не має вимірювального вікна та правила успіху; лист може бути умовою платежу або лише сповіщенням. Технології можуть бути фактами репозиторію, але самі собою не пояснюють систему.

Питання, що відокремлюють факти від припущень:

  1. Який реліз або commit описуємо? Чи розгорнутий цей код зараз?
  2. Хто є користувачами та зовнішніми постачальниками? Які поля або команди переходять між ними?
  3. Чи є Kafka в поточній конфігурації, чи це майбутній план? Які повідомлення вона несе, хто їх підтверджує та чи можна повторити?
  4. Яка дія має бути узгодженою з оплатою? Чи можна підтвердити замовлення, якщо провайдер оплати відповів тайм-аутом?
  5. Яке сховище володіє статусом платежу й замовлення? Чи можуть ці факти розійтися?
  6. Для кого важливі 99,99%; яка подія вважається успіхом, період, знаменник і джерело вимірювання?
  7. Яке саме відновлення автоматичне, хто його перевіряв і коли була остання успішна вправа?

До відповіді на ці питання не потрібно домальовувати складні деталі. У SAD можна написати: «У поточній гілці знайдено залежність PostgreSQL; розгортання не перевірене. Згадку Kafka є в пропозиції від 12 серпня, але розгортання та споживачі не підтверджені. Поріг 99,99% не має власника чи джерела, тому поки не є ціллю». Це точніше, ніж перетворити описаний варіант на статус «готово».

Виправлений уривок після перевірки припущень:

«У цьому навчальному прикладі перевірка релізу 1.4.2 підтвердила, що модуль Бронювання є єдиним власником активного слота. Одна транзакція створює запис, а частковий унікальний індекс PostgreSQL за ідентифікатором слота (slot_id) з предикатом WHERE status = 'active' забороняє зберегти два активні бронювання на той самий слот; якщо два запити прийшли одночасно, перший підтверджується, другий отримує конфлікт без створення запису й може оновити список слотів. У PostgreSQL унікальність лише підмножини рядків задають частковим унікальним індексом, а не звичайним обмеженням UNIQUE (обмеження таблиць, часткові індекси). Модуль Замовлення зберігає підтверджений стан замовлення, а модуль Оплати передає запит зовнішньому провайдеру. Після тайм-ауту платіж має стан “результат невідомий”; система спершу звіряє його за ідентифікатором провайдера, а не сліпо повторює оплату. Повідомлення надсилається після підтвердженого запису замовлення й не є доказом оплати. Фоновий брокер повідомлень не розгорнутий; це лише майбутній варіант, якщо вимірювання покаже потребу.

Невідомий результат платежу: модуль Оплати звертається до зовнішнього провайдера. Після тайм-ауту статус лишається невідомим; система звіряє його за ідентифікатором провайдера, а не повторює оплату наосліп. Лист надсилається після підтвердження замовлення, але сам по собі не доводить, що платіж пройшов. Брокер повідомлень ще не розгорнутий і залишається пропозицією.

Відновлення за runbook: черговий оператор відновлює копію в ізольованому середовищі, перевіряє точку відновлення, кількість і цілісність бронювань. Власник даних підтверджує результат перед перемиканням трафіку. Перед зміною схеми команда також перевіряє сумісність старої та нової версій, порядок розгортання, перенесення і звіряння даних, контрольну точку та перевірений відкат. Якщо відкат небезпечний, до перемикання має бути визначений план виправлення вперед. Це ручна процедура; автоматичне відновлення, цільовий час і допустима втрата даних лишаються непогодженими. Тому SAD не обіцяє автоматизацію чи доступність 99,99%.»

Такий уривок розділяє підтверджений кодом факт, невідомий платіжний результат, ручну процедуру й майбутню пропозицію. Він пояснює, чому повтор платежу після тайм-ауту небезпечний, як перевіряється відновлення і які зміни схеми потребують окремого плану. Уривок не підмінює контракт платіжного провайдера; його точні правила треба перевірити окремо.

Реальний приклад: перевірити архітектурний опис поруч із кодом і історією

Репозиторій temporalio/temporal має загальний огляд архітектури та окремий опис History Service. Огляд пояснює ролі Frontend, History і Matching та відділяє їх від Workers, які виконують користувацькі робочі процеси. Workers виконують код робочих процесів користувачів; вони не є тією самою межею, що серверні служби кластера. Опис History Service уточнює, що не охоплює всіх обов’язків компонента, і посилається на відповідний кодовий каталог у репозиторії.

У тому самому репозиторії існують окремі каталоги service/frontend, service/history, service/matching і service/worker. Історія Git показує, як посилання на код старіють: після рефакторингу обробника у травні 2024 року шлях workflow_task_handler_callbacks.go переїхав. Commit від червня 2026 року оновив його на service/history/api/respondworkflowtaskcompleted/api.go (виправлення посилань, поточний шлях).

Ці кроки підтверджують дві обмежені речі: документація називає межі, які можна знайти в кодовому дереві, а історія змін показує, що посилання треба підтримувати після рефакторингів. Вони не доводять, що кожен розділ повністю актуальний, що main розгорнуто в Temporal Cloud або що поведінка однакова за будь-якої конфігурації. Документація, код і запущене середовище — окремі джерела доказів. Для власного SAD зафіксуйте, що саме перевірили, за якою версією й коли.

Сторінки Temporal містять діаграми й посилання на зображення; у цьому текстовому прикладі курс не копіює їх. Ми переказуємо лише перевірювані твердження й історію посилань. Команда може застосувати той самий спосіб до свого SAD: відкрити документ, пройти ключові посилання до каталогу чи контракту, порівняти критичний потік із кодом та історією змін і записати дату та межі перевірки.

Документ має змінюватися разом із системою

Як підтримувати архітектурний документ актуальним

Архітектурний документ старіє, якщо зміна контракту, власника даних або розгортання не оновлює текст. Натомість його не потрібно редагувати після кожного перейменування змінної. Використовуйте практичне правило: оновлюйте SAD, коли змінюється факт, що впливає на вибір, ризик, сумісність, безпеку, операційну дію або розуміння межі.

Для зміни попросіть автора відповісти:

  1. Яке твердження SAD змінилося або стало неперевіреним?
  2. Це фактична реалізація, погоджена ціль, пропозиція чи експеримент?
  3. Який код, контракт, конфігурація або спостереження доводить новий стан?
  4. Який ADR чи вимога має посилатися на зміну?
  5. Чи змінилися дані, доступ, збій, запуск, відновлення або видимість для оператора?
  6. Які посилання й приклади тепер застарілі?
  7. Хто власник наступної перевірки і за якої події вона потрібна?

Одна зміна може оновлювати вимогу, SAD і короткий ADR. Не створюйте однакову таблицю тричі. У вимозі зафіксуйте очікувану поведінку; у SAD — її місце в структурі; в ADR — причину конкретного вибору. У коді лишається реалізація, а в runbook — інструкція дії під час інциденту.

Для документації як коду (англійською Documentation as Code) корисно зберігати текст поруч із кодом у системі керування версіями: можна переглянути автора, зміну, commit, обговорення й повернення попередньої редакції. Це полегшує перевірку посилань і власника, але не робить вміст правдивим автоматично. Твердження все одно мають мати джерело та дату.

Як агент має читати й підтримувати SAD

Агент може знайти розрив між документом і кодом, витягнути список залежностей, запропонувати таблицю відповідальностей або вказати, що критерій якості не має методу перевірки. Але він не може самостійно перетворити невідоме на факт, прийняти продуктовий поріг, затвердити модель доступу або оголосити розгортання успішним без доказу.

Добре обмежене доручення може звучати так:

Порівняй розділ «Стан і потоки» цього SAD із файлами в зазначених каталогах.
Для кожного твердження запиши одне з чотирьох: підтверджено кодом / суперечить коду /
не можна підтвердити за доступними файлами / описує погоджену ціль, але не поточний стан.
Для підтвердження наведи точний шлях і символ або commit. Не роби висновків
про виробниче розгортання без його окремого доказу. Не змінюй пороги,
ролі доступу, вимоги чи статус ADR. Запиши питання, на яке має відповісти
власник системи. Після аналізу не редагуй код; запропонуй конкретний текст SAD.

Перш ніж просити агента редагувати, вкажіть йому дозволені файли, джерела, версію гілки, форму доказу та заборону самостійно затверджувати рішення. Якщо агент не має доступу до інфраструктури, не просіть його «підтвердити продакшн» за конфігурацією локального репозиторію. Такий підхід узгоджується з офіційними порадами починати з чітких критеріїв і контрольованих меж, а автоматичні перевірки доповнювати людською оцінкою відповідності вимогам OpenAI, практичний посібник зі створення агентів, Anthropic, «Building effective agents». Такі обмеження роблять результат перевірюваним і захищають команду від впевненої, але вигаданої документації.

Типові помилки SAD

Помилка Чому шкодить Як виправити
Перелік технологій без відповідальностей Читач не знає, що можна змінити без порушення правил Описати межу, стан, інтерфейс і власника для кожної значущої частини
Задум записано в теперішньому часі Агент і команда приймають заплановане за вже наявне Позначити стан, дату й доказ окремо для поточного та цільового варіанта
Успішний шлях без часткового збою Оператор не знає, який стан міг лишитися після тайм-ауту Додати один або два ризикові потоки з повтором, відмовою й відновленням
«Безпечно», «масштабовано», «висока доступність» без критерію Немає способу перевірити заяву Посилатися на погоджену вимогу, спосіб вимірювання та межі твердження
Той самий контракт скопійовано в кілька місць Одна копія старіє, а зміна непомітно суперечить іншій Зберігати деталі в одному джерелі, в SAD лишити посилання й архітектурний сенс
Немає власника й перевірки Документ поступово перетворюється на архів Призначити власника та тригер оновлення; огляд не є заміною перевірки після змін
Діаграма змішує рівні й напрями потоків Читач плутає компонент, сервер і команду Назвати тип, межу, напрям, протокол і мету кожного зв’язку; матеріал наступної глави пояснить C4
Джерело свідчить лише про код, але висновок стосується продакшну Код може бути не розгорнутий або конфігурація відрізнятися Розділити докази коду, інфраструктури й фактичного середовища

Порядок підготовки й перевірки

Працюйте невеликими проходами, а не заповнюйте шаблон від початку до кінця без перевірок.

  1. Виберіть читача й питання. Наприклад: «Що не можна змінити, щоб не допустити подвійного бронювання?»
  2. Позначте межу й дату. Укажіть назву системи, реліз або commit, середовище й власника документа.
  3. Зберіть вихідні матеріали. Перегляньте вимоги, код, інтерфейси, налаштування, ADR, runbook і прямі відповіді власника системи.
  4. Розділіть факт і намір. Для кожного важливого твердження зафіксуйте джерело, статус, дату й невідоме.
  5. Опишіть зовнішній контекст і відповідальності. Назвіть людей, системи, компоненти й дані; зафіксуйте, хто відповідає за стан.
  6. Виберіть критичні сценарії. Покажіть нормальний шлях і ті дії, де зміна стану, інтеграція чи частковий збій мають дорогі наслідки.
  7. Додайте важливу якість, доступ, розгортання та ризики. Включайте відомості, що змінюють структуру або рішення; для невідомого запишіть спосіб перевірки.
  8. Перевірте зв’язки. Перейдіть від істотної вимоги до критерію, від відповідальності до коду чи контракту, від ризику до власника.
  9. Звірте текст із реалізацією. Попросіть розробника пройти ключовий шлях і окремо підтвердити стан інфраструктури. Не приймайте збіг назв файлів за доказ розгортання.
  10. Перевірте читабельність і актуальність. Чи знайде читач межу, власника даних, аварійний шлях, дату й відкрите питання без усних пояснень? Запишіть власника та тригер наступного оновлення.

Перед публікацією пройдіть повний список:

  • заголовок і статус кажуть, що саме описано й до якого моменту;
  • межа системи не плутає власний код із зовнішнім постачальником;
  • кожна значуща частина має відповідальність, інтерфейс і власника стану;
  • описані нормальний шлях і щонайменше один важливий шлях відмови;
  • поточний стан відокремлено від погодженого або запропонованого майбутнього;
  • числа якості пов’язані з вимогою та способом вимірювання;
  • персональні дані, права, секрети й відновлення описано настільки, наскільки вимагає ризик;
  • посилання ведуть до версійного коду, контрактів і рішень;
  • невідоме має власника або чітко позначене як невирішене;
  • текст можна читати без усних пояснень автора й він не містить тверджень ширших за наявні докази.

Короткий підсумок

SAD — карта важливих меж і аргументів системи, а не каталог кожної технічної деталі. Почніть з читача, мети й статусу тверджень; покажіть зовнішній контекст, відповідальності, дані, потоки й помилки; відокремте поточний код від погодженого задуму; вкажіть джерела, ризики й відкриті питання. Посилання на код і історія його змін дають змогу перевірити опис, але не доводять стан розгортання. Утримуйте документ через власника та тригери оновлення, а обсяг підбирайте за ризиком і користю.

Джерела та подальше читання

Онлайн-джерела й репозиторій перевірено 10 жовтня 2026 року. Джерела нижче підтримують опис структури й приклади; вони не задають обов’язкову кількість розділів або сторінок для кожного проєкту.