Шаблон запису рішення arc42

1. Вступ і цілі

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

1.1 Огляд вимог

Зміст

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

Мотивація

З погляду кінцевих користувачів систему створюють або змінюють, щоб краще підтримати бізнес-діяльність та/або підвищити якість.

Форма

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

Робіть ці витяги якомога коротшими. Збалансуйте читабельність цього документа з потенційною надлишковістю щодо документів з вимогами.

1.2 Цілі якості

Зміст

Три (щонайбільше п’ять) найважливіші цілі якості архітектури, досягнення яких має найвищу вагу для основних зацікавлених сторін. Ми справді маємо на увазі цілі якості архітектури. Не плутайте їх із цілями проєкту. Вони не обов’язково збігаються. Стандарт ISO 25010 дає гарний огляд потенційно цікавих тем.

Мотивація

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

Форма

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

1.3 Зацікавлені сторони

Зміст

Явний огляд зацікавлених сторін системи, тобто всіх осіб, ролей або організацій, які

мають знати архітектуру
мають бути переконані в архітектурі
мають працювати з архітектурою або з кодом
потребують документації архітектури для своєї роботи
мають ухвалювати рішення щодо системи або її розробки

Мотивація

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

Форма

Таблиця з назвами ролей, іменами осіб та їхніми очікуваннями щодо архітектури та її документації.

2. Обмеження

Усе, що обмежує команди в рішеннях щодо проєктування і реалізації або в рішеннях щодо пов’язаних процесів. Іноді виходить за межі окремих систем і діє для цілих організацій і компаній.

Зміст

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

Мотивація

Архітектори повинні точно знати, де вони вільні у своїх проєктних рішеннях, а де мусять дотримуватися обмежень. З обмеженнями завжди доводиться мати справу; проте вони можуть бути предметом переговорів.

Форма

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

3. Контекст і межі

Відмежовує вашу систему від її (зовнішніх) партнерів зі взаємодії (сусідніх систем і користувачів). Визначає зовнішні інтерфейси. Показується з бізнес-/предметної перспективи (завжди) або з технічної перспективи (необов’язково)

Зміст

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

За потреби розрізняйте бізнес-контекст (предметні входи та виходи) і технічний контекст (канали, протоколи, апаратне забезпечення).

Мотивація

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

Форма

Різні контекстні діаграми
Списки партнерів зі взаємодії та їхніх інтерфейсів.

3.1 Бізнес-контекст

Зміст

Специфікація всіх партнерів зі взаємодії (користувачів, ІТ-систем, …) із поясненнями предметних входів і виходів або інтерфейсів. За бажанням можна додати предметні формати чи протоколи зв’язку.

Мотивація

Усі зацікавлені сторони мають розуміти, які дані обмінюються з оточенням системи.

Форма

Усілякі діаграми, що показують систему як чорну скриньку та визначають предметні інтерфейси до партнерів зі взаємодії.

Як альтернативу (або додатково) можна використати таблицю. Назва таблиці — це назва вашої системи, три стовпці містять назву партнера зі взаємодії, входи та виходи.

3.2 Технічний контекст

Зміст

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

Мотивація

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

Форма

Напр., діаграма розгортання UML, що описує канали до сусідніх систем, разом із таблицею відображення, яка показує зв’язки між каналами та входами/виходами.

4. Стратегія розв’язання

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

Зміст

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

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

Мотивація

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

Форма

Пояснюйте ці ключові рішення коротко.

Обґрунтуйте, що ви вирішили і чому саме так, виходячи з вашої постановки проблеми, цілей якості та ключових обмежень. Посилайтеся на подробиці в наступних розділах (розділ 5 — для структурних подробиць, розділ 8 — для наскрізних концепцій).

Можна використати список підходів до розв’язання або таблицю.

5. Погляд на будівельні блоки

Статична декомпозиція системи, абстракції вихідного коду, показані як ієрархія білих скриньок (що містять чорні скриньки) до відповідного рівня деталізації.

Зміст

Погляд на будівельні блоки показує статичну декомпозицію системи на будівельні блоки (модулі, компоненти, підсистеми, класи, інтерфейси, пакети, бібліотеки, фреймворки, рівні, розділи, яруси, функції, макроси, операції, структури даних, …), а також їхні залежності (зв’язки, асоціації, …)

