Архітектурна документація мобільного застосунку: вузькі місця
Мобільний застосунок роками обростає модулями: шар роботи з мережею, локальний кеш, фонова синхронізація, навігація, відмальовування екранів.
Поки структура й звʼязки між частинами живуть у голові двох розробників, будь-яка правка перетворюється на розвідку — щоб виправити відображення списку, інженер читає пʼять файлів і все одно не може заздалегідь сказати, що ще зачепить зміна.
Ціна такої невизначеності вимірюється не в балах, а в строках.
Нова людина в команді виходить на першу самостійну правку не за тиждень, а за місяць; доопрацювання тягнуть побічні регресії в найнесподіваніших місцях — від екрана оформлення замовлення до обробки вхідного сповіщення.
Рішення ухвалюються наосліп: ніхто не памʼятає, чому кеш влаштований саме так і що зламається, якщо його зняти.
Вузькі місця архітектури майже завжди одні й ті самі: немає опису архітектури як такої, тобто шарів і напрямку залежностей, не зафіксовано межі модулів, відсутня історія рішень — чому вибрано такий спосіб синхронізації й від чого відмовилися.
Без цього розбір структури застосунку починається заново за кожної великої зміни, а оцінка строків тримається на інтуїції.
Саме тому архітектурна документація мобільного застосунку в нас — живий артефакт, а не тека із зображеннями: схема за рівнями в нотації C4, короткі записи щодо кожного значущого рішення, карта залежностей модулів і маршрут онбордингу. Далі розбираємо, з чого складається такий комплект і як він залишається актуальним.
Ефект: швидкість введення новачків, релізи, відкати
Документація окупається не самим фактом існування, а тим, що її відсутність видно в календарі.
Тому до старту робіт фіксуємо чотири вимірювані величини: час до першої прийнятої правки в нового інженера, частка випусків, що вийшли за планову дату, кількість переробок через неправильно зрозумілі вимоги й час повернення до попередньої стабільної збірки.
- Введення розробника. Замість трьох-чотирьох тижнів на розбір чужої логіки — 5-7 робочих днів до першої самостійної правки: межі модулів, схема даних і звʼязки між сервісами описані в нотації C4, діаграми генеруються з Structurizr, а не домальовуються руками, тому не розходяться з кодом.
- Незалежність від одного інженера. Кожне значуще рішення живе як ADR: контекст, розглянуті альтернативи, наслідки й умови перегляду. Носій знання перестає бути єдиною точкою відмови — відпустка або вихід фахівця не зупиняє напрям.
- Передбачуваність випусків. Частка незапланованих переробок падає: стики інтеграцій, порядок міграцій і залежності між модулями відомі до початку роботи, а не зʼясовуються на прийманні.
- Відкат. Заздалегідь описаний порядок повернення до стабільної версії — оборотні міграції, стан локальних сховищ, черговість кроків — скорочує відновлення після збою з годин до хвилин.
Ці показники знімаємо не одноразово: документація оновлюється в тій самій зміні, що й код, інакше за кілька ітерацій цифри повертаються до вихідних.
Формати опису архітектури: схеми, рішення, правила
Жоден формат не описує застосунок цілком — у кожного своя зона й своя ціна підтримки в актуальному стані. Оглядові схеми вводять нового інженера й фіксують межі системи, записи про рішення не дають знову відкривати закриті питання, а регламент випуску відповідає за експлуатацію. Нижче — чесне порівняння: де формат сильний і де він перестає працювати.
| Варіант | Коли підходить | Обмеження |
|---|---|---|
| Схеми рівнів контексту й контейнерів | Онбординг, розмова про межі системи, розподіл зон відповідальності | Не пояснюють внутрішній устрій модулів; застарівають без регламенту оновлення; не зберігають причини вибору |
| Записи про архітектурні рішення | Спірні зміни: сховище, розбиття на модулі, схема синхронізації | Читаються лише в звʼязці зі схемою; потребують дисципліни ведення; окремо не дають загальної картини |
| Карта інтеграцій і зовнішніх сервісів | Передача проєкту на підтримку, оцінка ризиків, заміна зовнішнього сервісу | Не описує внутрішню логіку застосунку; застаріває за кожної зміни зовнішнього сервісу |
| Регламент випуску версій | Експлуатація: збірка, перевірки, канали випуску, відкат на попередню версію | Це процес, а не опис системи; не відповідає на питання «як влаштовано» й «чому так» |
Набір закриває три різні питання: як влаштовано, чому так і як це випускається. Якщо залишити лише схеми, рішення будуть знову відкриватися в кожній новій команді; якщо лише записи — новий інженер не побачить систему цілком. Тому формати зберігаємо в одному місці й повʼязуємо посиланнями.
Етапи роботи: від інтервʼю до передачі команді
Замовнику потрібна не стопка діаграм, а опис, який збігається з кодом і працює без автора. Тому ми йдемо від фактів до документа: спочатку розбираємо поточний стан, потім проєктуємо структуру, а наприкінці перевіряємо результат на живих задачах. Порядок етапів фіксований — він захищає від опису «як задумувалося» замість «як є».
- Аудит поточної архітектури. Читаємо репозиторії, конфігурацію збірки та межі модулів, відновлюємо реальні залежності між шарами. Фіксуємо розбіжності: де схема на дошці не збігається з тим, що компілюється й потрапляє в реліз.
- Інтервʼю з командою розробки. По кожному шару витягуємо негласні домовленості, історичні рішення й обхідні шляхи — без них опис виходить правильним за формою й марним на практиці.
- Проєктування структури опису. Визначаємо, які рівні C4 потрібні саме цьому продукту, з яких тем заводимо ADR і що потрапляє в онбординг новачка. Склад розділів узгоджуємо до написання, щоб не переписувати.
- Наповнення. Збираємо діаграми, ADR з контекстом, рішенням і наслідками, глосарій і карту точок інтеграції. Кожна схема супроводжується посиланням на ділянку коду, яку вона описує.
- Перевірка схем на реальних сценаріях. Проганяємо типові задачі — додати екран, замінити зовнішній сервіс, випустити реліз — і перевіряємо, чи достатньо опису, щоб пройти шлях, не заглядаючи щоразу в код або до автора.
- Передача опису команді. Проводимо розбір з розробниками, розміщуємо документи поруч із кодом і домовляємося про правило: значуще рішення фіксується ADR у тому ж наборі змін, що й код.
Після передачі в команди залишається точка входу для нового інженера й живе джерело правди з архітектури — він оновлюється разом із продуктом, а не окремим героїчним зусиллям раз на рік.
Комплект на виході: схеми, регламенти, доступи
Після здачі в замовника залишається не презентація, а робочий комплект: за ним чергують, випускають релізи, відкочуються й вводять нових інженерів у проєкт.
Артефакти живуть поруч із кодом і правляться в тому ж наборі змін — документ, який розходиться з реальністю, вважаємо браком.
- Карта архітектури за C4: контекст, контейнери й компоненти — з чого складається застосунок, які в нього зовнішні залежності й де проходять межі сервісів.
- Схеми інтеграцій: мережа, черги, сховища, офлайн-режим — з описом того, що відбувається за недоступності кожної сторони.
- Політики доступу й ролі: права розробника, тестувальника, підтримки й підрядника, порядок надання й відкликання доступів до збірок і сховищ.
- Регламент випуску: гілкування, обовʼязкові перевірки й точки підтвердження перед публікацією — хто й що фіксує на кожному кроці.
- Регламент відкату: ознаки деградації, поріг спрацювання й порядок дій, включно з долею користувацьких даних.
- Журнал архітектурних рішень: що вибрали, які альтернативи відкинули й з якої причини — логіка не відновлюється з листування.
- Гід з онбордингу: як підняти середовище, зібрати збірку й де лежать ключові модулі.
Комплект перевіряємо на живому сценарії: інженер, який не брав участі в проєкті, розгортає середовище й вносить першу правку за документами. Де він спотикається — дописуємо схему або регламент, а не пояснюємо голосом.
Кейс: скоротили строки введення нових розробників удвічі
Застосунок на дві платформи, чотири продуктові команди, розподілений найм. Документація на старті була такою: десяток діаграм у спільному сховищі, частина — без дати й уже не збігалася з кодом, рішення з архітектури жили в історії листування.
Новий розробник збирав картину за кодом і питаннями в чат: до першої самостійної зміни в проді проходило пʼять-шість тижнів.
Ми звели все в один контур. Контекст і контейнери за C4 тримаємо як код у Structurizr — модель лежить поруч із репозиторієм і перезбирається автоматично, руками діаграми ніхто не малює. На кожне значуще рішення — короткий ADR: контекст, розглянуті варіанти, вибраний, наслідки.
Окремо зʼявилися три сторінки, яких раніше не було зовсім: карта модулів та їхніх меж, потоки даних між ними, порядок збірки й випуску.
Зміни архітектури тепер проходять через той самий розбір коду, що й правки: якщо рішення змінює межі модулів, оновлення діаграми й ADR — частина тієї ж гілки. Так прибрали головне джерело розбіжностей — документацію, яку правлять «потім».
Що стало після:
- строки введення нового розробника — з пʼяти-шести тижнів до двох із половиною;
- перший самостійний випуск — на сьомий-девʼятий робочий день замість пʼятого тижня;
- частка збоїв після випуску — з ~18% до 5%, і майже всі решта на стиках із зовнішніми сервісами, а не всередині продукту.
Ключове тут не обсяг документації, а єдина точка входу: людина за один вечір бачить устрій застосунку, його межі та причини рішень. Далі вона змінює код, не ламаючи приховані контракти.
Чим архітектурне рішення відрізняється від технічного завдання?
Технічне завдання відповідає на питання «що зробити»: які екрани й сценарії є в застосунку, які дані звідки беруться, за якими критеріями роботу приймуть. Це документ обсягу й приймання — за ним оцінюють трудовитрати й закривають етапи. Але він не пояснює, чому вибрано таку структуру й які альтернативи відкинули.
Архітектурне рішення або технічне завдання — не конкурентні документи, а різні рівні опису.
Рішення фіксує причини: чому стан зберігається локально, а не запитується на кожному екрані; чому фонову синхронізацію винесено окремо; що станеться, якщо мережа зникла на середині операції.
Чим відрізняється опис рішення — тим, що поруч із вибором стоїть відкинута альтернатива й ціна, якою він обійшовся.
Межі застосовності рішення — найнедооціненіша частина. Прямо зазначено, до якого обсягу даних конструкція тримає навантаження, а де ламається: наприклад, під час переходу на повний офлайн-режим або за появи другого каналу продажів.
Без цієї межі наступний інженер або боїться торкати робочий код, або ламає його, не розуміючи, що саме тримало систему.
Різниця видна на зміні команди: завдання читається як список фактів, рішення — як пояснення, тому новий розробник входить у проєкт за дні, а не за місяці.
Ми ведемо обидва документи паралельно й оновлюємо опис за кожної зміни архітектури — інакше воно швидко перетворюється на художню літературу.
Часті сумніви: підтримка, доступи, зміни
Сумніви зазвичай стосуються не самої документації, а супутніх умов: продукт давно в продакшені, доступи потрібно комусь надати, а опис застаріває швидше, ніж його встигають читати. Розберемо три питання, які найчастіше виринають до старту робіт.
Окремо про зміну підрядника: матеріали мають лежати в контурі замовника, а не в чужому сховищі, інакше разом із командою йде й розуміння системи. Нижче — як це влаштовано на практиці.
Застосунок уже запущено — архітектуру ще можна описати?
Так. Для працюючого продукту опис збирають із трьох боків: структура модулів і точок інтеграції — за репозиторієм, схема даних і міграції — за фактичним станом сховища, маршрути запитів — за логами й конфігурацією середовищ.
Далі схема C4 і рішення у форматі ADR відновлюються й звіряються з командою, а розбіжності фіксуються як відкриті питання, а не замовчуються.
Хто й з якими правами отримає доступ до документації?
Матеріали розміщуємо в репозиторії замовника: розробникам — запис через обовʼязкове ревʼю, аналітикам і керівникам напряму — читання. Правки в описі архітектури й ADR проходять той самий процес погодження, що й код, тому в історії видно, хто й чому змінив рішення.
Як опис залишається актуальним за зміни команди?
Свіжість зашивається в процес, а не в усну домовленість: зміна архітектури без оновлення відповідного розділу не проходить перевірку під час злиття, а ревізія схеми входить у чек-ліст релізу.
Новий інженер або підрядник входить у проєкт за документом, а не за розповідями попередньої команди.
Обговоримо вашу задачу й повернемося з планом
Щоб старт опису архітектури не розтягнувся на місяці листування й уточнювальних питань, до першої розмови достатньо зібрати кілька вхідних даних. Нічого екзотичного — зазвичай це вже є в команди, яка веде продукт. За цими даними ми відразу бачимо межі системи й обсяг майбутньої документації.
- Цільові платформи й мінімальні підтримувані версії операційних систем.
- Перелік ролей користувачів і 5–10 ключових сценаріїв, які застосунок має закривати.
- Список зовнішніх систем для інтеграції — платежі, аналітика, внутрішні сервіси — і формати обміну даними з ними.
- Доступи до репозиторіїв, трекера задач і макетів: на читання достатньо.
- Чинна документація й рішення, які не можна змінювати: контракти обміну, схеми даних, вимоги безпеки.
- Обмеження за строками релізу, вимоги регуляторів і режими роботи без мережі.
- Відповідальний за приймання рішень з боку замовника — одна людина, а не комітет.
Формат нас не сковує: працюємо і зі схемами C4, і з журналом рішень у дусі ADR, і з текстовими описами для онбордингу нових розробників.
Опишіть задачу у вільній формі — повернемося з оцінкою та планом робіт: складом документів, порядком їх підготовки й точками, де потрібне ваше підтвердження.
