FLOW: Структура работы приложения

Published

June 11, 2026

WarningОграничение публичной документации

В открытом доступе представлена демонстрационная версия метода. В настоящей публичной документации отображены не все шаги, технические сценарии и приватные эндпоинты для системы цифровых симуляторов бизнес-процессов.

  • Полная спецификация метода: Будет доступна только во внутреннем контуре разработки (Confluence / Swagger Enterprise).

1 Архитектура системы (System Architecture)

Архитектура системы спроектирована по многослойному (Layered Architecture) принципу с четким разделением зон ответственности (Separation of Concerns). Система разделена на изолированные слои, что обеспечивает независимое масштабирование клиентской части, производительного бэкенда, тяжелых вычислений и систем хранения данных. Вся архитектура делится на пять ключевых доменов:

  1. Edge Layer — слой первичного приема, фильтрации и распределения трафика.
  2. Core Backend Layer — центральный слой бизнес-логики на базе Go, оркестрирующий все потоки данных.
  3. Storage & Persistence — распределенный слой хранения транзакционных данных, событий и медиафайлов.
  4. Heavy AI Compute Layer — изолированный слой выполнения ресурсоемких задач искусственного интеллекта, где FastAPI выступает в роли сервисного интерфейса для ML-моделей (распознавание речи, компьютерное зрение).
  5. Observability Layer — сквозная инфраструктура логирования, сбора метрик и мониторинга состояния системы.

graph TD
    %% ОПРЕДЕЛЕНИЕ УЗЛОВ И САБГРАФОВ
    subgraph Edge_Layer ["Edge Layer (Контур контроля доступа)"]
        RN["Flutter Client / Агенты Симулятора"]
        Nginx["Nginx Reverse Proxy & Gateway"]
    end

    subgraph Core_Backend_Layer ["Core Backend Layer (Контур оркестрации)"]
        GoBackend["Go Core Backend"]
    end

    subgraph Heavy_AI_Compute_Layer ["Heavy AI & Analytics Layer (Вычисления и Майнинг)"]
        FastAPIWrapper["FastAPI Wrapper Nodes"]
        gRPCNodes["Whisper / OCR"]
        PM4Py["PM4Py (Process Mining Engine)"]
    end

    subgraph Storage_Persistence_Layer ["Storage & Persistence Layer (Слой хранения)"]
        MinIO["MinIO S3 Object Storage"]
        Kafka["Apache Kafka Cluster: KRaft"]
        DB1["PostgreSQL Auth DB"]
        DB2["PostgreSQL Business DB"]
    end

    subgraph Analytics_Observability_Layer ["Analytics & Observability Layer"]
        ClickHouse["ClickHouse DBMS (Единое аналитическое хранилище)"]
    end

    %% НАПРАВЛЕНИЯ ОСНОВНЫХ ПОТОКОВ ДАННЫХ
    RN -->|HTTP/HTTPS requests| Nginx
    Nginx -->|Проксирование и балансировка| GoBackend
    
    %% Связи Go Core бэкенда
    GoBackend -->|gRPC поверх HTTP/2| FastAPIWrapper
    GoBackend -->|Неблокирующий ввод-вывод| MinIO
    GoBackend -->|Асинхронный пуш DTO-событий| Kafka
    GoBackend -->|Транзакции и логи сессий| DB1
    GoBackend -->|Бизнес-логика и каталоги| DB2

    %% Внутренняя логика ИИ и Аналитики
    FastAPIWrapper --- gRPCNodes
    FastAPIWrapper --- PM4Py
    
    %% БИЗНЕС-ПОТОК: Репликация данных для Process Mining
    DB2 -->|ETL / CDC Репликация логов процессов| ClickHouse
    ClickHouse ==>|Выборка Event Logs для анализа| PM4Py

    %% ТЕХНИЧЕСКИЙ ПОТОК: Обсервабилити (Логирование компонентов)
    Nginx -.->|stdout/stderr логи| ClickHouse
    GoBackend -.->|Логи горутин и метрики| ClickHouse
    FastAPIWrapper -.->|Метрики ML-моделей| ClickHouse
    Kafka -.->|Метрики очередей| ClickHouse

    %% СТИЛИЗАЦИЯ
    style GoBackend fill:#2B6CB0,stroke:#fff,stroke-width:2px,color:#fff
    style FastAPIWrapper fill:#2F855A,stroke:#fff,stroke-width:2px,color:#fff
    style gRPCNodes fill:#D69E2E,stroke:#fff,stroke-width:2px,color:#fff
    style PM4Py fill:#4A5568,stroke:#fff,stroke-width:2px,color:#fff
    style ClickHouse fill:#E53E3E,stroke:#fff,stroke-width:2px,color:#fff
    style Nginx fill:#319795,stroke:#fff,stroke-width:2px,color:#fff
    style Kafka fill:#10B981,stroke:#fff,stroke-width:2px,color:#fff

