iac/docs/architecture/README.md

Модель архитектуры в нотации ArchiMate

Модель технологического слоя типового контура платформы. Все данные, зависящие от конкретной инсталляции — имя кластера, узлы, домены, реестр — заменены на примеры. Реальные значения в репозиторий не попадают: они задаются профилем контура, который держится отдельно.

Прикладной слой присутствует только как потребители технологических сервисов. Межсервисные REST-связи приложений и бизнес-слой будут добавлены отдельно.

Файлы

Файл	Формат	Чем открывать
example-technology.archimate	нативный формат Archi	десктопный Archi: File → Open
example-technology.xml	The Open Group ArchiMate Model Exchange File Format 3.1	любой инструмент с импортом Open Exchange, в том числе archi-online.com: Import, save, and create models → Open Exchange
preview.html	SVG-рендер всех представлений	любой браузер, без установки чего-либо

70 элементов, 153 отношения, 9 представлений.

Представление	Что показывает
T1	Кластер, ПО внутри него, внешние узлы, технологические сервисы. Без приложений — обзорная схема
T2–T9	По одному представлению на технологический сервис: кто им пользуется

Разбиение по сервисам сделано осознанно: все 118 связей «сервис → приложение» на одной схеме нечитаемы. В модели они лежат одним набором, представления — это срезы.

Метамодель намеренно урезана. Технологический слой: Node, SystemSoftware, TechnologyService, Artifact. Прикладной: ApplicationComponent. Отношения: Composition, Realization, Serving, Assignment. Не используются Device, Path, CommunicationNetwork, TechnologyFunction — они не несут информации на этом уровне.

Как собрать модель для реального контура

1. Снять матрицу связей с нужного кластера:

   py scan_contour.py <имя-кластера> matrix.json
   

2. Скопировать contour-profile.example.json, подставить настоящие имена кластера, узлов, доменов и реестра. Копию хранить вне репозитория.

3. Собрать модель и производные форматы:

   py build_archimate.py <профиль.json> matrix.json out.archimate
   py to_open_exchange.py out.archimate out.xml
   py render_preview.py out.archimate out.html
   

Результат шага 3 в репозиторий не коммитить — он содержит данные контура.

Откуда взяты связи

Не нарисованы от руки, а выведены из манифестов, поэтому проверяемы.

Связь	Источник
Состав кластера, версии чартов	clusters/<контур>/kustomization.yaml, infrastructure/<comp>/base/helmrelease.yaml
Приложение → PostgreSQL	env POSTGRES_*, DB__HOST или путь Vault secrets/data/apps/<app>/postgres
Приложение → RabbitMQ	env RABBITMQ*, AMQP__*
Приложение → Kafka	env KAFKA*, BOOTSTRAP_SERVERS
Приложение → S3	env S3__*, S3_ENDPOINT, S3_ACCESS, S3_BUCKET
Приложение → Redis	env REDIS_HOST, REDIS__*
Приложение → Vault	аннотации vault.hashicorp.com/agent-inject*
Приложение → Zitadel	env ZITADEL*, JWKS, OIDC, секрет jwt-public
Приложение → Istio	service: в маршрутах infrastructure/istio-config/<контур>/istio-config.yaml (закомментированные не считаются)

Сканируются *.yaml в apps/<app>/base/ и apps/<app>/<контур>/; документация *.md игнорируется, иначе прозаические упоминания переменных дают ложные срабатывания.

matrix.example.json — снимок такой матрицы. Он содержит только имена приложений и флаги использования сервисов; идентификаторов контура в нём нет.

Про формат файлов

Нативный .archimate нигде не стандартизирован, и его словарь неочевиден: объекты схем сериализуются как <child xsi:type="archimate:DiagramObject">, соединения — через атрибут relationship. Имена EClass из метамодели (DiagramModelArchimateObject, archimateRelationship) в XML не используются — на них легко попасться, модель тогда открывается с пустыми представлениями.

Эталон для сверки — любая модель из archimatetool/ArchiModels, созданная самим Archi.

example-technology.xml проверен на соответствие официальной схеме archimate3_Diagram.xsd. Если сторонний инструмент не берёт нативный формат, используйте его. Отличие обменной версии: вложенность узлов развёрнута в плоский список с абсолютными координатами (в обменном формате трактовка координат вложенного узла неоднозначна между реализациями). Визуально раскладка та же, но компоненты внутри кластера не будут его дочерними элементами.

Скрипты

Требуется Python 3, внешних зависимостей нет. На Windows запускать через py, а не python.

Скрипт	Назначение
scan_contour.py	матрица «приложение → технологический сервис» по кластеру
build_archimate.py	сборка модели из профиля и матрицы
to_open_exchange.py	конвертация в обменный формат
render_preview.py	рендер представлений в HTML со встроенным SVG

Внимание: после ручной правки модели в Archi источником истины становится .archimate, а повторный запуск build_archimate.py затрёт расстановку элементов. Производные форматы (to_open_exchange.py, render_preview.py) пересобирать после каждой правки, иначе они разъедутся с моделью.