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

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

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

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

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

Вступайте в сообщество DocHubTeam. Здесь мы обсуждаем подход "Архитектура как код" и опыт применения DocHub.

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.

npm install
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

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

• DocHubTeam

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