Цей погляд обов’язковий для будь-якої документації архітектури. За аналогією з будинком це поверховий план.

Мотивація

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

Це дозволяє спілкуватися із зацікавленими сторонами на абстрактному рівні без розкриття подробиць реалізації.

Форма

Погляд на будівельні блоки — це ієрархічна колекція чорних і білих скриньок (див. рисунок нижче) та їхніх описів.

5.1 Біла скринька всієї системи

Тут ви описуєте декомпозицію всієї системи за наведеним нижче шаблоном білої скриньки. Він містить

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

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

У найкращому разі вам вистачить прикладів або простих сигнатур.

5.2 Рівень 2

Тут можна визначити внутрішню структуру (деяких) будівельних блоків рівня 1 як білі скриньки.

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

5.2.1 Біла скринька для будівельного блока 1

Визначає внутрішню структуру будівельного блока 1.

Використайте шаблон білої скриньки (див. вище).

6. Погляд на час виконання

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

Зміст

Погляд на час виконання описує конкретну поведінку та взаємодії будівельних блоків системи у формі сценаріїв з таких галузей:

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

Зауваження: головний критерій вибору можливих сценаріїв (послідовностей, робочих процесів) — їхня архітектурна релевантність. Описувати велику кількість сценаріїв не важливо. Краще задокументувати репрезентативну добірку.

Мотивація

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

Форма

Існує багато нотацій для опису сценаріїв, напр.

нумерований список кроків (природною мовою)
діаграми діяльності або блок-схеми
діаграми послідовності
BPMN або EPC (ланцюги подій і процесів)
скінченні автомати
тощо.

6.n Сценарій часу виконання n (1, 2, 3 тощо)

Вставте діаграму часу виконання або текстовий опис сценарію.

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

7. Погляд на розгортання

Технічна інфраструктура із середовищами, комп’ютерами, процесорами, топологіями. Відображення (програмних) будівельних блоків на елементи інфраструктури.

Зміст

Погляд на розгортання описує:

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

Системи часто виконуються в різних середовищах, напр. середовище розробки, тестове середовище, робоче середовище. У таких випадках слід задокументувати всі релевантні середовища.

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

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

Мотивація

Програмне забезпечення не працює без апаратного. Ця базова інфраструктура може і буде впливати на вашу систему та/або деякі наскрізні концепції. Тому вам потрібно знати інфраструктуру.

Форма

Можливо, діаграма розгортання найвищого рівня вже міститься в розділі 3.2 як технічний контекст із вашою власною інфраструктурою як ОДНІЄЮ чорною скринькою. У цьому розділі ви наблизите цю чорну скриньку за допомогою додаткових діаграм розгортання.

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

7.1 Інфраструктура рівня 1

Опишіть (зазвичай поєднанням діаграм, таблиць і тексту):

розподіл вашої системи за кількома розташуваннями, середовищами, комп’ютерами, процесорами, … а також фізичні з’єднання між ними
важливе обґрунтування або мотивацію цієї структури розгортання
якісні та/або продуктивні характеристики інфраструктури
відображення програмних артефактів (будівельних блоків) на елементи інфраструктури

Для кількох середовищ чи альтернативних розгортань скопіюйте цей розділ arc42 для всіх релевантних середовищ. **

7.2 Інфраструктура рівня 2

Тут можна навести внутрішню структуру (деяких) елементів інфраструктури з рівня 1.

Скопіюйте структуру з рівня 1 для кожного вибраного елемента.

8. Наскрізні концепції

Загальні, принципові правила та підходи до розв’язання, релевантні в кількох частинах (→ наскрізно) системи. Концепції часто пов’язані з кількома будівельними блоками. Охоплюють різні теми, як-от предметні моделі, архітектурні патерни та стилі, правила використання певних технологій і правила реалізації.

Зміст

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

Мотивація

Концепції утворюють основу концептуальної цілісності (узгодженості, однорідності) архітектури. Отже, вони є важливим внеском у досягнення внутрішньої якості вашої системи.

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

Багато цих концепцій стосуються кількох ваших будівельних блоків або впливають на них.

Форма

Форма може бути різною:

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

Структура цього розділу

Оберіть лише найпотрібніші для вашої системи теми та призначте кожній заголовок другого рівня в цьому розділі (напр. 8.1, 8.2 тощо).

НЕ НАМАГАЙТЕСЯ охопити всі теми з наведеної вище діаграми.

