How danuk/shm works
Определение типа и назначения проекта
• Это open-source биллинговая система «SHM» на Perl, реализующая универсальный биллинг с внешними действиями (платёжные шлюзы, DNS-регистраторы, уведомления и т.п.).
• По структуре это монолитное серверное приложение с CGI/PSGI-точками входа, модульным ядром, миграциями БД, тестами и средствами деплоя (Docker, Helm, Kubernetes).
Анализ структуры файлов
• Папка app/bin – CLI-утилиты (инициализация, миграции, шедулер задач).
• app/lib/Core – бизнес-логика (модули: Billing, Orders, Services, Transport, DNS, Template, Task, Spool и т.д.).
• app/public_html/shm – HTTP/CGI-энды (user, admin, pay_systems, v1 API).
• app/sql – DDL/DML-скрипты для MySQL.
• t/ – множество модульных тестов (API, billing, domain, transport, storage).
• Конфиги: app/conf/shm.conf, nginx/, uwsgi.ini, Dockerfile, docker-compose.yml, Helm chart (helm/k8s-shm).
Основные компоненты системы
a. Внешние клиенты: браузер администратора и пользователя, API-клиенты.
b. Nginx (reverse proxy + статика) → uWSGI/PSGI адаптер → CGI-скрипты/app.
c. Бизнес-слой (app/lib/Core): модули Billing, Orders, Services, Sessions, Spool, Transport, DNS и т.д.
d. База данных MySQL (миграции из app/bin/migrations и app/sql).
e. Система очередей/тасков (spool.pl + cronjob/Helm CronJob).
f. Внешние сервисы: платёжные шлюзы (YooKassa, Freekassa, CryptoCloud и др.), DNS-регистраторы, Telegram, SSH и почта.
g. Инструменты деплоя: Docker-контейнеры, docker-compose, Helm/Kubernetes.
Взаимодействия между компонентами
• HTTP-запросы клиентов → Nginx → CGI/PSGI → Core API → чтение/запись в MySQL → ответ HTTP.
• Core при определённых событиях ставит задачи в очередь (Spool) → cronjob/uWSGI-worker → выполнение тасков → взаимодействие с внешними сервисами через Transport::Http, Ssh, Mail, Telegram.
• Миграции БД запускаются через init-скрипт и app/bin/migrations при инициализации контейнера.
• Тестовые окружения запускаются локально через build.sh или docker-compose.
Важные архитектурные принципы
• Модульность: чёткое разделение на модули Core/... для разных доменов (Billing, Domain, Transport).
• Очереди и асинхронность: модуль Spool для фоновых задач.
• Конфигурируемость: единый конфиг shm.conf + env-переменные (Docker/K8s ConfigMaps/Secrets).
• Инфраструктурная автоматизация: контейнеры и Helm charts.
Рекомендации по построению диаграммы
a. Разделить на зоны:
• Зона «HTTP-слой»: Nginx, CGI/PSGI адаптер, статические файлы.
• Зона «Приложение»: модуль Core (бизнес-логика).
• Зона «Хранение»: MySQL.
• Зона «Очередь»: Spool-микросервис или CronJob.
• Зона «Внешние сервисы».
• Зона «Оркестратор»: Docker/Kubernetes.
b. Показывать направления потоков данных:
• Клиент → Nginx → App → БД → App → Клиент.
• App → Spool → Worker → Внешние сервисы.
c. Цветовая кодировка:
• Синим – внутренняя инфраструктура (Nginx, Docker, K8s).
• Зелёным – бизнес-слой/Core.
• Оранжевым – база данных и очередь.
• Красным – внешние интеграции (платежи, DNS, Telegram, SSH).
d. Фигуры:
• Прямоугольники – сервисы/модули.
• Базы – хранилища.
• Облака – внешние системы.
e. Обозначить пункты конфигурации (ConfigMap, shm.conf).
f. Добавить легенду, стрелки с подписью протокола (HTTP, SQL, SSH, SMTP, Webhook).
Как отразить детали проекта
• На уровне App-слоя указать ключевые модули Core/Billing, Core/Transport, Core/Spool и их взаимодействие.
• Показать точку входа – CGI-скрипты в public_html/shm (user, admin, v1 API).
• Отразить миграции БД (app/bin/migrations) при старте контейнера.
• На уровне оркестрации – Deployment приложения, CronJob для spool, StatefulSet MySQL, ConfigMaps/Secrets, Service, Ingress.
Итоговая диаграмма должна показать все перечисленные компоненты, их связи и порядок взаимодействия, позволяя инженеру сразу оценить архитектуру, границы модулей и точки интеграции.