Иногда архитектура системы «есть» — но ответить на простой вопрос всё равно сложно.

Например:

Что происходит после того, как пользователь нажал кнопку «Оплатить заказ»?

На первый взгляд ответ очевиден: frontend вызывает backend, backend создаёт заказ, идёт в платёжный сервис, сохраняет данные и отправляет письмо.

Но если начать разбирать сценарий чуть подробнее, картина обычно становится менее простой.

Какой именно endpoint вызывает frontend? Где проверяется наличие товара? В какой момент создаётся заказ? Платёж подтверждается синхронно или отдельным webhook’ом? Что происходит, если платёж прошёл, а резервирование товара — нет? Когда публикуется событие в брокер? Может ли письмо уйти до того, как заказ окончательно сохранён?

В работающей системе ответы на эти вопросы почти всегда существуют. Но они редко находятся в одном месте.

Часть живёт в коде. Часть — в OpenAPI-спецификации. Что-то можно увидеть в логах. Какие-то детали помнит разработчик, который внедрял интеграцию год назад. А схема на доске чаще всего показывает только то, что Order Service каким-то образом связан с Payment Service.

Для общего понимания системы этого достаточно. Для проектирования, ревью и изменения бизнес-логики — уже нет.

C4-модель хорошо отвечает на вопрос: из каких частей состоит система и как они связаны между собой.

Но в реальной работе команды регулярно возникает другой вопрос:

Как именно конкретное бизнес-действие проходит через систему?

Не просто «какие сервисы у нас есть», а какой путь проходят данные при регистрации пользователя, оформлении заказа, подтверждении платежа, выдаче доступа или обработке webhook’а.

Именно для этого в Viaduct появился функционал Magic Flows.

Magic Flow — это последовательность взаимодействий между элементами архитектурной модели. Для каждого шага можно задать:

• понятное имя шага;

• описание того, что на нём происходит;

• источник и получателя;

• связь между ними;

• конкретный endpoint, сообщение или другой технический контракт.

На скриншоте выше показан поток Payment leaves the bank. Он состоит из семи шагов: пользователь отправляет перевод, запрос проходит через API, транзакция записывается, публикуется событие payment.requested, клиент получает уведомление, браузер получает подтверждение и показывает пользователю результат.

Первый шаг называется Submits a transfer. В нём Single-Page Application отправляет запрос в API Gateway:

POST /api/payments

В описании зафиксирован не только технический вызов, но и его смысл: пользователь передаёт сумму и целевой IBAN. Это маленькая деталь, но именно такие детали превращают набор архитектурных связей в объяснимый бизнес-сценарий.

Дальше поток можно открыть в плеере и пройти визуально: откуда выходит запрос, куда он приходит, какой сервис участвует следующим и какие связи соединяют участников. А затем на основе этой же последовательности автоматически собрать sequence diagram.

Один сценарий вместо десятка разрозненных артефактов

В примере поток называется Payment leaves the bank.

Он отвечает на более узкий и полезный вопрос:

Как пользовательский перевод попадает из браузера в банковскую систему и каким путём возвращается результат?

Это важное ограничение.

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

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

Поэтому для Magic Flows лучше выбирать один понятный сценарий с конкретной целью.

Например:

• пользователь отправляет перевод;

• пользователь входит в систему;

• система обрабатывает webhook от платёжного провайдера;

• оператор подтверждает подозрительную операцию;

• клиент получает банковскую выписку;

• сервис выдаёт доступ после успешной оплаты.

Каждый такой сценарий становится отдельным потоком. У него есть имя, краткое описание и последовательность шагов.

В нашем примере описание потока выглядит так:

A transfer is written locally, settled through the core ledger, then fanned out to notifications and fraud scoring.

Уже по одной фразе понятно, что перевод не заканчивается в момент вызова API: он должен быть записан локально, обработан core ledger и затем передан в другие части системы — уведомления и antifraud.

Такое описание полезно ещё до того, как команда начнёт обсуждать детали endpoint’ов, очередей или транзакций. Оно фиксирует границы сценария и его ожидаемый результат.

