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