Architecture Course Home / Архитектурная деятельность / Архитектурное моделирование / Процесс проектирования архитектуры / Практический пример: Платёжные выписки

ADR. Платёжные выписки

⚠️ Рекомендация по ADR

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

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

Глоссарий

Контекст

Формулировка проблемы

Необходимо спроектировать продукт "Выписки".

Проектирование выписок усложняется большим числом интеграций с "внешними" системами. 

Информация о операциях хранится в разных системах банка:


Окружение проблемы

В данном сценарии рассматривается банк с активной пользовательской базой в 500к пользователей, с перспективами роста до 1кк. Банк давно на рынке с устаявщейся культурой и процессами разработки. В банке постоянно запускаются новые продукты. Большое разнообразие PaaS. Имеются принципы и стандарты разработки. Разработка ведется предпочтительно в крос-функциональных, продуктовых командах использую гибкие методологии Agile.

Надёжность

Наше окружение бесплатно предоставляет нам высокую дотступность наших решений:

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

Безопастность

Наша инфраструктура бесплатно даёт нам системы:

Проблемы безопастности не будет затрагиваться на этом этапе проектирования.

Цель

Разработать инициализирующий дизайн для системы генерации платежных выписок.

Требования, ограничения и сценарии атрибутов качества

Функциональные требования (ФТ)

ID

Описание требования

Заказчик

Приоритет (H/M/L)

FR-001Пользователь личного кабинета хочет запрашивать выписку за указанный интервал времени, чтобы анализировать данные за нужный мне период.Технолог. Вася ПупкинH
FR-002Пользователь личного кабинета хочет запрашивать выписку с фильтром по счету, чтобы получать данные только по выбранному мной счету.Технолог. Вася ПупкинH
FR-003Пользователь личного кабинета хочет запрашивать выписку с фильтрацией по категории, чтобы быстро найти операции нужного типа.Технолог. Вася ПупкинM
FR-004Пользователь личного кабинета хочет запрашивать выписку с фильтрацией по бренду, чтобы отслеживать операции, связанные с конкретным брендом.Технолог. Вася ПупкинM
FR-005

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

Технолог. Вася ПупкинM
FR-006Пользователь личного кабинета хочет запрашивать выписку по произвольной строке поиска, чтобы быстро находить нужную информацию по ключевым словам.Технолог. Вася ПупкинL
FR-007Пользователь личного кабинета хочет скачивать сгенерированную выписку, чтобы использовать её вне личного кабинета.Технолог. Вася ПупкинH
FR-008Пользователь личного кабинета хочет задавать правила генерации регулярных выписок (устанавливать фильтр и задавать расписание в формате CRON), чтобы регулярно получать нужную информацию без дополнительных ручных действий.Технолог. Вася ПупкинH
FR-009Пользователь личного кабинета хочет получать уведомления на почту по завершении генерации выписки, чтобы своевременно узнать, когда данные готовы.Технолог. Вася ПупкинH
FR-010Пользователь личного кабинета хочет, чтобы система автоматически запускала генерацию выписки по заданному мной расписанию, чтобы регулярно получать актуальную информацию без участия пользователя.Технолог. Вася ПупкинH

Нефункциональные требования (НФТ)

ID

Связанные сценарии

Описание требования

Заказчик

Приоритет (H/M/L)

Влияние на архитектуру (H/M/L)



Security


NFR-001ВсеСистема должна обеспечивать разграничение доступа к данным по компании: пользователь может получить доступ только к данным той компании, в которой он является сотрудником. Попытки доступа к чужим данным должны блокироваться и логироваться.ИБ. Саша ПуговкинHL
NFR-002ВсеСотрудник службы поддержки должен иметь возможность получать доступ к данным любой компании, при наличии соответствующих прав доступа.ИБ. Саша ПуговкинHL
NFR-003ВсеВнутренние системы должны использовать механизмы аутентификации и авторизации для доступа к системеИБ. Саша ПуговкинML


Reliability




NFR-004

Все

Система должна продолжать работать в 99.8 % времени даже при выходе из строя любого из компонент системыSRE. Петя ЯковлевHH
NFR-005ВсеПри недоступности источника операций система должна обеспечивать доступность не менее 80% пользовательского функционала, критичного для основного сценария использованияSRE. Петя ЯковлевHH


Scalability/Performance


NFR-006ВсеСистема должна выдерживать нагрузку 20к DAUТехнолог. Вася ПупкинHL
NFR-007ВсеК 2026 г. DAU должно увеличиться до 100к. Система должна предсказуемо масштабироваться.Технолог. Вася ПупкинHM
NFR-008FR-001, FR-002Система должна хранить данные за весь период (предположительный объем данных на 2026 г будет 6 тб. прирост данных каждый год 1 тб)Технолог. Вася ПупкинHH
NFR-009FR-001, FR-002Для 20к DAU выписка за пол года формируется за 1 минутуТехнолог. Вася ПупкинHL
NFR-010FR-007Система должна хранить сгенерированные выписки в течении 1 года. Дальше выписки удаляются (предполагаемый объем хранимых данных 1 тб).Технолог. Вася ПупкинML


Resource Utilization


NFR-011FR-010Формирование регулярных выписок нагружает систему не больше 30% от номинальногоDPHL


Agility


NFR-012ВсеСистема должны быть лёгкой в расширении и сопровожденииТехнолог. Вася ПупкинMH

Ограничения

ID

Описание требования

Заказчик

Влияние на архитектуру (H/M/L)

CON-001

Корпоративные стандарты (IT как Lego)

  • postgresql
  • cassandra
  • redis
  • k8s
  • kafka
  • ...
IT как LEGOH
CON-002Стек разработки .Net. Команда формируется вокруг этого стека т.к. вектор бизнес линии идёт в сторону диверсификации рисков связанных с наймом scalaТехнолог. Вася ПупкинL
CON-003Срок разработки конец 2023 годаТехнолог. Вася ПупкинM

Выделение архитектурно значимых требований

ID

Описание требования

Причина ASR

NFR-004

Система должна продолжать работать в 99.8 % времени даже при выходе из строя любого из компонент системы

Влияние на надежность
NFR-005При недоступности источника операций система должна обеспечивать доступность не менее 80% пользовательского функционала, критичного для основного сценария использования.Влияние на надежность
NFR-007К 2026 г. DAU должно увеличиться до 100к. Система должна предсказуемо масштабироваться.Влияние на масштабируемость
NFR-008Система должна хранить данные за весь период (предположительный объем данных на 2026 г будет 6 тб. прирост данных каждый год 1 тб)Влияние на масштабируемость
NFR-012Система должны быть лёгкой в расширении и сопровожденииВлияние на гибкость
CON-001

Корпоративные стандарты (IT как Lego)

  • postgresql
  • cassandra
  • redis
  • k8s
  • kafka
  • ...
Ограничивает возможный дизайн
CON-003Срок разработки конец 2023 годаВлияние на сроки

Решение

Раунд 1. Функциональная декомпозиция

Цель раунда

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

Драйверы: Все ключевые функциональности. NFR-012

Элемент для проработки

Вся система

Выявление альтернатив и анализ компромиссов (trade-off)

Качество (utility tree)

ID

Архитектурный драйвер

Декомпозиция по слоям (layered)

Декомпозиция по бизнес функциям (Vertical Slice)

Декомпозиция по бизнес возможностям (Modular Monolith)

Functional SuitabilityВсеВсе ключевые функциональности🟢🟢🟢

Security



🟢

🟢🟢
Reliability



🔴 Любая ошибка в низком слое (например, базе или логике) может повлиять на все приложение. Высок риск каскадных сбоев.

🟢 Ошибка в одном срезе редко затрагивает другие, т.к. связи между срезами минимальны.🟢 Ошибки внутри домена локализованы. Риск каскадных сбоев ниже, чем в монолите.

Scalability



🔴 Монолитное приложение сложно масштабировать, так как отдельные слои требуют разных подходов к масштабированию.

