# danuk/shm architecture

> Architecture diagram of the GitHub repository danuk/shm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/danuk/shm
- Repository: https://github.com/danuk/shm

## Overview

##### Определение типа и назначения проекта
- Это 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.

Итоговая диаграмма должна показать все перечисленные компоненты, их связи и порядок взаимодействия, позволяя инженеру сразу оценить архитектуру, границы модулей и точки интеграции.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Зоны
    subgraph "HTTP-слой" 
        style HTTP fill:#e0f3ff
        NGINX["Nginx (Reverse Proxy)"]:::infra
        UWSGI["uWSGI/PSGI адаптер"]:::infra
        Static["Статика"]:::infra
        CGI["CGI-скрипты (user, admin, pay_systems, v1.cgi, healthcheck.cgi, object.cgi)"]:::infra
        ScriptCGI["Доп. CGI (reset_admin_pass.cgi)"]:::infra
    end

    subgraph "Приложение" 
        style App fill:#e6ffe6
        Init["init.pl (контейнер, миграции)"]:::infra
        Migrations["Миграции БД"]:::db
        CoreBilling["Core/Billing"]:::core
        CoreOrders["Core/Orders"]:::core
        CoreServices["Core/Services"]:::core
        CoreDomain["Core/Domain"]:::core
        CoreSpool["Core/Spool"]:::core
        CoreTransport["Core/Transport"]:::core
        CoreTemplate["Core/Template"]:::core
        CoreTask["Core/Task"]:::core
        CoreConfig["Core/Config"]:::core
    end

    subgraph "Хранение" 
        style Storage fill:#fff0b3
        MySQL["MySQL"]:::db
    end

    subgraph "Очередь" 
        style Queue fill:#fff0b3
        SpoolCLI["spool.pl (enqueue/dequeue)"]:::db
        CronJob["K8s CronJob (spool)"]:::db
    end

    subgraph "Внешние сервисы" 
        style External fill:#ffe6e6
        PAY["Платёжные шлюзы"]:::external
        DNSREG["DNS-регистраторы"]:::external
        MAIL["SMTP (Mail)"]:::external
        SSH["SSH сервисы"]:::external
        TELE["Telegram"]:::external
    end

    subgraph "Оркестратор" 
        style Orchestrator fill:#e0f3ff
        Docker["Docker/K8s"]:::infra
        Helm["Helm chart"]:::infra
        ConfigMap["ConfigMaps/Secrets"]:::infra
        Ingress["Ingress/Service"]:::infra
    end

    %% Поток запросов
    Браузер["Браузер Admin/User"]:::external -->|HTTP| NGINX
    APIClient["API-клиенты"]:::external -->|HTTP| NGINX
    NGINX -->|уведомить| Static
    NGINX -->|proxy_pass| UWSGI
    UWSGI -->|PSGI| CGI
    CGI -->|Core API| CoreBilling
    CGI --> CoreOrders
    CGI --> CoreServices
    CGI --> CoreDomain
    CGI --> CoreSpool
    CGI --> CoreTransport
    CGI --> CoreTemplate
    CGI --> CoreTask
    CGI --> CoreConfig
    CGI -->|SQL| MySQL
    MySQL -->|результат| CGI
    CGI -->|HTTP ответ| NGINX
    NGINX -->|HTTP ответ| Браузер

    %% Фоновые задачи
    CoreSpool -->|enqueue| SpoolCLI
    SpoolCLI -->|cronjob| CronJob
    CronJob -->|worker| CoreSpool
    CoreTransport -->|HTTP| PAY
    CoreTransport -->|API| DNSREG
    CoreTransport -->|SMTP| MAIL
    CoreTransport -->|SSH| SSH
    CoreTransport -->|Webhook| TELE

    %% Миграции
    Init -->|запуск| Migrations
    Migrations -->|DDL/DML| MySQL

    %% Оркестрация
    Docker --> Init
    Docker --> CronJob
    Helm --> Docker
    ConfigMap --> CoreConfig
    Ingress --> NGINX

    %% Click Events
    click NGINX "https://github.com/danuk/shm/blob/master/nginx/default.conf"
    click UWSGI "https://github.com/danuk/shm/blob/master/nginx/uwsgi.ini"
    click CGI "https://github.com/danuk/shm/tree/master/app/public_html/shm/"
    click ScriptCGI "https://github.com/danuk/shm/tree/master/app/scripts/"
    click Init "https://github.com/danuk/shm/blob/master/app/bin/init.pl"
    click Migrations "https://github.com/danuk/shm/tree/master/app/bin/migrations/"
    click SpoolCLI "https://github.com/danuk/shm/blob/master/app/bin/spool.pl"
    click CoreBilling "https://github.com/danuk/shm/blob/master/app/lib/Core/Billing.pm"
    click CoreOrders "https://github.com/danuk/shm/blob/master/app/lib/Core/Orders.pm"
    click CoreServices "https://github.com/danuk/shm/tree/master/app/lib/Core/Services/"
    click CoreDomain "https://github.com/danuk/shm/tree/master/app/lib/Core/Domain/"
    click CoreSpool "https://github.com/danuk/shm/blob/master/app/lib/Core/Spool.pm"
    click CoreTransport "https://github.com/danuk/shm/blob/master/app/lib/Core/Transport/Http.pm"
    click CoreTemplate "https://github.com/danuk/shm/blob/master/app/lib/Core/Template.pm"
    click CoreTask "https://github.com/danuk/shm/blob/master/app/lib/Core/Task.pm"
    click CoreConfig "https://github.com/danuk/shm/blob/master/app/conf/shm.conf"
    click MySQL "https://github.com/danuk/shm/blob/master/app/sql/shm/shm_structure.sql"
    click CronJob "https://github.com/danuk/shm/blob/master/helm/k8s-shm/charts/helm-common/templates/cronjob.yaml"
    click Docker "https://github.com/danuk/shm/tree/master/Dockerfile"
    click Helm "https://github.com/danuk/shm/tree/master/helm/k8s-shm/"
    click ConfigMap "https://github.com/danuk/shm/tree/master/helm/k8s-shm/"
    click Ingress "https://github.com/danuk/shm/tree/master/helm/k8s-shm/"

    %% Styles
    classDef infra fill:#cce5ff,stroke:#3399ff,color:#003366
    classDef core fill:#e6ffe6,stroke:#33cc33,color:#006600
    classDef db fill:#fff0b3,stroke:#ffcc00,color:#664d00
    classDef external fill:#ffe6e6,stroke:#ff3333,color:#660000
```
