Seaf Archtool

Добро пожаловать в Seaf Archtool — решение для управления цифровой архитектурой.

Применение

Seaf Archtool — продукт, предназначенный для выполнения следующих задач:

• Cоздание технологии для описания цифровой архитектуры. Мы считаем, что достичь ее можно описывая архитектуру кодом.
• Поставка метамодели и методологии, которые должны адаптироваться и развиваться под потребности конкретного предприятия, выявленные домены и слои архитектуры
• Cистематизация и контроль архитектуры дочерних зависимых обществ (ДЗО) группы "Сбер". Наш продукт нацелен на создание единой экосистемы, где архитектура может быть описана, оценена и адаптирована в соответствии со стратегическими целями группы.
• Экспертиза архитектурных решений всех ДЗО, обеспечивая тем самым соответствие этих решений установленным стандартам и стратегическим направлениям банка. Мы собираем и анализируем текущие архитектурные решения от ДЗО и проводим экспертизу их будущих планов на горизонте планирования, чтобы удостовериться, что они соответствуют общей стратегии группы.

Наш подход включает:

1. Исследование кейсов, возникающих перед бизнесом и архитекторами, формирование выверенных примеров описания и управления архитектурой (разработка и экспертиза артефактов), выявление лучших практик, обучение, референс, сопровождение и консалтинг.
2. Архитектурную работу c применением SEAF в организациях Группы Сбер, Банке или внешней организации-партнере, приносящую ценность бизнесу, поддерживаемую Сообществом и демонстрирующую во внешнюю среду успешную историю развития участника Сообщества.
3. Разработку и внедрение архитектурных стандартов — мы создаем и тиражируем стандарты среди ДЗО, что значительно повышает зрелость информационных технологий.
4. Проведение контроля архитектур на соответствие установленным стандартам с целью обеспечить оптимальность принимаемых решений.
5. Развитие сообщества архитекторов, что позволяет обмениваться опытом и иными ресурсами между ДЗО.

Инструмент

SEAF Archtool - инструмент управления архитектурой как кодом. Создан на базе https://github.com/DocHubTeam/DocHub. Документация: https://dochub.info.

Векторы Seaf Archtool, отличные от Dochub

• Поддержка цифровых архитектурных шаблонов и фреймворков, разрабатываемых в Сбере (SEAF, КА ДЗО, Ассессменты и др.)
• Поддержка Enterprise режимов использования инструмента SEAF.Archtool (бекэнд режим, в k8s, ролевая модель и т.п.)
• Обеспечение уровня безопасности продукта (обязательные проверки на уязвимости инструментами Сбера перед выпуском релиза)
• Поддержка практик развития архитектурной функции в Группе Сбера

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

• PlantUML - позволяет создавать диаграммы, используя простой и интуитивно понятный язык;
• Mermaid - позволяет создавать диаграммы с использованием кода;
• Markdown - язык разметки, созданный с целью обозначения форматирования в тексте;
• Swagger - язык описания HTTP API контрактов;
• AsyncAPI - язык описания событийных контрактов;
• SmartAnts - продвинутый инструмент презентации архитектуры.
• Манифесты - структурированные файлы в формате YAML/JSON для описания архитектурных объектов;

Поддерживаемые языки:

• HTML
• Dockerfile
• CSS
• TypeScript
• JavaScript
• Shell
• Vue

Общая архитектура SEAF Archtool

Решаемые проблемы:

• Управление версиями;
• Децентрализованное управление архитектурой в Agile-ориентированных компаниях;
• Управление архитектурой экосистемы;
• Создание архитектурных фасадов (портал документации);
• Анализ архитектуры;
• Контроль консистентности;
• Расширяемая метамодель.

Быстрый старт

Рекомендуется начать с прочтения статьи Архитектура рядом с кодом. Познакомиться с работой инструмента и его подробной документацией можно на сайте https://dochub.info. Примеры использования можно найти в специальном репозитории, который развивает сообщество - Примеры DocHub. Также полезно посмотреть воркшоп по старту использования.

