SEAF.ArchTool

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

Быстрый старт 🚀 • Cписок репозиториев 📋

Применение

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

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

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

1. Исследование кейсов, возникающих перед бизнесами и IT, формирование выверенных примеров описания и управления архитектурой (разработка и экспертиза артефактов), выявление лучших практик, обучение, референс, сопровождение и консалтинг.
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 - язык описания событийных контрактов;

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

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

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

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

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

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

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

Свежие версии плагинов для IDEA и VSCode лежат в проекте

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

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

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

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

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

Список репозиториев

Статьи

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

Воркшопы

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

Доклады

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

Сообщество

• Группа комьюнити SEAF.ArchTool
• Группа DocHubTeam
• Канал "Архитектура как код"

Лицензия

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