2 Технологический ландшафт (Tech Stack / IT Landscape)

Технологический стек системы подобран с упором на максимальную производительность, параллелизм и эффективную работу с ИИ-моделями:

  • Client / Simulation: Кроссплатформенный фреймворк Flutter для пользовательского интерфейса и специализированные агенты симулятора для генерации синтетической нагрузки.
  • API Gateway & Proxy: Веб-сервер Nginx, выступающий в роли Reverse Proxy и балансировщика нагрузки.
  • Core Backend: Бэкенд на Go, обеспечивающий обработку бизнес-логики, эффективную параллелизацию задач с помощью горутин (goroutines) и низкое потребление ресурсов.
  • Compute Layer (AI): Контейнеризированные узлы gRPC FoodService Nodes, завернутые в асинхронный веб-фреймворк FastAPI (Python) для предоставления gRPC-интерфейса к тяжелым ML-моделям распознавания речи (например Whisper) и оптического распознавания текста (OCR).
  • Brokers & Storage: Apache Kafka в современной архитектуре KRaft (без необходимости развертывания ZooKeeper) для надежного асинхронного стриминга событий.
  • MinIO S3 — S3-совместимое объектное хранилище для неструктурированных медиаданных.
  • PostgreSQL — реляционная СУБД, разделенная на два изолированных инстанса: Auth DB (сессии, права, пользователи) и Business DB (каталоги, бизнес-сущности).

