DocHub

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 379 Open GitHub ↗

Управление архитектурой как кодом

Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# DocHub

![Инкрементальное развитие архитектуры](https://raw.githubusercontent.com/DocHubTeam/DocHub/master/pics/interface.png)

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

* [Markdown](https://ru.wikipedia.org/wiki/Markdown) - язык разметки, созданный с целью обозначения форматирования в тексте;
* [PlantUML](https://plantuml.com/) - позволяет создавать диаграммы, используя простой и интуитивно понятный язык;
* [BPMN](https://dochub.info/entities/docs/blank?dh-doc-id=dochub.bpmn) - Поддерживается BPMN нотация описания бизнес-процессов с использованием [bpmnjs](https://bpmn.io/);
* [Mermaid](https://mermaid-js.github.io/mermaid/#/) - позволяет создавать диаграммы с использованием кода;
* [Swagger](https://swagger.io/) - язык описания HTTP API контрактов;
* [AsyncAPI](https://www.asyncapi.com/) - язык описания событийных контрактов;
* [SmartAnts](https://dochub.info/docs/dochub.smartants) - продвинутый инструмент презентации архитектуры.
* [Манифесты](https://dochub.info/docs/dochub_contexts) - структурированные файлы в формате YAML/JSON для описания архитектурных объектов;

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

* [Управление версиями](#versions);
* [Децентрализованное управление архитектурой в Agile-ориентированных компаниях](#decentralized);
* [Управление архитектурой экосистемы](#ecosystem);
* [Создание архитектурных фасадов (портал документации)](#facade);
* [Анализ архитектуры](#analysis);
* [Контроль консистентности](#problems);
* [Расширяемая метамодель](#extmetamodel).

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

Рекомендую начать с прочтения статьи [Архитектура рядом с кодом](https://habr.com/ru/post/659595/).
Познакомиться с работой инструмента и его подробной документацией можно на сайте 
[https://dochub.info](https://dochub.info/). 
Примеры использования можно найти в специальном репозитории, который развивает 
сообщество - [Примеры DocHub](https://github.com/rpiontik/DocHubExamples). Также полезно
посмотреть [воркшоп](https://youtu.be/A7U4KiE5uhQ) по старту использования.

Свежие версии плагинов лежат:
1. Для IDEA в [проекте](./distrib/idea/) и в [маркете JetBrains](https://plugins.jetbrains.com/plugin/18518-dochub-architecture-as-code);
2. Для VSCode в [проекте](./distrib/vscode/);

Вступайте в сообщество [DocHubTeam](https://t.me/archascode). Здесь мы
обсуждаем подход "Архитектура как код" и опыт применения DocHub.

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

```mermaid
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"
```

[Принципы развития продукта](#manifest)

## <a name="versions"></a> Управление версиями архитектуры

DocHub позволяет развивать кодовую базу архитектуры аналогично кодовой базе приложений. В качестве системы управления
версиями используется GitLab.

![Инкрементальное развитие архитектуры](https://raw.githubusercontent.com/DocHubTeam/DocHub/master/pics/inc_arch.png)

## <a name="decentralized"></a> Децентрализованное управление архитектурой в Agile-ориентированных компаниях

DocHub умеет консолидировать описание архитектуры из различных источников. Например, из разных репозиториев. Это
позволяет командам действовать независимо в сотрудничестве друг с другом.

![Децентрадлизованное управление архитектурой](https://raw.githubusercontent.com/DocHubTeam/DocHub/master/pics/decentralized.png)

## <a name="ecosystem"></a> Управление архитектурой экосистем

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

![Управление эксоситемой](https://raw.githubusercontent.com/DocHubTeam/DocHub/master/pics/ecosystem.png)

## <a name="facade"></a> Архитектурные фасады

DocHub хорошо решает задачу публичного портала документации.

![Архитектурные фасады](https://raw.githubusercontent.com/DocHubTeam/DocHub/master/pics/facade.png)

[Пример портала](https://dochub.info/).

## <a name="analysis"></a> Анализ архитектуры

Один из ключевых принципов инструмента - Архитектура как данные. Это означает, что вы можете
получать ценные для себя сведения из архитектуры, используя язык запросов [JSONata](https://jsonata.org/).

Протейшим примером этого подхода являются [табличные документы](https://dochub.info/docs/dochub.tables).

## <a name="problems"></a> Контроль консистентности архитектуры

DocHub умеет находить проблемы в описании архитектуры и контролировать определенные вами правила.

![Валидатор](https://raw.githubusercontent.com/DocHubTeam/DocHub/master/pics/validators.png)

## <a name="extmetamodel"></a> Расширяемая метамодель

Метамодель DocHub может быть расширена по вашему желанию. Есть возможность как модифицировать
уже существующие сущности, так и создавать собственные.

Познакомиться с идеей ближе можно в статье [Код архитектуры — это жидкость](https://habr.com/ru/post/701050/).

Пример можно посмотреть [здесь](https://github.com/rpiontik/DocHubExamples/tree/main/src/C4Model)

## Развертывание

### Конфигурирование

Определите необходимые переменные окружения. Используйте файл примера [example.env](example.env) для этого. Переименуйте его для
продакшен окружения в ".env" для локального развертывания в ".env".

Если вы ничего не будете трогать, развертывание произойдет с дефолтными настройками. В этом случае DocHub будет
содержать собственную документацию.

### Локальное развертывание

Выполните команды:
```
docker-compose up --build
```
DocHub станет доступен по адресу [http://localhost:8080/main](http://localhost:8080/main)

### Сборка из исходников для продакшен

Проект является VueJS SPA приложением. В качестве backend пользуется GitLab.

Для развёртывания потребуется стандартная сборка VueJS приложения средствами npm, версией не ниже 8.1.х (версия node 20.х.х).
```
npm сi
npm run build
```

В результате будут сгенерированы статические файлы в папке /dist. Их необходимо
опубликовать используя web-сервер. Например, nginx.

Подробнее о вариантах развертывания можно узнать [тут](https://cli.vuejs.org/ru/guide/deployment.html).

## Интеграция с GitLab
### Для локального развертывания
В файле "example" укажите адрес GitLab в соответствующей переменной:
```
VUE_APP_DOCHUB_GITLAB_URL=https://foo.space
```

В GitLab **под своей учетной записью** выпустите персональный токен Profile->Preferences->Access Tokens

![Пример настройки GitLab](https://raw.githubusercontent.com/DocHubTeam/DocHub/master/pics/personal_token.png)

Полученный токен укажите в файле ".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. Документацию по настройке можно найти на
[официальном сайте](https://docs.gitlab.com/ee/integration/oauth_provider.html).

![Пример настройки GitLab](https://raw.githubusercontent.com/DocHubTeam/DocHub/master/pics/gitoauth.png)

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

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

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

Следите за новостями в [группе комьюнити](https://t.me/archascode) и нашем [канале](https://t.me/dochubchannel).

# Статьи
* [Архитектура как кот VS Архитектура как кол](https://habr.com/ru/company/rabota/blog/578340/);
* [Архитектура как данные](https://habr.com/ru/post/593009/);
* [Архитектура рядом с кодом](https://habr.com/ru/post/659595/);
* [Код архитектуры — это жидкость](https://habr.com/ru/post/701050/);
* [Кто последний на индустриальный стандарт? Мне только спросить…](https://habr.com/ru/post/713534/);

# Воркшопы
* [Старт использования](https://youtu.be/A7U4KiE5uhQ)
* [Ванильная метамодель DocHub](https://youtu.be/reuVl9rQyXM)
* [Реверс-архитектура](https://youtu.be/yp4PgZUYBZY)
* [Опыт ГК Самолет](https://youtu.be/8nMWWaw_GYQ)
* [Кастомизация метамодели](https://youtu.be/57LxueZy0mc)

# Доклады
* [Доклад "Архитектура как код" на FlowConf 2023](https://www.youtube.com/watch?v=B7IqUR9yb0w);
* [Доклад "Архитектура как код" на ArchDays 2022](https://www.youtube.com/watch?v=gLsKxWjRPoI);
* [Круглый стол 2021](https://youtu.be/tGulYbKW_Lg).

# Сообщество
* [Группа DocHubTeam](https://t.me/archascode)
* [Канал "Архитектура как код"](https://t.me/dochubchannel)

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

Каждая [звезда DocHub](#), это камень в фундамент подхода "Архитектура как код"!
 
 ## Stargazers over time
[![Звезды на GitHub](https://starchart.cc/DocHubTeam/DocHub.svg?variant=adaptive)](https://starchart.cc/DocHubTeam/DocHub)

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

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

## Проблема

Цель создания DocHub — инструментализировать подход управления архитектурой кодом для его развития. DocHub разработан 
как [FOSS](https://en.wikipedia.org/wiki/Free_and_open-source_software) продукт, который должен развиваться сообществом.

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

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

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

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

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

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

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

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

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

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

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

DocHub

Download

Today's picks

Was this content helpful?

Recent Feedback

DocHub

Download

Today's picks

Was this content helpful?

Recent Feedback

Download README