Как составить карту архитектуры уже существующей программы?

#Пять проходов

1. Что запущено и где

   Среды, что в каждой развёрнуто, что работает по расписанию и что работает, чего нет в репозитории. По консоли облака и crontab, а не по разговору.

2. Опись

   Каждый компонент с каноническим типом и одним читаемым предложением. Сервисы, модули, базы, очереди, задачи по расписанию, фронтенды, внешние системы.

   Канонический тип важен: свободные формулировки вида приводят к тому, что два анализа одной системы дают несравнимые списки.

3. Связи

   Что что использует, от чего зависит, откуда читает, куда пишет или что реализует — и в какую сторону. Направление здесь не украшение: оно решает, что сломается, когда что-то встанет.

4. Границы

   Предоставляемые и потребляемые интерфейсы. По каждому: маршрут или канал, зачем он, как аутентифицируется и что происходит при сбое.

   Именно в последних двух правдоподобная реализация и правильная больше всего похожи друг на друга.

5. Что установить не удалось

   Каждый вопрос, который проходы выше подняли и не закрыли, с причиной и приоритетом. Записанный на карте, а не оставленный за её пределами.

#Что записывать по каждому элементу

#Поле, о котором забывают все

Карта без устойчивой идентичности прекрасно работает в первый раз и перестаёт работать на втором обновлении.

Чтобы потом сказать, что компонент изменился, а не что один исчез и появился другой, две версии карты должны согласиться, что описывают одно и то же. Имена этого не несут:

• Переименуйте класс — это тот же класс.
• Назовите две вещи «Основная база» — это по-прежнему две разные вещи.
• Переместите файл — и вся идентичность, построенная на путях, ломается разом.

Поэтому дайте каждому элементу что-то устойчивое, по чему его узнают: путь в репозитории, полное имя или метку, которую вы выбрали и держите для того, у чего нет ни первого, ни второго, — базы, очереди, среды развёртывания, облачного ресурса. Элемент, у которого нет ни одного из трёх, при каждой пересборке карты оказывается новым.

SERVICE     Биллинг
            путь: app/Services/Billing/
            полное имя: App\Services\Billing\BillingService

DATABASE    Основная база
            внешний id: db.main
            (ни пути, ни полного имени — идентичность в метке)

QUEUE       Очередь платежей
            внешний id: queue.payments

#Одна система, пять иерархий

Компонент одновременно лежит больше чем в одном дереве, и именно схлопывание их в одно делает большинство архитектурных документов «почти верными».

Платёжный сервис находится внутри приложения, внутри развёртывания и внутри бизнес-возможности. Это три разных родителя, и попытка загнать их в одну иерархию каждый раз теряет информацию.

• Приложение — из чего софт состоит, в терминах софта.
• Бизнес — что он делает, в терминах компании.
• Организация — кто чем владеет.
• Развёртывание — что где работает.
• Данные — какая информация существует и где она живёт.

В первый день все пять не нужны. Нужно записывать вложенность как принадлежащую названному представлению, а не как единственное дерево, — иначе второе представление окажется переписыванием, а не дополнением.

#Когда рисовать схему

После того как есть список, а не до. Схема, нарисованная первой, становится тем, о чём спорят, и зашивает в себя решения — что включить, что объединить, что опустить, — которые должны приниматься из доказательств, а не из того, что помещается на слайд.

Когда список есть, схема по-настоящему полезна и дёшева: это вид на то, что у вас уже имеется. Честной её держат два правила:

• Ставьте дату и указывайте, из чего она выведена. Схема без даты неопровержима.
• Не позволяйте ей стать источником. Когда схема и анализ расходятся, ссылки приложены к анализу.

#Как удерживать её верной

Карту стоит иметь, только пока она верна, и провал всегда один и тот же: её производят один раз, как проект, а потом обновлять её оказывается некому.

Предотвращают это две вещи:

1. Сделайте пересборку дешёвой. Если обновление карты стоит полудня чьего-то внимания, оно не случится. Если оно стоит одной инструкции — случится.
2. Пересобирайте по событиям, а не по календарю. После релиза, в конце этапа работ, когда приземлилась подсистема, перед передачей. Квартальный ритм даёт обновления, которые никто не читает, и пропускает те, что имели значение.

Тогда ценность оказывается в разнице между двумя версиями, а не в любой из них: что появилось, что изменилось, что ушло и какие прежние утверждения больше ничем не поддержаны.

#Что идёт не так

#Чего карта сказать не может