DocHub

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

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

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

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

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

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

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

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

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

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

mermaidCopy
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> Принципы развития продукта

Термины

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

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

Принципы

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

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

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

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

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

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

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

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

Статьи

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

Воркшопы

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

Доклады

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

Сообщество

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

Динамика роста звезд на GitHub

Каждая звезда DocHub, это камень в фундамент подхода "Архитектура как код"!

Stargazers over time

Лицензия

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

Комьюнити-взнос за пользование продуктом

Проблема

Цель создания DocHub — инструментализировать подход управления архитектурой кодом для его развития. DocHub разработан
как FOSS продукт, который должен развиваться сообществом.

К сожалению, не все участники сообщества могут внести значимый вклад в кодовую базу DocHub. Однако сообщество уже велико
и требует поддержки и развития. Примерно 97% пользователей зависят от результатов работы лишь 3% участников.

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

Решения проблемы - Прозрачность использования FOSS DocHub

Одной из ключевых проблем любого продукта является доверие к нему. В ИТ это доверие заслужить сложно.
Обычно метрикой надежности и перспективности продукта являются статусность его клиентов. DocHub не гнался за "лейблами" на первом этапе.
Он ставил задачу создать реальную ценность для экспертов-инноваторов без "маркетингового давления" на них.

Сегодня наше сообщество достаточно велико, и мы можем с уверенностью говорить о подтверждении ценности инструмента и подхода. Скромность более неуместна.
Более того, она мешает его новым членам оценить масштаб и достижения нашего комьюнити.

Каждый пользователь DocHub может существенно помочь его развитию, опубликовав информацию о том, в какой компании и для каких задач он используется.
Эта информация объединит наше сообщество, привлечет новых участников и расширит базу контрибьюторов.
Направляйте информацию на ящик r.piontik@mail.ru. Этим вы, безусловно, сделаете очень ценный вклад в развитие подхода "Архитектура как код".

Начиная с релиза v3.13.1, в дополнение к лицензии Apache 2.0 вводится комьюнити-взнос в развитие DocHub. Он заключается в обязательстве пользователя
не скрывать использование DocHub. Это обязательство также касается производных продуктов на основе кодовой базы DocHub.

Информация о факте использования компанией DocHub может без ее явного согласия публиковаться в репозиториях продукта, в информационной
пространстве комьюнити, в статьях, на конференциях и т.д. при наличии очевидных признаков такого использования (публичные заявления, форки кодовой базы,
обсуждения в экспертных сообществах и т.п.). При этом, без согласия публикуется только сам факт использования.

    Например, если архитектор компании ООО "Креативные Технологии" опубликовал 
    статью на Хабре "Развертывание сервисов с использованием DocHub", в 
    репозитории DocHub может появиться информация об новом клиенте DocHub -
    ООО "Креативные Технологии". 
    
    Никакой детальной информации об опыте использования без выраженного
    желания компании не появится.

Если по какой-либо причине считаете, что использование вами DocHub не может быть публичной информацией — прекратите его использование.
Это противоречит цели создания DocHub как FOSS инструмента для развития инноваций в ИТ индустрии.

По запросу организации на ящик r.piontik@mail.ru информация об использовании ей DocHub будет удалена.
Одновременно с этим, компания берет на себя обязательства прекратить использовать DocHub в любых целях.