graph TD
    %% СХЕМА ТЕХНОЛОГИЧЕСКОГО ЛАНДШАФТА (БЕЗ СВЯЗЕЙ ДЛЯ МАКСИМАЛЬНОЙ ШИРИНЫ)

    subgraph Layer1 ["1. CLIENT & SIMULATION LAYER"]
        direction LR
        Flutter["Frontend: Flutter Framework"]:::clientStep
        Bots["Load Generation: Custom Simulation Bots"]:::clientStep
    end

    subgraph Layer2 ["2. ROUTING & INGRESS LAYER"]
        direction LR
        Nginx["Reverse Proxy / API Gateway: Nginx"]:::nginxStep
    end

    subgraph Layer3 ["3. CORE BACKEND LAYER"]
        direction LR
        Go["Runtime & Orchestration: GO (Golang)"]:::goStep
    end

    subgraph Layer4 ["4. COMPUTE & ANALYTICS LAYER"]
        direction LR
        FastAPI["API Wrapper: FastAPI (Python)"]:::aiStep
        Whisper["Speech-to-Text: OpenAI Whisper"]:::aiStep
        OCR["Text Recognition: CV OCR"]:::aiStep
        PM4Py["Process Mining: PM4Py Engine"]:::aiStep
    end

    subgraph Layer5 ["5. DATA & MESSAGING LAYER"]
        direction LR
        Kafka["Event Streaming: Apache Kafka (KRaft)"]:::pgStep
        Postgres["Relational СУБД: PostgreSQL"]:::pgStep
        MinIO["Object Storage: MinIO S3"]:::pgStep
    end

    subgraph Layer6 ["6. ANALYTICS & OBSERVABILITY LAYER"]
        direction LR
        ClickHouse["Columnar DBMS: ClickHouse (DWH / Logs)"]:::chStep
    end

    %% НАСТРОЙКА ЦВЕТОВЫХ СТИЛЕЙ
    
    %% 1. Слой клиента (Фиолетовый)
    style Layer1 fill:#F3E8FF,stroke:#7E22CE,stroke-width:1px,color:#6B21A8,font-weight:bold
    classDef clientStep fill:#FFFFFF,stroke:#A855F7,stroke-width:1px,color:#2D3748;

    %% 2. Слой маршрутизации (Бирюзовый)
    style Layer2 fill:#E6FFFA,stroke:#0D9488,stroke-width:1px,color:#115E59,font-weight:bold
    classDef nginxStep fill:#FFFFFF,stroke:#0D9488,stroke-width:1px,color:#2D3748;

    %% 3. Слой Go-бэкенда (Синий)
    style Layer3 fill:#E0F2FE,stroke:#0369A1,stroke-width:1px,color:#0C4A6E,font-weight:bold
    classDef goStep fill:#FFFFFF,stroke:#0EA5E9,stroke-width:1px,color:#2D3748;

    %% 4. Слой ИИ и Аналитики (Зеленый)
    style Layer4 fill:#F0FDF4,stroke:#15803D,stroke-width:1px,color:#14532D,font-weight:bold
    classDef aiStep fill:#FFFFFF,stroke:#22C55E,stroke-width:1px,color:#2D3748;

    %% 5. Слой хранения и брокеров (Серый)
    style Layer5 fill:#F5F5F4,stroke:#78716C,stroke-width:1px,color:#44403C,font-weight:bold
    classDef pgStep fill:#FFFFFF,stroke:#78716C,stroke-width:1px,color:#2D3748;

    %% 6. Слой ClickHouse (Красный)
    style Layer6 fill:#FEF2F2,stroke:#B91C1C,stroke-width:1px,color:#7F1D1D,font-weight:bold
    classDef chStep fill:#FFFFFF,stroke:#EF4444,stroke-width:1px,color:#2D3748;

3 Поток данных (Data Flow)

Поток данных (Data Flow) в системе имеет направленный характер и разделяется на синхронный (запрос-ответ) и асинхронный (событийно-ориентированный) конвейеры:

  1. Входящий поток: Данные рождаются на клиенте (Flutter / Агенты) и в виде HTTP/HTTPS запросов поступают на Nginx.
  2. Маршрутизация: Nginx проксирует очищенный поток на центральный Go Core Backend.
  3. Разветвление потоков на Бэкенде: Go-сервис выступает главным диспетчером и делит данные по типу обработки:
  • Транзакционные данные: Направляются в виде SQL-запросов строго в целевые базы — авторизационные данные в Auth DB, данные предметной области — в Business DB.
    • Бинарные / Тяжелые данные: Через эффективный неблокирующий ввод-вывод (Non-blocking I/O) отправляются из Go на долговременное хранение в MinIO S3 Object Storage.
    • Событийные данные: Трансформируются в DTO (Data Transfer Object) и асинхронно пушатся в топики Kafka.
    • ИИ-запросы: Поток данных, требующий интеллектуальной обработки, перенаправляется бэкендом по протоколу gRPC поверх HTTP/2 на слой ИИ, где его принимает FastAPI и передает в нейросети.

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'actorBkg': '#E3F2FD',
    'actorBorder': '#546E7A',
    'actorTextColor': '#0D47A1',
    'rectBkg': '#FFF9C4',
    'rectBorder': '#FBC02D',
    'noteBkgColor': '#F3E5F5',
    'noteBorderColor': '#7E57C2',
    'noteTextColor': '#311B92',
    'signalColor': '#2C3E50',
    'signalLineColor': '#2C3E50'
  }
}}%%

