DocHub - инструмент описания архитектуры через код (Architecture as a code). Код архитектуры - ансамбль файлов на языках, решающих задачу описания. Поддерживаются:
- Markdown - язык разметки, созданный с целью обозначения форматирования в тексте;
- PlantUML - позволяет создавать диаграммы, используя простой и интуитивно понятный язык;
- BPMN - Поддерживается BPMN нотация описания бизнес-процессов с использованием bpmnjs;
- Mermaid - позволяет создавать диаграммы с использованием кода;
- Swagger - язык описания HTTP API контрактов;
- AsyncAPI - язык описания событийных контрактов;
- SmartAnts - продвинутый инструмент презентации архитектуры.
- Манифесты - структурированные файлы в формате YAML/JSON для описания архитектурных объектов;
Решаемые проблемы:
- Управление версиями;
- Децентрализованное управление архитектурой в Agile-ориентированных компаниях;
- Управление архитектурой экосистемы;
- Создание архитектурных фасадов (портал документации);
- Анализ архитектуры;
- Контроль консистентности;
- Расширяемая метамодель.
Рекомендую начать с прочтения статьи Архитектура рядом с кодом. Познакомиться с работой инструмента и его подробной документацией можно на сайте https://dochub.info. Примеры использования можно найти в специальном репозитории, который развивает сообщество - Примеры DocHub. Также полезно посмотреть воркшоп по старту использования.
Свежие версии плагинов лежат:
- Для IDEA в проекте и в маркете JetBrains;
- Для VSCode в проекте;
Вступайте в сообщество DocHubTeam. Здесь мы обсуждаем подход "Архитектура как код" и опыт применения DocHub.
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
Public metamodel repository :done, 2023-10-01, 200d
section Q2 2024
MVP mutators :done, 2024-01-01, 200d
Process Disigner tool :done, 2024-06-01, 120d
Architectire Commutiny tool :2024-06-01, 200d
section Q3 2024
AaaC Community Architect Framework (CEAF) :active, 2024-06-17, 200d
WEB DocHub IDE :active, 2024-09-14, 120d
Digital Modeler :active, 2024-09-14, 120d
section Q4 2024
Time Machine :active, 2024-11-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"
DocHub позволяет развивать кодовую базу архитектуры аналогично кодовой базе приложений. В качестве системы управления версиями используется GitLab.
DocHub умеет консолидировать описание архитектуры из различных источников. Например, из разных репозиториев. Это позволяет командам действовать независимо в сотрудничестве друг с другом.
DocHub создан с учетом современных проблем в управлении архитектурой экосистемы. В ней продукты взаимосвязаны, но развиваются автономно. DocHub позволяет создать единое информационное пространство для экосистемы. Стимулирует положительную синергию продуктов.
DocHub хорошо решает задачу публичного портала документации.
Один из ключевых принципов инструмента - Архитектура как данные. Это означает, что вы можете получать ценные для себя сведения из архитектуры, используя язык запросов JSONata.
Протейшим примером этого подхода являются табличные документы.
DocHub умеет находить проблемы в описании архитектуры и контролировать определенные вами правила.
Метамодель DocHub может быть расширена по вашему желанию. Есть возможность как модифицировать уже существующие сущности, так и создавать собственные.
Познакомиться с идеей ближе можно в статье Код архитектуры — это жидкость.
Пример можно посмотреть здесь
Определите необходимые переменные окружения. Используйте файл примера example.env для этого. Переименуйте его для продакшен окружения в ".env" для локального развертывания в ".env".
Если вы ничего не будете трогать, развертывание произойдет с дефолтными настройками. В этом случае DocHub будет содержать собственную документацию.
Выполните команды:
docker-compose up --build
DocHub станет доступен по адресу http://localhost:8080/main
Проект является VueJS SPA приложением. В качестве backend пользуется GitLab.
Для развёртывания потребуется стандартная сборка VueJS приложения средствами npm, версией не ниже 8.1.х (версия node 20.х.х).
npm сi
npm run build
В результате будут сгенерированы статические файлы в папке /dist. Их необходимо опубликовать используя web-сервер. Например, nginx.
Подробнее о вариантах развертывания можно узнать тут.
В файле "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 [email protected]: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
Наш клиент - организация или лицо ее представляющее, которые действительно используют продукт или действительно собираются его использовать.
Наше комьюнити - сообщество полностью или частично разделяющее идею продукта.
-
Команда продукта работает по принципам Agile. Причина этому не дань "модным тенденциям", а искренняя вера в то, что только мотивированные члены команды могут достичь действительно значимых результатов.
-
Мы отдаем предпочтение работающему продукту, а не исчерпывающей документации. Документация очень важна, но ровно в необходимом объеме.
-
Развитие продукта идет в тесной связи с клиентом. Наша задача не соблюсти контракт с ним, а сделать его счастливым. Решить не только его сегодняшние проблемы, но и перспективные.
-
Мы хорошо понимаем, что наш продукт развивается в динамичном мире. Наша команда постоянно переоценивает свои цели и адекватность средств их достижения.
-
Мы в крайней степени дорожим вкладом сообщества в продукт. Такой вклад обязательно будет поддержан. Контрибьютор получит всестороннюю помощь успешной интеграции его вклада в продукт. Его вклад будет публично заявлен. Одновременно с этим, команда продукта несет ответственность за стратегическое развитие продукта перед клиентом. За его образ и целостность во всех аспектах. Эта ответственность дает ей право финального решения об образе продукта, его функциональной наполненности и порядке выхода фич.
По этой причине, наши опубликованные планы, это планы в который мы искренне верим сегодня. Но они является лишь инструментом координации команды и комьюнити продукта. Они могут пересматриваться в любой момент, когда станет очевидным, что они устарели.
Следите за новостями в группе комьюнити и нашем канале.
- Архитектура как кот VS Архитектура как кол;
- Архитектура как данные;
- Архитектура рядом с кодом;
- Код архитектуры — это жидкость;
- Кто последний на индустриальный стандарт? Мне только спросить…;
- Старт использования
- Ванильная метамодель DocHub
- Реверс-архитектура
- Опыт ГК Самолет
- Кастомизация метамодели
- Доклад "Архитектура как код" на FlowConf 2023;
- Доклад "Архитектура как код" на ArchDays 2022;
- Круглый стол 2021.
Каждая звезда DocHub, это камень в фундамент подхода "Архитектура как код"!
DocHub распространяется под лицензией Apache License 2.0 Open source license.
Цель создания DocHub — инструментализировать подход управления архитектурой кодом для его развития. DocHub разработан как FOSS продукт, который должен развиваться сообществом.
К сожалению, не все участники сообщества могут внести значимый вклад в кодовую базу DocHub. Однако сообщество уже велико и требует поддержки и развития. Примерно 97% пользователей зависят от результатов работы лишь 3% участников.
Это, безусловно, тормозит инновации продукта, так как ресурсы расходуются на поддержку, а не на новшества. Эту ситуацию необходимо изменить, чтобы сохранить импульс инноваций.
Одной из ключевых проблем любого продукта является доверие к нему. В ИТ это доверие заслужить сложно. Обычно метрикой надежности и перспективности продукта являются статусность его клиентов. DocHub не гнался за "лейблами" на первом этапе. Он ставил задачу создать реальную ценность для экспертов-инноваторов без "маркетингового давления" на них.
Сегодня наше сообщество достаточно велико, и мы можем с уверенностью говорить о подтверждении ценности инструмента и подхода. Скромность более неуместна. Более того, она мешает его новым членам оценить масштаб и достижения нашего комьюнити.
Каждый пользователь DocHub может существенно помочь его развитию, опубликовав информацию о том, в какой компании и для каких задач он используется. Эта информация объединит наше сообщество, привлечет новых участников и расширит базу контрибьюторов. Направляйте информацию на ящик [email protected]. Этим вы, безусловно, сделаете очень ценный вклад в развитие подхода "Архитектура как код".
Начиная с релиза v3.13.1, в дополнение к лицензии Apache 2.0 вводится комьюнити-взнос в развитие DocHub. Он заключается в обязательстве пользователя не скрывать использование DocHub. Это обязательство также касается производных продуктов на основе кодовой базы DocHub.
Информация о факте использования компанией DocHub может без ее явного согласия публиковаться в репозиториях продукта, в информационной пространстве комьюнити, в статьях, на конференциях и т.д. при наличии очевидных признаков такого использования (публичные заявления, форки кодовой базы, обсуждения в экспертных сообществах и т.п.). При этом, без согласия публикуется только сам факт использования.
Например, если архитектор компании ООО "Креативные Технологии" опубликовал
статью на Хабре "Развертывание сервисов с использованием DocHub", в
репозитории DocHub может появиться информация об новом клиенте DocHub -
ООО "Креативные Технологии".
Никакой детальной информации об опыте использования без выраженного
желания компании не появится.
Если по какой-либо причине считаете, что использование вами DocHub не может быть публичной информацией — прекратите его использование. Это противоречит цели создания DocHub как FOSS инструмента для развития инноваций в ИТ индустрии.
По запросу организации на ящик [email protected] информация об использовании ей DocHub будет удалена. Одновременно с этим, компания берет на себя обязательства прекратить использовать DocHub в любых целях.
