DocHub
Управление архитектурой как кодом
Install / Use
/learn @DocHubTeam/DocHubREADME
DocHub
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
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 (BPMN) :done, 2024-06-01, 120d
Architectire Commutiny tool :2024-06-01, 300d
section Q3 2024
AaaC Community Architect Framework (CEAF) :active, 2024-06-17, 550d
WEB DocHub IDE :active, 2024-09-14, 150d
SaaS version :active, 2024-11-01, 130d
section Q4 2024
Digital Modeler :active, 2024-12-14, 365d
Time Machine :active, 2024-11-01, 250d
section Q1 2025
User form editor :active, 2025-01-08, 60d
ArchiMate modeler :active, 2025-03-15, 60d
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"
<a name="versions"></a> Управление версиями архитектуры
DocHub позволяет развивать кодовую базу архитектуры аналогично кодовой базе приложений. В качестве системы управления версиями используется GitLab.
<a name="decentralized"></a> Децентрализованное управление архитектурой в Agile-ориентированных компаниях
DocHub умеет консолидировать описание архитектуры из различных источников. Например, из разных репозиториев. Это позволяет командам действовать независимо в сотрудничестве друг с другом.
<a name="ecosystem"></a> Управление архитектурой экосистем
DocHub создан с учетом современных проблем в управлении архитектурой экосистемы. В ней продукты взаимосвязаны, но развиваются автономно. DocHub позволяет создать единое информационное пространство для экосистемы. Стимулирует положительную синергию продуктов.
<a name="facade"></a> Архитектурные фасады
DocHub хорошо решает задачу публичного портала документации.
<a name="analysis"></a> Анализ архитектуры
Один из ключевых принципов инструмента - Архитектура как данные. Это означает, что вы можете получать ценные для себя сведения из архитектуры, используя язык запросов JSONata.
Протейшим примером этого подхода являются табличные документы.
<a name="problems"></a> Контроль консистентности архитектуры
DocHub умеет находить проблемы в описании архитектуры и контролировать определенные вами правила.
<a name="extmetamodel"></a> Расширяемая метамодель
Метамодель 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.
Подробнее о вариантах развертывания можно узнать тут.
Интеграция с 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
<a name="manifest"></a> Принципы развития продукта
Термины
Наш клиент - организация или лицо ее представляющее, которые действительно используют продукт или действительно собираются его использовать.
Наше комьюнити - сообщество полностью или частично разделяющее идею продукта.
Принципы
-
Команда продукта работает по принципам Agile. Причина этому не дань "модным тенденциям", а искренняя вера в то, что только мотивированные члены команды могут достичь действительно значимых результатов.
-
Мы отдаем предпочтение работающему продукту, а н