sequenceDiagram
    autonumber
    actor Client as Flutter / Боты
    participant Go as Go Core Backend
    participant DB as PostgreSQL
    participant CH as ClickHouse DBMS
    participant PM as FastAPI (PM4Py Engine)

    %% 1. Инициация и транзакционный слой
    Note over Client, Go: [ТРАНЗАКЦИОННЫЙ ПОТОК]
    Client->>Go: Запуск сценария симуляции (HTTP POST)
    Go->>CH: [Tech Log] Старт обработки запроса (Асинхронный пуш)
    Go->>DB: Запись текущего состояния процесса в транзакционную БД
    DB-->>Go: Успешное сохранение (ID транзакции)
    Go-->>Client: Сценарий принят в работу (HTTP 202 Accepted)

    %% 2. Аналитический слой (Репликация)
    Note over DB, CH: [АНАЛИТИЧЕСКИЙ ПОТОК (ETL / СИНХРОНИЗАЦИЯ)]
    loop Каждые N секунд / По событию CDC
        DB->>CH: Репликация сырых исторических логов (Postgres -> ClickHouse)
    end

    %% 3. Слой Process Mining
    Note over CH, PM: [ПОТОК PROCESS MINING И АНАЛИЗА]
    Client->>Go: Запрос аналитики процесса (Хочу граф / Conformance Checking)
    Go->>PM: Инициация анализа бизнес-процесса (gRPC)
    PM->>CH: Тяжелый аналитический SQL-запрос (Выборка Event Logs)
    CH-->>PM: Массив исторических данных (Case ID, Activity, Timestamp)
    Note over PM: PM4Py обрабатывает логи,<br/>строит граф процесса (DFG)
    PM-->>Go: Результаты майнинга процессов (gRPC ответ JSON/Прото)
    Go-->>Client: Визуализация графа бизнес-процесса на UI

4 Схема взаимодействия компонентов (Component Interaction Flow / Diagram)

Взаимодействие между компонентами системы строго регламентировано протоколами связи для минимизации накладных расходов:

  • Клиент ── Nginx ── Go Бэкенд: Взаимодействие строится на классическом REST-подходе по протоколам HTTP/HTTPS.
  • Go Бэкенд ── Вычислительный слой (FastAPI / AI): Синхронное, но максимально быстрое межсервисное взаимодействие. Компиляторный Go общается с FastAPI через gRPC поверх HTTP/2. Это позволяет стримить бинарные данные (например, аудиофайлы для Whisper или изображения для OCR) напрямую из бэкенда в Python-сервис в рамках постоянных мультиплексированных соединений с минимальным оверхедом.
  • Go Бэкенд ── Брокер сообщений: Полностью асинхронное взаимодействие. Go-сервис отправляет DTO-события в Kafka, используя эффективные нативные библиотеки, не блокируя основной поток выполнения.
  • Компоненты ── Observability: Все компоненты системы пишут логи в стандартные потоки stdout/stderr. Агент Promtail непрерывно считывает эти потоки и отправляет чанками (HTTP POST Chunks) в хранилище Loki, откуда Grafana запрашивает их через LogQL.