Свежие версии палгинов лежат:

1. Для IDEA в проекте
2. Для VSCode в маркете VSCode

В качестве хранилища для репозиториев Seaf Archtool использует GitVerse - https://gitverse.ru/seafteam/seaf-archtool-core.

План развития

gantt
    title RoadMap развития
    dateFormat  YYYY-MM
    section Q1 2023
        Plugins                      :done, plugins, 2023-01-01, 40d
        SmartAnts                    :done, smartants, 2023-02-01, 30d
        Export to Excalidraw         :done, exportexc, 2023-02-20, 11d
        Backend                      :done, 2023-02-27, 30d
    section Q2 2023
        PoC revers architecture tool    :done, 2023-04-01, 180d
        PoC event storming tool         :done, 2023-04-01, 90d
    section Q3 2023
        Iaas reverce tool           :done, 2023-07-01, 92d
        MVP Framework SEAF          :done, 2023-07-01, 92d
        POC mutators                :done, 2023-07-01, 150d
    section Q4 2023
        Framework SEAF              :done, 2023-10-01, 92d
        Time Machine                :active, 2023-11-01, 250d
        Public metamodel repository :active, 2023-10-01, 200d
    section Q2 2024
        MVP mutators                :active, 2024-01-01, 200d
        Process Disigner tool       :2024-06-01, 90d
        Architectire Commutiny tool :2024-06-01, 90d

click plugins href "https://dochub.info/docs/dochub.plugins.intro"
click smartants href "https://dochub.info/docs/dochub.smartants"
click exportexc href "https://dochub.info/docs/dochub.smartants#%D0%BF%D1%80%D0%BE%D1%81%D1%82%D0%B5%D0%B9%D1%88%D0%B5%D0%B5-%D0%BF%D1%80%D0%B5%D0%B4%D1%81%D1%82%D0%B0%D0%B2%D0%BB%D0%B5%D0%BD%D0%B8%D0%B5"

Принципы развития продукта

Управление версиями архитектуры

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

Децентрализованное управление архитектурой в Agile-ориентированных компаниях

Seaf Archtool умеет консолидировать описание архитектуры из различных источников. Например, из разных репозиториев. Это позволяет командам действовать независимо в сотрудничестве друг с другом.

Управление архитектурой экосистем

Seaf Archtool позволяет создать единое информационное пространство для экосистемы. Стимулирует положительную синергию продуктов.

Архитектурные фасады

Seaf Archtool хорошо решает задачу публичного портала документации.

Анализ архитектуры

Один из ключевых принципов инструмента - Архитектура как данные. Это означает, что вы можете получать ценные для себя сведения из архитектуры, используя язык запросов JSONata.

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

Контроль консистентности архитектуры

Seaf Archtool умеет находить проблемы в описании архитектуры и контролировать определенные вами правила.

Расширяемая метамодель

Метамодель Seaf Archtool может быть расширена по вашему желанию. Есть возможность как модифицировать уже существующие сущности, так и создавать собственные. Пример можно посмотреть здесь

Развертывание

Конфигурирование

Определите необходимые переменные окружения. Используйте файл примера example.env для этого. Переименуйте его для продакшен окружения в ".env" для локального развертывания в ".env".

Если вы ничего не будете трогать, развертывание произойдет с дефолтными настройками. В этом случае Seaf Archtool будет содержать собственную документацию.

Локальное развертывание

Выполните команды:

docker-compose up --build

Seaf Archtool станет доступен по адресу http://localhost:8080/main

Сборка из исходников для продакшен

Проект является VueJS SPA приложением. В качестве backend пользуется GitLab.

Для развёртывания потребуется стандартная сборка VueJS приложения средствами npm, версией не ниже 8.1.х (версия node 20.х.х).

npm сi
npm run build

