dochubcore
Advanced tools
DocHub - инструмент описания архитектуры через код (Architecture as a code). Код архитектуры - ансамбль файлов на языках, решающих задачу описания. Поддерживаются:
Решаемые проблемы:
Рекомендую начать с прочтения статьи Архитектура рядом с кодом. Познакомиться с работой инструмента и его подробной документацией можно на сайте https://dochub.info. Примеры использования можно найти в специальном репозитории, который развивает сообщество - Примеры DocHub. Также полезно посмотреть воркшоп по старту использования.
Свежие версии плагинов лежат:
Вступайте в сообщество 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
Time Machine :active, 2023-11-01, 250d
Public metamodel repository :active, 2023-10-01, 200d
section Q2 2024
MVP mutators :active, 2024-01-01, 200d
Process Disigner tool :2024-06-01, 90d
Architectire Commutiny tool :2024-06-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 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
Наш клиент - организация или лицо ее представляющее, которые действительно используют продукт или действительно собираются его использовать.
Наше комьюнити - сообщество полностью или частично разделяющее идею продукта.
Команда продукта работает по принципам Agile. Причина этому не дань "модным тенденциям", а искренняя вера в то, что только мотивированные члены команды могут достичь действительно значимых результатов.
Мы отдаем предпочтение работающему продукту, а не исчерпывающей документации. Документация очень важна, но ровно в необходимом объеме.
Развитие продукта идет в тесной связи с клиентом. Наша задача не соблюсти контракт с ним, а сделать его счастливым. Решить не только его сегодняшние проблемы, но и перспективные.
Мы хорошо понимаем, что наш продукт развивается в динамичном мире. Наша команда постоянно переоценивает свои цели и адекватность средств их достижения.
Мы в крайней степени дорожим вкладом сообщества в продукт. Такой вклад обязательно будет поддержан. Контрибьютор получит всестороннюю помощь успешной интеграции его вклада в продукт. Его вклад будет публично заявлен. Одновременно с этим, команда продукта несет ответственность за стратегическое развитие продукта перед клиентом. За его образ и целостность во всех аспектах. Эта ответственность дает ей право финального решения об образе продукта, его функциональной наполненности и порядке выхода фич.
По этой причине, наши опубликованные планы, это планы в который мы искренне верим сегодня. Но они является лишь инструментом координации команды и комьюнити продукта. Они могут пересматриваться в любой момент, когда станет очевидным, что они устарели.
Следите за новостями в группе комьюнити и нашем канале.
DocHub распространяется под лицензией Apache License 2.0 Open source license.
FAQs
The npm package dochubcore receives a total of 12 weekly downloads. As such, dochubcore popularity was classified as not popular.
We found that dochubcore demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.