graph LR
    %% ОПРЕДЕЛЕНИЕ СТИЛЕЙ
    classDef edgeStyle fill:#ececff,stroke:#9370db,stroke-width:2px;
    classDef coreStyle fill:#e1f5fe,stroke:#0288d1,stroke-width:2px;
    classDef storageStyle fill:#efebe9,stroke:#5d4037,stroke-width:2px;
    classDef aiStyle fill:#e8f5e9,stroke:#388e3c,stroke-width:2px;
    classDef obsStyle fill:#fff3e0,stroke:#f57c00,stroke-width:2px;

    %% УЗЛЫ СИСТЕМЫ
    Clients["Flutter / Sims"]:::edgeStyle
    Nginx["Nginx Proxy / Gateway"]:::edgeStyle
    Go["Go Core Backend"]:::coreStyle
    
    subgraph Compute ["Heavy AI & Analytics Layer"]
        FastAPI["FastAPI Wrapper Nodes"]:::aiStyle
        Whisper["Whisper Module"]:::aiStyle
        OCR["OCR Module"]:::aiStyle
        PM4Py["PM4Py Engine"]:::aiStyle
    end

    subgraph Storage ["Storage & Persistence Layer"]
        MinIO["MinIO S3 Storage"]:::storageStyle
        Kafka["Apache Kafka (KRaft)"]:::storageStyle
        PostgresAuth["PostgreSQL (Auth DB)"]:::storageStyle
        PostgresBiz["PostgreSQL (Business DB)"]:::storageStyle
    end

    ClickHouse["ClickHouse DBMS (DWH / Logs)"]:::obsStyle

    %% СЕТЕВЫЕ ВЗАИМОДЕЙСТВИЯ (Направление стрелки = кто инициирует сессию)
    Clients -->|HTTP / HTTPS| Nginx
    Nginx -->|Reverse Proxy / HTTP| Go
    
    %% Транзакционное взаимодействие Go бэкенда
    Go -->|SQL / gRPC Drivers| PostgresAuth
    Go -->|SQL / gRPC Drivers| PostgresBiz
    Go -->|AWS S3 API / TCP| MinIO
    Go -->|TCP / native wire protocol| Kafka
    
    %% Межсервисный синхронный gRPC канал (HTTP/2)
    Go -->|gRPC поверх HTTP/2| FastAPI
    FastAPI --- Whisper
    FastAPI --- OCR
    FastAPI --- PM4Py

    %% Аналитический поток (Асинхронная репликация данных)
    PostgresBiz -->|CDC / ETL Репликация| ClickHouse
    PM4Py -->|Аналитические SQL Запросы| ClickHouse

    %% Инфраструктурный поток обсервабилити (Телеметрия)
    Nginx -.->|Асинхронный стриминг логов| ClickHouse
    Go -.->|Метрики горутин и трассировка| ClickHouse
    FastAPI -.->|Метрики утилизации GPU/CPU| ClickHouse

  • Изоляция транзакционного и аналитического контуров: Обратите внимание, что сервис PM4Py не имеет прямого доступа к операционной базе Business DB. Межсервисный запрос направлен строго в ClickHouse. Это полностью защищает «живую» базу данных от деградации производительности во время тяжелых расчетов Process Mining.

  • Взаимодействие между бэкендом на Go и ИИ/аналитическим слоем FastAPI осуществляется через постоянные мультиплексированные gRPC (HTTP/2) соединения. Это минимизирует задержки (overhead) на сериализацию данных и открытие сетевых сокетов, что критично для передачи аудиофайлов в Whisper или тяжелых логов в PM4Py.

  • Конвергентность логирования: Вместо поддержки распределенного пула инфраструктурных агентов, все сервисы пишут структурированную телеметрию напрямую в ClickHouse через нативные драйверы, снижая нагрузку на сеть и упрощая администрирование системы.

5 Сквозная логика системы (End-to-End System Flow)

Рассмотрим, как работает система на примере сквозного сценария: «Пользователь загружает голосовое сообщение или фото чека/меню для распознавания в симуляторе».

  1. Инициация: Пользователь в мобильном приложении нажимает кнопку и отправляет медиафайл. Запрос проходит через Nginx и принимается бэкендом на Go.
  2. Сохранение оригинала: Go-бэкенд принимает файл и через неблокирующий ввод-вывод моментально сохраняет его в MinIO S3, получая уникальный ID файла.
  3. Фиксация события: Бэкенд фиксирует метаданные запроса в Business DB и отправляет асинхронное уведомление (DTO-событие) в Kafka о том, что создана новая задача.
  4. Тяжелые вычисления (AI): Go-бэкенд инициирует gRPC-вызов к вычислительным нодам. На стороне ИИ-слоя FastAPI принимает этот вызов и, в зависимости от типа файла, передает управление конкретной ML-модели — либо Whisper (транскрибация аудио в текст), либо модулю OCR (распознавание текста с картинки).
  5. Мониторинг шагов: На каждом этапе (сохранение в S3, отправка в Kafka, работа нейросети на FastAPI) сервисы отправляют технические логи в stdout. Promtail моментально доставляет их в Loki, и администратор системы видит весь путь прохождения запроса на дашборде Grafana в реальном времени.
  6. Финал: Результат распознавания возвращается из ИИ-ноды обратно в Go-бэкенд через gRPC-ответ, обновляется статус в PostgreSQL, и пользователь видит обработанные данные на экране своего устройства.

