vmkteam labs
Table of contents

Заметки: Архитектурный репозиторий

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

В данной статье представлена попытка описания минимального архитектурного репозитория (Architecture as Code). Или как жить без выделенного архитектора в команде.

Инструменты

  • git – основной принцип AaC.
  • Writerside – система документации от JetBrains.
  • PlantUML – поддержка диаграмм.
  • C4 – архитектурная нотация.
  • Mermaid – поддержка простых диаграмм.
  • Скрипты и тулпинг
  • Публикация (github/gitlab pages) – доступность в виде опубликованного сайта.

Ядро системы: Writerside

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

Предлагаемая структура

  • Структура команд
  • Отдельная страница продуктовой команды
    • Структура команды
    • Общая архитектура. Например, C4 Диаграмма взаимодействия сервисов
    • Список поддерживаемых сервисов
    • ADR
  • Инфраструктура
    • Карта сети
    • Сервера

Структура может быть сложнее и ветвистее, в зависимости от стадии развития команды.

Важные артефакты архитектуры на старте

  • Схемы взаимодействия сервисов (на уровне C4 контейнеров)
  • Физическая карта сети
  • Описание сложных бизнес-процессов
  • Верхнеуровневое описание сервисов

Тулинг

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

Writerside/ 
cmd/
    tool1/ 
    tool2/ 
Makefile
go.mod

Примеры тулинга

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

  • автоматическое построение карты сети из данных хостеров
  • автоматическое построение сервисов из метрик метаданных appkit
  • автоматическое построение межсервисного взаимодействия через HTTP на основе appkit
  • построение техрадара на основе датасета

Посмотрите заметку про genc4

Почему не база знаний / wiki / confluence?

  • Нет поддержки сложных диаграмм C4 и PlantUML (на достаточном уровне).
  • Нет процессов принятия архитектурных изменений: git, merge request.
  • Нет возможности сохранить рядом тулинг для работы с архитектурой.
  • Нет атомарной истории изменений (у каждой статьи вместо одного коммита).
  • В IDE создавать текст и диаграммы гораздо удобнее, чем в браузере.

Почему стоит начать прямо сейчас?

  • Снизиться порог входа для нового члена команды
  • Появится единственный источник истины (SSOT)
  • Потому что “на потом” уже откладывали :)
  • Даже если у вас 2 сервиса – начните сейчас, потом будет гораздо проще.

С чего начать?

  • Описать оргструктуру и команды
  • Расписать одну команду
  • Попробовать сделать первый ADR
  • Любой новый сервис описывать через MR

Подводные камни?

  • Нет времени – никогда и не появится
  • Схема потеряет актуальность – измените процессы, чтобы внесение изменений в инфраструктуру было через Merge Requests.
  • А зачем? – чтобы постоянно не рассказывать, как все устроено.

Пример структуры проекта во Writerside

Допустим, у нас появилась компания Sandbox, в которой есть три команды. Ниже предоставлен пример предлагаемой структуры:

  • Sandbox – описание структуры компании (mindmap со ссылками)
  • Команда админов – описание команды внутри (mindmap)
    • Карта сети
  • Команда платформы – описание команды внутри (mindmap), важные ссылки
    • Сервисы – список сервисов команды с верхнеуровневым описанием
    • Архитектура – архитектура сервисов
    • Потоки данных
    • ADR
  • Команда фронтенда
  • Команда мобильных приложений
  • Техрадар

Интересно почитать