🟢 Можно независимо оптимизировать и масштабировать отдельные функции, минимизируя лишнюю нагрузку.🟢 Масштабируется по доменам, позволяя гибко управлять ресурсами в зависимости от нагрузки.

Agility

NFR-012

Система должны быть лёгкой в расширении и сопровождении

🔴 Изменения часто касаются нескольких слоев, что увеличивает время разработки и риски регрессий.

🟢 Легко вносить изменения, так как код отдельной функции изолирован и изменения не касаются всей системы.🟠 Внутри домена изменения вносятся легко, но междоменные изменения требуют дополнительной координации.
Complexity

🟢 Низкая (простая, понятная структура, минимум дополнительной сложности).🟢 Низкая (простая, понятная структура, минимум дополнительной сложности).🟠 Средняя (нужна архитектурная дисциплина и управление границами доменов, но проще масштабировать по отдельности).
Resource Utilization

🟠 Возможны сложности с оптимальным использованием ресурсов, так как все слои делят общие ресурсы монолита.🟠 Возможны сложности с оптимальным использованием ресурсов, так как все слои делят общие ресурсы монолита.🟢 Позволяет эффективно использовать ресурсы, настроенные отдельно под каждый домен, но может возникнуть некоторое дублирование ресурсов между доменами.
Constrains

🟢🟢🟢

Принятое решение

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

Выбираем второй вариант.

  • Выбор между вторым и третьим вариантом определяется в первую очередь опытом и зрелостью команды в работе с выбранным подходом.

Раунд 2. Проработка сценариев надежности

Цель раунда

Большая надежда в этом решении закладывается на надёжность. Эта уже не первая версия выписок, старая страдала от проблем с доступностью.

Драйверы: Целью этой итерации будет проработка NFR-004, NFR-005.

Элемент для проработки

Вся система

Выявление альтернатив и анализ компромиссов (trade-off)

Качество (utility tree)

ID

Архитектурный драйвер

Асинхронно отливать данные из источников в БД Выписок используя очередь сообщений

Синхронно ходить в источники и забирать операции.

Functional Suitability

🟢🟢

Security



🟠 Легче обеспечить контроль доступа и аудит, т.к. данные хранятся локально, но требуется защита реплик и управление доступом.🟢 Меньше рисков компрометации, так как данные не хранятся локально; контроль доступа делегируется внешним системам.
Reliability

NFR-004

Система должна продолжать работать в 99.8 % времени даже при выходе из строя любого из компонент системы🟢 Высокая надёжность, поскольку доступность данных не зависит от текущего состояния внешних источников.🔴 Низкая надёжность, так как отказ внешней системы немедленно влияет на работу всей функциональности, зависящей от неё.
NFR-005При недоступности источника операций система должна обеспечивать доступность не менее 80% пользовательского функционала, критичного для основного сценария использования.🟢 Недоступность внешних сервисов ни как не влияет на надежность решения.🔴 Для некоторых источников возможно реализовать частичную деградацию, но не для ключевых.

Scalability



🟢 Легко масштабируется, так как чтение происходит локально, и не ограничивается производительностью внешних систем.🔴 Сложно масштабировать, т.к. производительность зависит напрямую от пропускной способности и задержек внешних систем.

Agility



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

🟠 Средняя сложность: требуется реализация механизма отливки, хранения и актуализации данных, однако сложность централизована и управляемая.🟢 Низкая сложность: прямая реализация вызовов API, простота начальной интеграции, но сложность обработки ошибок и ретраев может возрастать.
Resource Utilization

🟠 Средние затраты: необходимы ресурсы на хранение и периодическую актуализацию данных, но экономия ресурсов на сетевых вызовах в реальном времени.🟠 Может быть высокая нагрузка на ресурсы из-за ожидания сетевых вызовов, обработки ошибок и ретраев.
Constrains

🟢🟢

Принятое решение

Первое решение кажется самым надежным и перспертивным с точки зрения развития продукта.

Первое решение приносит нам и риски которые мы должны обработать:

  • При найме нужно учесть опыт команды в событийном дизайне.
  • При асинхронном обмене сообщений нужно продумать:
    • гарантии доставки
    • обнаружение потерь сообщений
    • план доката в случае потери

Уточнение принятого решения

На этом шаге выделим брокер событий, возможно его конфигурацию, компоненты системы отвечающие за обработку входных данных.

Дизайнерские решение и расположениеОбоснование

Источник первый сгенерировавший событие обязан сгенерировать уникальный идентификатор операции.

Любой из участников проведения платежа: OPS, PG, Online, Prime, XXI

Нам нужен согласованный идентификатор платежа на всех системах. Если хотя бы кто-то не получит этот идентификатор мы не получаем часть операции.

Все источники обязаны присылать сквозной идентификатор операции. 

Все источники: OPS, PG, Online, Prime, XXI

Нам нужен согласованный идентификатор платежа на всех системах. Если хотя бы кто-то не получит этот идентификатор мы не получаем часть операции.

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

  • replication factor 3
  • min.insync.replicas 2 - гарантирует нам, что запись будет производиться только в том случае если в кластере как минимум два брокер синхронизированны друг с другом
  • количество партиций в очереди кратно 4. Это позволит нам ровномерно размазать нагрузку по нашим инстансам приложения

Все источники: OPS, PG, Online, Prime, XXI

Такая конфигурация гарантирует нам попадание и хранения события на стороне брокера

Использовать шаблон outbox для гарантий отправки сообщения от источника в Kafka

Все источники: OPS, PG, Online, Prime, XXI

Шаблон outbox гарантирует нам отправку сообщения в очередь. В противном случае мы рискуем получить несогласованность.

При отправке сообщения в очередь используется парамерт acks=all. Это и min.insync.replicas 2 гарантируют нам долговечную запись на брокере

Все источники: OPS, PG, Online, Prime, XXI

Такая конфигурация гарантирует фиксацию события минимум на двух репликах брокера.

На стороне выписок НЕ используем авто. подтверждение обработки сообщений. Вручную фиксируем сообщение после гарантированной записи в БД

Выписки

Так мы закрываем риск отсутствия записи в локальное хранилище.

Раунд 3. Проработать сценарий обнаружения потери сообщения и проработать план доката

Цель раунда

На этой итерации закроем риски выявленные с предидущей итерации:

  • обнаружение потерь сообщений
  • план доката в случае потери

Элемент для проработки

Вся система

Выявление альтернатив и анализ компромиссов (trade-off)

Качество (utility tree)

ID

Архитектурный драйвер

Периодическая полная сверка данных (Full Reconciliation)

Периодически (например, раз в сутки или час) синхронизировать все данные из внешних источников, выявляя и устраняя пропуски.

Использование событийного журнала (Event Log)

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

Мониторинг и запрос дельты (Delta polling)

Регулярные запросы во внешние системы для получения обновлений (дельты данных за последний период). Сравнение текущего состояния с последним полученным позволяет выявить пропуски.

Functional Suitability

🟢🟢🟢

Security



🟠 Средняя (нужно периодически запрашивать большие объёмы данных)🟢 Высокая (запрашиваются минимальные наборы данных)🟠 Средняя (умеренные объёмы данных)
Reliability

обнаружение потерь сообщений

🟢 Очень высокая (полностью гарантирует восстановление данных)🟢 Высокая (при надёжной реализации журнала событий)🟠 Средняя (зависит от реализации механизма дельт)

Scalability



🔴 Низкая (большие объёмы данных, сложность при росте источников)🟢 Высокая (легко масштабировать по количеству событий)🟠 Средняя (зависит от объёма и частоты изменений)

Agility



🟠 Средняя (проста в реализации, но большие затраты на изменения)🟢 Высокая (легко адаптировать под новые сценарии)🟠 Средняя (необходима поддержка API внешних систем)
Complexity

🟠 Средняя (простая логика, но ресурсоёмкий и требующий эффективной обработки данных)🟠 Средняя (требуется поддержка со стороны внешних систем)🟢 Низкая (простота реализации, вся нужная логика уже реализована на стороне XXI)
Resource Utilization