graph TD
    %% НАСТРОЙКА КОНТЕЙНЕРОВ (ПЛАВАТЕЛЬНЫХ ДОРОЖЕК) С ЦВЕТОВЫМ РАЗДЕЛЕНИЕМ
    
    subgraph Client_Layer ["КЛИЕНТСКИЙ СЛОЙ"]
        A["1. Запуск симуляции (Flutter / Агенты)"]:::clientStep
        H["8. Визуализация графа процесса на UI"]:::clientStep
    end

    subgraph Go_Layer ["GO CORE BACKEND"]
        B["2. Прием запроса (через Nginx)"]:::goStep
        G["7. Оркестрация и отправка ответа"]:::goStep
    end

    subgraph PG_Layer ["ПОТОК ТРАНЗАКЦИЙ (PostgreSQL)"]
        C["3. Фиксация шагов в Business DB"]:::pgStep
    end

    subgraph CH_Layer ["АНАЛИТИЧЕСКОЕ ХРАНИЛИЩЕ (ClickHouse)"]
        D["4. Асинхронная CDC-репликация данных"]:::chStep
        F["6. Отдача Event Logs по SQL-запросу"]:::chStep
    end

    subgraph AI_Layer ["ВЫЧИСЛЕНИЯ (FastAPI / PM4Py)"]
        E["5. Запуск Process Mining через gRPC"]:::aiStep
    end

    %% СВЯЗИ И НАПРАВЛЕНИЕ СКВОЗНОГО ПОТОКА
    A -->|HTTP POST: Параметры сессии| B
    B -->|SQL: Запись ACID-состояния| C
    C -.->|Асинхронный стрим логов| D
    B ==>|gRPC: Запрос аналитики процесса| E
    E ==>|SQL: Выборка Case ID, Activity, Time| F
    F ==>|Плоский массив Event Logs| E
    E ==>|gRPC ответ: Граф процесса| G
    G -->|HTTP 200 OK: Данные для отрисовки| H

    %% НАСТРОЙКА ЦВЕТОВЫХ СТИЛЕЙ (Уникальные подложки слоев и шагов)
    
    %% 1. Слой клиента (Фиолетовый)
    style Client_Layer fill:#F3E8FF,stroke:#7E22CE,stroke-width:1px,color:#6B21A8,font-weight:bold
    classDef clientStep fill:#FFFFFF,stroke:#A855F7,stroke-width:2px,color:#2D3748;

    %% 2. Слой Go-бэкенда (Синий)
    style Go_Layer fill:#E0F2FE,stroke:#0369A1,stroke-width:1px,color:#0C4A6E,font-weight:bold
    classDef goStep fill:#FFFFFF,stroke:#0EA5E9,stroke-width:2px,color:#2D3748;

    %% 3. Слой транзакций Postgres (Коричневый/Серый)
    style PG_Layer fill:#F5F5F4,stroke:#78716C,stroke-width:1px,color:#44403C,font-weight:bold
    classDef pgStep fill:#FFFFFF,stroke:#78716C,stroke-width:2px,color:#2D3748;

    %% 4. Слой ClickHouse (Красный/Оранжевый)
    style CH_Layer fill:#FEF2F2,stroke:#B91C1C,stroke-width:1px,color:#7F1D1D,font-weight:bold
    classDef chStep fill:#FFFFFF,stroke:#EF4444,stroke-width:2px,color:#2D3748;

    %% 5. Слой ИИ и Аналитики (Зеленый)
    style AI_Layer fill:#F0FDF4,stroke:#15803D,stroke-width:1px,color:#14532D,font-weight:bold
    classDef aiStep fill:#FFFFFF,stroke:#22C55E,stroke-width:2px,color:#2D3748;

    %% Выделение синим цветом стрелок основного аналитического конвейера
    linkStyle 3,4,5,6 stroke:#2563EB,stroke-width:3px;