От списка шагов к пути через систему

После первого шага поток продолжается уже внутри банковской платформы.

Запрос проходит через API, запись о переводе появляется в нужном хранилище, публикуется событие payment.requested, после чего к сценарию подключаются уведомления и antifraud. В финале клиентское приложение получает подтверждение и показывает пользователю результат.

Magic Flow не требует рисовать отдельную диаграмму для каждого сценария вручную. Поток использует уже существующую C4-модель: сервисы, контейнеры, компоненты, связи и endpoint’ы.

То есть сначала команда описывает структуру системы, а затем добавляет поверх неё важные пути данных и бизнес-действий.

Это особенно полезно в системах, где один сценарий проходит через несколько стилей взаимодействия.

Проигрываем сценарий

После того как поток описан, его можно открыть в плеере.

Плеер проходит шаги последовательно и подсвечивает текущий переход на архитектурной схеме. Сначала видно, как Single-Page Application отправляет перевод в API Gateway. Затем фокус переходит к следующему участнику процесса: API, сервису платежей, хранилищу, брокеру сообщений или внешней системе.

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

Это особенно удобно в трёх ситуациях.

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

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

• Изменение системы. Перед изменением endpoint’а, очереди, модели данных или внешней интеграции можно быстро найти сценарии, которые затронет это изменение.

Для меня это ближе к прохождению маршрута в навигаторе.

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

Sequence diagram из того же потока

После того как путь описан шаг за шагом, из него можно автоматически собрать sequence diagram.

Это полезно, потому что sequence diagram и архитектурная модель часто живут отдельно друг от друга.

Архитектурную схему рисуют в одном инструменте. Последовательность вызовов — в PlantUML, Mermaid, Excalidraw или где-то в Confluence. Затем меняется endpoint, появляется новый сервис, HTTP-вызов становится асинхронным, добавляется очередь — и один из документов перестаёт соответствовать реальности.

Magic Flow уменьшает количество таких независимых артефактов.

В нём уже есть всё необходимое для последовательностной диаграммы:

• участники сценария;

• порядок взаимодействий;

• направление каждого перехода;

• описание шага;

• связи, через которые проходит взаимодействие;

• endpoint’ы, события или другие контракты.

Поэтому sequence diagram можно построить на основе потока, а не поддерживать вручную как отдельный источник информации.

Для сценария банковского перевода такая диаграмма может показать примерно следующую последовательность:

Если сценарий имеет сложные ветвления, ретраи, компенсационные действия или долгие асинхронные процессы, это стоит явно отражать в модели и при необходимости дорабатывать sequence diagram. Но базовая последовательность больше не существует отдельно от архитектуры: она выводится из того же потока, который команда проходит в плеере.

Это особенно полезно перед ревью. Можно сначала открыть Magic Flow и пройти сценарий на общей архитектурной схеме, а затем переключиться на sequence diagram, когда нужно обсудить порядок сообщений, синхронные и асинхронные границы или конкретные API-контракты.

Документация в контексте сценария

У бизнес-сценария почти всегда есть контекст, который не помещается в названия шагов.

Например:

• почему перевод сначала записывается локально, а потом передаётся в core ledger;

• какие поля обязательны в POST /api/payments;

• как устроена идемпотентность платежного запроса;

• что считается успешным статусом;

• почему antifraud запускается после публикации события;

• что происходит при повторной доставке сообщения;

• какие ограничения действуют для переводов между странами или валютами.

Обычно эта информация разбросана по wiki, ADR, API-спецификациям, тикетам и комментариям в коде. При обсуждении потока команда вынуждена искать её отдельно или опираться на память людей.

В Magic Flows к потоку можно прикреплять документацию.

Это может быть:

• страница с описанием бизнес-процесса;

• OpenAPI-спецификация или документация endpoint’а;

• ADR с архитектурным решением;

• требования к безопасности;

• описание событий и схем сообщений;

• runbook для поддержки;

• ссылка на dashboard, trace или issue.

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

Ссылка на сервис: Viaduct