В результате будут сгенерированы статические файлы в папке /dist. Их необходимо опубликовать используя web-сервер. Например, nginx.

Подробнее о вариантах развертывания можно узнать тут.

Интеграция с GitLab

Для локального развертывания

В файле "example" укажите адрес GitLab в соответствующей переменной:

VUE_APP_DOCHUB_GITLAB_URL=https://foo.space

В GitLab под своей учетной записью выпустите персональный токен Profile->Preferences->Access Tokens

Полученный токен укажите в файле ".env" в переменной:

# Персональный токен gitlab. Используется для локальной разработки
VUE_APP_DOCHUB_PERSONAL_TOKEN=9H...FR

Перезапустите контейнеры:

docker-compose down
docker-compose up --build

Локальное развитие архитектуры

Создайте папку "/public/workspace". Папка входит в .gitignore. Это нормально. Папка предназначена для локального развертывания архитектурных репозиториев. Клонируйте необходимый архитектурный репозиторий.

cd /public/workspace
git clone git@git.foo.space:repo.git

Определите в ".env" переменную корневого манифеста:

VUE_APP_DOCHUB_ROOT_MANIFEST=workspace/repo/root.yaml

Перезапустите контейнеры:

docker-compose down
docker-compose up --build

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

Для продакшена

В файле ".env" укажите адрес GitLab в соответствующей переменной:

VUE_APP_DOCHUB_GITLAB_URL=https://foo.space

Настройте OAuth2 service provider в GitLab. Документацию по настройке можно найти на официальном сайте.

Полученные токены укажите в файле .env в переменных:

# Идентификатор приложения зарегистрированного в GitLab
VUE_APP_DOCHUB_APP_ID=5f3...f0

# Секрет приложения
VUE_APP_DOCHUB_CLIENT_SECRET=1e4...384

Соберите приложение:

npm run build

Принципы развития продукта

Термины

Наш клиент - организация или лицо ее представляющее, которые действительно используют продукт или действительно собираются его использовать.

Наше комьюнити - сообщество полностью или частично разделяющее идею продукта.

Принципы

1. Команда продукта работает по принципам Agile. Причина этому не дань "модным тенденциям", а искренняя вера в то, что только мотивированные члены команды могут достичь действительно значимых результатов.

2. Мы отдаем предпочтение работающему продукту, а не исчерпывающей документации. Документация очень важна, но ровно в необходимом объеме.

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

4. Мы хорошо понимаем, что наш продукт развивается в динамичном мире. Наша команда постоянно переоценивает свои цели и адекватность средств их достижения.

5. Мы в крайней степени дорожим вкладом сообщества в продукт. Такой вклад обязательно будет поддержан. Контрибьютор получит всестороннюю помощь успешной интеграции его вклада в продукт. Его вклад будет публично заявлен. Одновременно с этим, команда продукта несет ответственность за стратегическое развитие продукта перед клиентом. За его образ и целостность во всех аспектах. Эта ответственность дает ей право финального решения об образе продукта, его функциональной наполненности и порядке выхода фич.

Отказ от обязательств в строгом планировании

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

Следите за новостями в группе комьюнити и нашем канале.

Статьи

• Архитектура как кот VS Архитектура как кол;
• Архитектура как данные;
• Архитектура рядом с кодом;
• Код архитектуры — это жидкость;
• Кто последний на индустриальный стандарт? Мне только спросить…;

Воркшопы

• Старт использования
• Ванильная метамодель DocHub
• Реверс-архитектура
• Опыт ГК Самолет
• Кастомизация метамодели

Доклады

• Доклад "Архитектура как код" на FlowConf 2023;
• Доклад "Архитектура как код" на ArchDays 2022;
• Круглый стол 2021.

Сообщество

• Группа DocHubTeam
• Канал "Архитектура как код"

Лицензия

DocHub распространяется под лицензией Apache License 2.0 Open source license.