🔴 Высокая (ресурсы на обработку и передачу больших объёмов данных)🟢 Низкая (минимальные расходы ресурсов на обработку событий)🟠 Средняя (зависит от частоты запросов)
Constrains

🟢🟢🟢

Принятое решение

Подход с Event Log выглядит наилучшим решением. Проблема в том, что мы не можем модифицировать мастер систему и добавить в неё монотонно увеличивающийся идентификатор события.

Выбираем решение 3. Самое лучшее решение из оставшихся.

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

Уточнение принятого решения

Дизайнерские решение и расположениеОбоснование

Со стороны XXI нужна синхронная ручка получения балансов на указанный день. Пусть это будет внутренняя rest ручка принимающая на вход дату и счёт

Кроме как на стороне XXI брать гарантированно согласованные балансы нам негде.

Раунд 4. Выбор БД

Цель раунда

Выбрать персистентное хранилище для сырах операций и сгенерированной выписки.

 Драйверы: NFR-007, NFR-008, CON-001

Элемент для проработки

База данных.

Выявление альтернатив и анализ компромиссов (trade-off)

Качество (utility tree)

ID

Архитектурный драйвер

PostgreSQL (без шардинга)

PostgreSQL (шардированный)

Cassandra

Functional Suitability

🟢🟢🟢

Security



🟢🟢🟢
Reliability

🟠 Средняя, требуются HA и реплики, но при 6 ТБ это выполнимо🟢 Высокая, сбой одного шарда не затрагивает всю систему🟢 Высокая, встроенная отказоустойчивость

Scalability

NFR-007К 2026 г. DAU должно увеличиться до 100к. Система должна предсказуемо масштабироваться.🟠 Средняя, под наши цели ограниченно масштабируется🟢 Высокая, масштабируемость горизонтальная, но управляемая вручную🟢 Высокая, автоматическое горизонтальное масштабирование
NFR-008Система должна хранить данные за весь период (предположительный объем данных на 2026 г будет 6 тб. прирост данных каждый год 1 тб)🟠 Средняя, 6 ТБ ещё можно поддерживать на мощном сервере🟢 Высокая, масштабируемость горизонтальная, но управляемая вручную🟢 Высокая, автоматическое горизонтальное масштабирование

Agility



🟢 Хорошая гибкость. Запросы, схемы и индексы можно гибко менять, миграции умеренно простые.🔴 Низкая гибкость при изменении схемы запросов. Любое изменение может привести к созданию новых таблиц и затратным миграциям.🔴 Низкая гибкость при изменении схемы запросов. Любое изменение может привести к созданию новых таблиц и затратным миграциям.
Complexity

🟢 Низкая, простота настройки и эксплуатации единого сервера🔴 Высокая, сложность шардинга, управления и балансировки данных🟠 Средняя, требует начальной экспертизы в NoSQL и понимания моделей данных
Resource Utilization

🟠 Средняя, один дорогой сервер, но объём ещё управляемый🟠 Средняя, умеренная нагрузка на железо, но больше инфраструктурных затрат на управление шардами🟢 Высокая эффективность при использовании стандартного оборудования
ConstrainsCON-001

Корпоративные стандарты (IT как Lego)

  • postgresql
  • cassandra
  • redis
  • k8s
  • kafka
  • ...
🟢🟢🟢

Принятое решение

Вариант 1 выглядит наиболее удачным. Даёт максимум функциональности и минимум дополнительных затрат.

Уточнение принятого решения

Дизайнерские решение и расположениеОбоснование

Кластер PostgreSQL мы закажем в DBaaS.

Все конфигурации развертывания HA кластера берут на себя ребята из платформы. 

Предполагаемый объем данных на 2026 г = 5тб. Это вполне приемлемая цифра для PostgreSQL.

Для партиционирования используем декларативное секционирование. Такой вид партиционирования наиболее удобен для обслуживания и разработки.

Эскиз решния

Оригинал на wiki