исследуй
проектируй
Улучшай

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

Качественно не значит много

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

Нужно упрощать и визуализировать

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

C4 нотация - это одна из попыток сделать проще и понятнее для всех.
Здесь и далее будем рассматривать C4 как:

• контекст;
• контейнер;
• компонент;
• код
  Собственно, С4: Context, Container, Component & Code - 4 С.

  Что такое Контекст?

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

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

Что делаем:

1. Определяем пользователя (его может и не быть, но есть сервис клиент и т.д.)
2. Определяем внешние системы, сервисы и их функции
3. Определяем отношения, в которые вступает создаваемый нами сервис

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

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

Контейнер

Диаграмма контейнеров - показывает из чего состоит то, что мы с вами проектируем. Благодаря этой диаграмме должны стать очевидными стек, состав, принципы коммуникации и хранения данных.

Что делаем:

1. Определяем достаточность данных, которыми мы располагаем. Если чего-то нет - это причина создать аналитический долг и апнуть диаграмму, когда пробелы будут закрыты, но не отказаться от её создания. Интересность штуки в том, что пока мы не начнем прорисовывать начинку, мы не начнем задавать себе правильные вопросы.
2. Определяем список сущностей, которые должны попасть на диаграмму
3. Каждый элемент на схеме должен выполнять какую-то понятную работу: хранить конкретные данные, предоставлять доступ, маршрутизировать и т.д.
4. Связать компоненты контейнера, объявить тип связи
5. При необходимости создать легенду

Что мы понимаем из диаграммы выше.

1. Оказывается, у нас два шлюза: старый и новый, при этом обеспечена маршрутизация к сервису лояльности. Сам сервис - это не только backend с логикой и API, но и некий фронт. Мы понимаем, что хранилка - это PostgreSQL, что наворочен слой API для обращения к базе, и, кроме того, осуществляется логирование запросов, однако, в моменте хранилка логов не детализирована.

Компонент

В нашем с вами импровизированном примере мы проектируем Цифровую платформу лояльности (Digital Loyalty Platform), попробуем погрузиться до уровня компонент, и показать более детально, что именно представляет собой Digital Loyalty Platform.

Что делаем:

1. Декомпозируем сервис, который мы проектируем до уровня самостоятельных компонент
2. Определяем, какие компоненты важно отразить в диаграмме в контексте задачи. Более чем часто - всегда бывает так, что сервис на уровне компонент распадается на существенное количество объектов, каждый из которых решает конкретную задачу. Для нас важно показать не вообще всё, но те части контейнера, которые аффектят или прямо участвуют в проектируемой фиче.
3. Устанавливаем связи между компонентами, объявляем форматы и протоколы.

Что нам становится понятным из диаграммы выше:

1. Цифровая платформа лояльности - это не монолит.
2. Отдельные модули сервиса решают задачи безопасности, авторизации, определения геолокации устройства пользователя.
3. Мы видим, что функции безопасности и функции определения локации устройства выведены за предела фасада сервиса.
4. Видим, что чувствительные данные хранятся в отдельных контейнерах, за пределами Цифровой платформы лояльности.

Код

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

Что делаем:

1. Определяем границы для диаграммы классов. Что именно должна сделать понятным диаграмма. Часто до уровня классов при проектировании не углубляются, и эта часть проектной документации поставляется вместе с постановкой задачи для базовода, или при проектировании API
2. Объявляем объекты, атрибуты
3. Устанавливаем связи

Что мы понимаем из приведенной диаграммы классов:

1. Внедряемый в профиль customer refcode хранится в отдельной таблице.
2. Customer может иметь только один refcode, или не иметь его вовсе.
3. Если будет удалена таблица с рефкодами - это не окажет летального аффекта на профиль пользователя.

Резюме

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

Про полезные ссылки

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

Какие инструменты удобно использовать:
Если не любим кодить, но жутко нравится рисовать - то, Draw.io, в большей части развернутых Confluence этот модуль подключен.
Если работаем не в Confluence, или модуль по каким-то соображениям не включен в коробку, можно установить на десктоп.

Рекомендую безотказный PlantUML - то есть код.
Работать можно как в Visual Studio Code, так и в NotePad++ через плагин.

PlantUML_C4

Другие решения: