Skip to content

Commit 14aa9a3

Browse files
rpiontikrpiontik
committed
Первый пример для метамодели C4Model
1 parent 7aeff77 commit 14aa9a3

15 files changed

Lines changed: 708 additions & 0 deletions

File tree

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
.idea
2+
.vscode

‎DocHubExamples.iml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<module type="GENERAL_MODULE" version="4">
3+
<component name="NewModuleRootManager" inherit-compiler-output="true">
4+
<exclude-output />
5+
<content url="file://$MODULE_DIR$" />
6+
<orderEntry type="sourceFolder" forTests="false" />
7+
</component>
8+
</module>

‎README.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Примеры использования DocHub
2+
3+
Репозиторий содержит примеры использования инструмента управления архитектурой
4+
[DocHub](https://dochub.info/). Репозиторий развивается силами [сообщества](https://t.me/archascode).
5+
6+
## Цели
7+
8+
* Накопление опыта использования инструмента;
9+
* Развитие практик применения DocHub;
10+
* Формирование базы знаний для создания прикладных метамоделей.
11+
12+
## Каталог
13+
14+
1. [Пример создания пользовательской метамодели C4 Model](src/C4Model)
15+
16+
## Разворачивание
17+
18+
1. Установите IntelliJ IDEA. Рекомендуется [Community Edition](https://www.jetbrains.com/idea/download/);
19+
2. Установите [плагин DocHub](https://plugins.jetbrains.com/plugin/18518-dochub-architecture-as-code);
20+
3. Клонируейте репоизиторий примеров:
21+
```
22+
git clone https://github.com/rpiontik/DocHubExamples.git
23+
```
24+
4. Откройте в IDE каталог DocHubExamples;
25+
5. Найдите справа в панели плагинов закладку DocHub и откройте ее;
26+
6. Откройте файл ./dochub.yaml и раскомментируйте нужный пример;
27+
7. Сохраните файл;
28+
8. Следйте рекомендациям примера;
29+
9. Наблюдайте изменения в рендеринги плагина DocHub справа.
30+
31+
## Порядок развития репозитория
32+
33+
Чтобы сделать вклад в репозиторий, необходимо:
34+
1. Создать форк данного репозитория;
35+
2. Внести изменения:
36+
* в папке ./src создать папку примера (Например, ./src/C4ModelContext);
37+
* в папке примера создать файл README.md, где описать суть примера;
38+
* корневым файлом примера должен быть dochub.yaml;
39+
* папку примера наполнить контентом примера;
40+
* в корневой файл ./dochub.yaml добавить **закомментированную** строку импорта примера. Например:
41+
```
42+
imports:
43+
...
44+
# Пример пользовательского контекста
45+
# - ./src/C4ModelContext/dochub.yaml
46+
```
47+
* внести изменения в файл ./README.md в раздел "Каталог".
48+
3. Создать Pull Request в master ветку данного репозитория.
49+
50+
# Требования к контенту
51+
1. Пример должен быть структурирован, структура файлов продумана, читабельна;
52+
2. Код архитектуры должен быть снабжен комментариями;
53+
3. Названия файлов должны быть на латинице и не должны содержать пробелы;
54+
4. Настоятельно рекомендуется избегать внешних ссылок кроме случаев, когда они являются сутью примера;
55+
5. Данные для примера должны содержаться в самом примере;
56+
6. Рекламные ссылки запрещены без предварительного согласования.
57+
58+
# Рекомендации к контенту
59+
1. Старайтесь в примере погружать читателя в смысл последовательно, предполагая, что он плохо знаком с инструментом;
60+
2. Если для понимания примера нужна подготовка, укажите это явно, давайте ссылки на нужный материал;
61+
3. Сопровождайте пример ссылками на документацию;
62+
4. В README.md включайте наглядные изображения ожидаемого от примера результата.
63+
64+
# Работа с issue репозитория
65+
1. Оставляйте информацию о найденных ошибках, опечатках и прочих отклонениях помечая меткой "bug";
66+
2. Размещайте запросы на примеры как "requests";
67+
3. Идеи оставляйте с меткой "idea".
68+
69+
# Лицензия
70+
71+
Все материалы содержащиеся в данном репозитории являются публичными. Могут использовать без ограничения
72+
с любой целью не противоречащей закону.
73+
74+
Pull request в данный репозиторий означает согласие автора на присоединение к данной лицензии.
75+
76+
The MIT License http://opensource.org/licenses/MIT

‎dochub.yaml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
imports:
2+
# Пример создания метамодели для описания в нотации C4 Model
3+
- src/C4Model/dochub.yaml

‎src/C4Model/README.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Пример создания пользовательской метамодели C4 Model
2+
3+
**Цель примера:** Познакомить с возможностями создания пользовательской метамодели
4+
в инструменте управления архитектурой [DocHub](https://dochub.info).
5+
6+
Пример является адаптацией [примера](https://mermaid-js.github.io/mermaid/#/c4c)
7+
с официального сайта Mermaid.
8+
9+
# Суть примера
10+
DocHub позволяет создавать кастомные метамодели для описания архитектуры в том виде,
11+
которое требуется в конкретной прикладной области.
12+
13+
В базовый функционал DocHub не входит поддержка нотации C4 Model. Данный пример демонстрирует
14+
как пользователь может реализовать эту поддержку самостоятельно.
15+
16+
Пример участка кода:
17+
```yaml
18+
# Описываем L1 Context в нотации C4 Model
19+
c4model:
20+
# ******************************************************
21+
# Клиенты
22+
# ******************************************************
23+
customerA:
24+
title: Customer A
25+
entity: Person
26+
links:
27+
- id: SystemAA
28+
direction: ->
29+
...
30+
# ******************************************************
31+
# Системы
32+
# ******************************************************
33+
SystemAA:
34+
title: Internet Banking System
35+
description: Allows customers to view information about their bank accounts, and make payments.
36+
entity: System
37+
links:
38+
- id: SystemE
39+
direction: ->
40+
title: Uses
41+
- id: SystemC
42+
direction: <->
43+
title: Sends e-mails
44+
description: SMTP
45+
...
46+
```
47+
48+
Результат:
49+
50+
![Пример метамодели C4 Model](./images/c4model.png)
51+
52+
## Файловая структура примера
53+
* components - данные архитектуры для рендеринга
54+
* L1.yaml - компоненты уровня L1 C4 Model
55+
* L2.yaml - компоненты уровня L2 C4 Model
56+
* L3.yaml - компоненты уровня L3 C4 Model
57+
* root.yaml - корневой манифест данных архитектуры
58+
* entities - матемодель;
59+
* templates - шаблоны, используемые для рендеринга диаграмм
60+
* context.mmd - Mermaid шаблон
61+
* c4model.yaml - манифест пользовательской сущности C4Model
62+
* root.yaml - корневой манифест метамодели
63+
* images - картинки для настоящей документаии
64+
* dochub.yaml - корневой манифест примера
65+
66+
## Использование
67+
В меню плагина DocHub выберите пункт "C4 Model"
68+
69+
![Меню](./images/menu.png)
70+
71+
Кликните на диаграмме по компоненту "Internet Banking System".
72+
Вы "провалитесь" в него на уровень L2 в нотации C4 Model.
73+
Далее кликните по компоненту "API Application".
74+
75+
Вносите изменения в данные архитектуры в файлах аталога [components/](./components).
76+
Наблюдайте изменения в рендеринге плагина DocHub.
77+
78+
## Задания для практики
79+
* Опишите компоненты для контейнера SystemAA.spa в файле [components/L3.yaml](./components/L3.yaml);
80+
* Опишите контейнеры системы SystemE в файле [components/L2.yaml](./components/L2.yaml)
81+
и компоненты к ним в файле [components/L3.yaml](./components/L3.yaml);
82+
* Измените шаблон рендеринга с Mermaid на PlantUML;
83+
* Добавьте новое обязательное поле в метамодель [c4model](./entities/c4model.yaml) для уровня L1;
84+
* Реализйте поддержку L4 C4Model в метамодели.

‎src/C4Model/components/L1.yaml‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# Описываем L1 Context в нотации C4 Model
2+
c4model:
3+
# ******************************************************
4+
# Клиенты
5+
# ******************************************************
6+
customerA:
7+
title: Customer A
8+
entity: Person
9+
links:
10+
- id: SystemAA
11+
direction: ->
12+
customerB:
13+
title: Customer B
14+
entity: Person
15+
customerC:
16+
title: Customer C
17+
entity: Person_Ext
18+
customerD:
19+
title: Customer D
20+
entity: Person
21+
22+
# ******************************************************
23+
# Системы
24+
# ******************************************************
25+
SystemAA:
26+
title: Internet Banking System
27+
description: Allows customers to view information about their bank accounts, and make payments.
28+
entity: System
29+
links:
30+
- id: SystemE
31+
direction: ->
32+
title: Uses
33+
- id: SystemC
34+
direction: <->
35+
title: Sends e-mails
36+
description: SMTP
37+
38+
# BankBoundary
39+
SystemE:
40+
title: Mainframe Banking System
41+
description: Stores all of the core banking information about customers, accounts, transactions, etc.
42+
entity: SystemDb_Ext
43+
boundary: BankBoundary
44+
SystemC:
45+
title: E-mail system
46+
description: The internal Microsoft Exchange e-mail system.
47+
entity: System_Ext
48+
boundary: BankBoundary
49+
links:
50+
- id: customerA
51+
direction: <->
52+
title: Sends e-mails to
53+
SystemD:
54+
title: Banking System D Database
55+
description: A system of the bank, with personal bank accounts.
56+
entity: SystemDb
57+
boundary: BankBoundary
58+
59+
# BankBoundary.BankBoundary2
60+
SystemA:
61+
title: Banking System A
62+
entity: System
63+
boundary: BankBoundary.BankBoundary2
64+
SystemB:
65+
title: Banking System B
66+
entity: System
67+
description: A system of the bank, with personal bank accounts.
68+
boundary: BankBoundary.BankBoundary2
69+
70+
# BankBoundary.BankBoundary3
71+
SystemF:
72+
title: Banking System F Queue
73+
description: A system of the bank, with personal bank accounts.
74+
entity: SystemQueue
75+
boundary: BankBoundary.BankBoundary3
76+
SystemG:
77+
title: Banking System G Queue
78+
description: A system of the bank, with personal bank accounts.
79+
entity: System_Ext
80+
boundary: BankBoundary.BankBoundary3

‎src/C4Model/components/L2.yaml‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# Описываем L2 Container в нотации C4 Model
2+
# Раскрываяем SystemAA: Internet Banking System
3+
c4model:
4+
# ******************************************************
5+
# Системы
6+
# ******************************************************
7+
SystemAA.spa:
8+
entity: Container
9+
title: Single-Page App
10+
description: Provides all the Internet banking functionality to customers via their web browser.
11+
tech-stack:
12+
- JavaScript
13+
- Angular
14+
links:
15+
- id: customerA
16+
title: Uses
17+
direction: --
18+
tech-stack:
19+
- HTTPS
20+
- id: SystemAA.backend_api
21+
title: Uses
22+
direction: --
23+
tech-stack:
24+
- async
25+
- HTTPS
26+
- JSON
27+
SystemAA.mobile_app:
28+
entity: Container_Ext
29+
title: Mobile App
30+
description: Provides a limited subset of the Internet banking functionality to customers via their mobile device.
31+
tech-stack:
32+
- C#
33+
- Xamarin
34+
links:
35+
- id: customerA
36+
title: Uses
37+
direction: --
38+
- id: SystemAA.backend_api
39+
title: Uses
40+
direction: --
41+
tech-stack:
42+
- async
43+
- JSON
44+
- HTTPS
45+
SystemAA.web_app:
46+
entity: Container
47+
title: Web Application
48+
description: Delivers the static content and the Internet banking SPA.
49+
tech-stack:
50+
- Java
51+
- Spring MVC
52+
links:
53+
- id: customerA
54+
title: Uses
55+
direction: --
56+
tech-stack:
57+
- HTTPS
58+
- id: SystemAA.spa
59+
direction: --
60+
title: Delivers
61+
SystemAA.database:
62+
entity: ContainerDb
63+
title: Database
64+
description: Stores user registration information, hashed auth credentials, access logs, etc.
65+
tech-stack:
66+
- SQL Database
67+
links:
68+
- id: SystemAA.backend_api
69+
title: Reads from and writes to
70+
direction: <-
71+
tech-stack:
72+
- sync
73+
- JDBC
74+
SystemAA.backend_api:
75+
entity: ContainerDb_Ext
76+
title: API Application
77+
description: Provides Internet banking functionality via API
78+
tech-stack:
79+
- Java
80+
- Docker Container
81+
links:
82+
- id: SystemC
83+
title: Send E-mail
84+
direction: ->
85+
- id: SystemE
86+
title: Uses
87+
direction: --
88+
tech-stack:
89+
- sync
90+
- async
91+
- XML
92+
- HTTPS
93+

0 commit comments

Comments
 (0)