Передумови

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

Певні концепції можуть стосуватися всіх елементів системи, інші — лише кількох.

9. Архітектурні рішення

Важливі, дорогі, критичні, великомасштабні або ризиковані архітектурні рішення разом з обґрунтуваннями.

Зміст

Важливі, дорогі, великомасштабні або ризиковані архітектурні рішення разом з обґрунтуваннями. Під «рішеннями» ми розуміємо вибір однієї альтернативи за заданими критеріями.

Скористайтеся власним судженням, щоб вирішити, чи архітектурне рішення слід задокументувати тут, у цьому центральному розділі, чи краще задокументувати його локально (напр., у шаблоні білої скриньки одного будівельного блока). Уникайте надлишкових текстів. Зверніться до розділу 4, де ви вже зафіксували найважливіші рішення своєї архітектури.

Мотивація

Зацікавлені сторони вашої системи повинні мати змогу зрозуміти й відтворити ваші рішення.

Форма

ADR (запис архітектурного рішення) для кожного важливого рішення
список або таблиця, упорядковані за важливістю та наслідками, або
докладніше у формі окремих розділів для кожного рішення

Передумови (щодо ADR)

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

знають про рішення, бо воно видиме, напр., у вихідному коді, але
не знають мотивації цього рішення (див. Nygard 2011)

Тому слід документувати кілька важливих рішень разом із їхньою мотивацією, міркуваннями

Наша пропозиція щодо рішень

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

10. Вимоги до якості

Вимоги до якості у вигляді сценаріїв, з деревом якості для надання високорівневого огляду. Найважливіші цілі якості мали бути описані в розділі 1.2 (цілі якості).

Зміст

Цей розділ містить усі релевантні вимоги до якості.

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

Мотивація

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

Додаткова інформація

Дивіться розлогу модель якості Q42 на https://quality.arc42.org.

10.1 Огляд вимог до якості

Зміст

Огляд або підсумок вимог до якості.

Мотивація

Часто ми стикаємося з десятками (або навіть сотнями) детальних вимог до якості. У цьому оглядовому розділі слід спробувати підсумувати їх, напр. описавши категорії чи теми (як пропонують ISO 25010:2023 або Q42

Якщо ці підсумкові описи вже точні, достатньо конкретні та вимірні, розділ 10.2 можна пропустити.

Форма

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

У літературі також описано ідею дерева атрибутів якості, яке ставить загальний термін «якість» у корінь і використовує деревоподібне уточнення терміна «якість». [Bass+21] запровадили для цього термін «дерево корисності атрибутів якості» (Quality Attribute Utility Tree).

10.2 Сценарії якості

Зміст

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

Особливо корисні два види сценаріїв:

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

Форма

Типова інформація для детальних сценаріїв охоплює таке:

У короткій формі (віддається перевага в моделі Q42):

Контекст/Тло: який вид системи чи компонента, яке оточення чи ситуація?
Джерело/Стимул: хто або що ініціює чи запускає поведінку, реакцію або дію.
Метрика/Критерії прийняття: відповідь, що містить міру чи метрику

Довга форма сценаріїв (якій віддають перевагу SEI і [Bass+21]) детальніша і містить таку інформацію:

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

Дивіться також

Із січня 2023 року arc42 пропонує прагматичну модель якості, яка радить позначати вимоги до якості хештегами чи мітками, як-от #flexible, #efficient, #usable, #operable, #testable, #secure, #safe, #reliable.

11. Ризики і технічний борг

Відомі технічні ризики або технічний борг. Які потенційні проблеми існують у системі чи навколо неї? Що змушує команду розробників почуватися кепсько?

Зміст

Список виявлених технічних ризиків або технічних боргів, упорядкований за пріоритетом

Мотивація

«Управління ризиками — це управління проєктами для дорослих» (Тім Лістер, Atlantic Systems Guild.)

Це має бути вашим девізом для систематичного виявлення та оцінювання ризиків і технічних боргів в архітектурі, які знадобляться керівним зацікавленим сторонам (напр., менеджерам проєктів, власникам продукту) як частина загального аналізу ризиків і планування заходів.

Форма

Список ризиків та/або технічних боргів, імовірно, із запропонованими заходами для мінімізації, пом’якшення чи уникнення ризиків або зменшення технічних боргів.