iac/docs/architecture/README.md

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

Модель контура УГМК (d8-ugmk-prod) в двух форматах — содержимое одинаковое:

Файл	Формат	Чем открывать
ugmk-technology.archimate	нативный формат Archi	десктопный Archi: File → Open
ugmk-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-рендер всех представлений	любой браузер, без установки чего-либо

ugmk-technology.xml проверен на соответствие официальной схеме archimate3_Diagram.xsd — валидатор ошибок не нашёл. Если сторонний инструмент не берёт нативный .archimate, используйте его.

Отличие обменной версии: вложенность узлов на схемах развёрнута в плоский список с абсолютными координатами (в обменном формате трактовка координат вложенного узла неоднозначна между реализациями). Визуально раскладка та же, но компоненты внутри кластера не будут «вложены» в него как дочерние — при перетаскивании контейнера содержимое останется на месте.

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

Состав

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

Представление	Что показывает
T1	Кластер, ПО внутри него, внешние узлы, технологические сервисы. Без приложений — обзорная схема
T2	Маршрутизация HTTPS — 21 приложение
T3	Аутентификация OIDC — 10
T4	Управление секретами — 25
T5	Реляционное хранилище — 23
T6	Кэш — 3
T7	Событийная шина — 12
T8	Очередь сообщений AMQP — 11
T9	Объектное хранилище — 13

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

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

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

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

Связь	Источник
Состав кластера	clusters/d8-ugmk-prod/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/d8-ugmk-prod/istio-config.yaml (закомментированные не считаются)

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

Что вскрылось при построении

• Camunda развёрнута, но потребителей нет. camunda-contour 11.0.14 в контуре есть, наружу опубликованы Operate, Tasklist, Optimize, Identity, Keycloak — но ни одно приложение не сконфигурировано на Zeebe. Единственные ссылки на Camunda в apps/ — оверлеи cde/brusnika-prod и cde/brusnika-stage.
• Четыре приложения ни к чему не подключены: projects, prescriptions, cross-section, faas — не используют ни один технологический сервис и не имеют маршрута в istio-config. В модели они есть, но ни в одно представление не попали. Для сравнения: в yc-ecp маршрут /projects/static/ существует.
• Наблюдаемости в контуре нет — ни vmstack, ни prometheus-stack, ни openobserve, ни otel, в отличие от Brusnika и WB. Если мониторинг там есть, он живёт вне этого репозитория.
• Сертификаты самоподписанные — ClusterIssuer sarex-selfsigned, не Let's Encrypt.
• Redis только у pm. В остальных приложениях REDIS_HOST встречается лишь в текстах CONFIGURATION.md.
• Ingress прибит к одному узлу um-sarex-k8s-frontend-01 через nodeSelector — единственная точка отказа внешнего трафика.
• S3 внешний (s3.uralmine.com), MinIO в контуре не разворачивается.

Скрипты

scan_ugmk.py — строит матрицу «приложение → технологический сервис» и кладёт в matrix.json. Полезен, когда состав контура изменился: перезапустить и сравнить.

py scan_ugmk.py matrix.json

build_archimate.py — одноразовая генерация модели из matrix.json.

py build_archimate.py ugmk-technology.archimate

to_open_exchange.py — конвертирует нативный файл в обменный формат. Запускать после каждой правки модели, иначе .xml разъедется с .archimate.

py to_open_exchange.py ugmk-technology.archimate ugmk-technology.xml

render_preview.py — рисует все представления в один HTML со встроенным SVG. Пересобирать вместе с обменным форматом.

py render_preview.py ugmk-technology.archimate preview.html

Внимание: после того как модель отредактирована в Archi, источником истины становится .archimate, а повторный запуск генератора затрёт расстановку элементов. Пересобирать целиком имеет смысл только при перестройке модели с нуля.

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