Документирование архитектуры мобильного приложения
Архитектурная документация нужна в трёх случаях: новый разработчик должен понять систему за день, а не за две недели; команда обсуждает расширение — и все смотрят на разные ментальные модели одного и того же приложения; проект передаётся другой команде или заказчику.
Что документируем и как
Не пишем «Приложение использует MVVM» в README. Документируем решения и их причины.
C4 Model — практичный стандарт для мобильных систем. Четыре уровня детализации:
- Context — мобильное приложение в контексте пользователей, внешних систем, бэкенда
- Containers — iOS app, Android app, API backend, push notification service, CDN
- Components — внутри iOS app: Authentication Module, Feed Module, Payment Module
- Code — классы и интерфейсы внутри конкретного модуля (только для сложных частей)
Инструменты: Structurizr (DSL для C4, рендерит диаграммы из кода — диаграммы всегда актуальны если их обновлять вместе с кодом), draw.io / Miro для менее формальных схем.
ADR (Architecture Decision Records) — короткие документы формата «мы выбрали X вместо Y потому что Z». Файл в репозитории: docs/adr/0001-use-swiftui-over-uikit.md. Новый разработчик читает ADR и понимает почему так, а не переоткрывает решения заново.
Диаграммы потоков данных. Как данные движутся от API до экрана: сетевой слой → кеш → ViewModel → View. Для офлайн-режима: локальная БД → ViewModel → sync queue → API. Рисуем sequence diagram для нетривиальных флоу (авторизация через Apple, background sync).
Минимально необходимый набор
Для среднего мобильного приложения (2–4 разработчика, 50+ экранов):
- README с onboarding-инструкцией (как запустить проект, версии Xcode/Android Studio/Flutter SDK, переменные окружения)
- Архитектурная схема C4 уровня Containers (одна страница)
- Описание ключевых архитектурных паттернов: «используем Clean Architecture, данные идут Repository → UseCase → ViewModel → View»
- ADR для каждого неочевидного технического решения
- Документация по CI/CD: что запускается при PR, что при merge в main
Не нужно документировать очевидное. Не нужна диаграмма для каждого класса — IDE покажет. Нужны именно те решения, логика которых не видна из кода.
Сроки: аудит существующей кодовой базы и создание документации с нуля — 1–2 недели. Поддержка в актуальном состоянии — встроена в процесс: новый ADR при каждом архитектурном решении, схемы обновляются при изменении структуры.