Архитектура

Платформа NPPWEB построена как разделённая цепочка сервисов, где сбор, транспорт, нормализация, хранение и аналитика разведены по разным репозиториям и разным зонам ответственности.

Системная схема

Внешние источники
  EIS / EASUZ / RNP / FNS / Fedresurs / GIS Torgi
                |
                v
         scrape-helper
      raw events + artifacts
                |
                v
             RabbitMQ
                |
                v
       processing-worker
  validation -> normalization -> ingest
                |
                v
          npp-backend
   GraphQL + auth + reports + analytics
                |
                v
             npp-web

Основные принципы разбиения

• Сбор не пишет напрямую в базу: внешние сайты нестабильны, поэтому их нельзя связывать напрямую с бизнес-хранилищем.
• Нормализация отделена от парсинга: источники меняются чаще, чем доменная модель.
• Backend — единственный владелец состояния: только он управляет закупками, пользователями, отчётами и source runs.
• Frontend читает только контракт: UI зависит от GraphQL, а не от внутренних таблиц, очередей или формата raw-событий.

Потоки данных

1. Сбор данных

scrape-helper отвечает за:

• запуск по расписанию;
• работу через proxy-контур при необходимости;
• извлечение карточек и артефактов;
• публикацию source.raw.v1;
• загрузку HTML/PDF/выписок в S3-совместимое хранилище.

2. Нормализация и ingest

processing-worker:

• читает raw-события из RabbitMQ;
• валидирует их по общим схемам;
• приводит данные к единому формату;
• вычисляет source-specific и derived поля;
• вызывает ingest в backend через x-ingest-token.

3. Доменный слой и аналитика

npp-backend:

• хранит закупки, отчёты, source runs, источники и пользователей;
• поддерживает auth и server-side сессии;
• считает агрегаты для дашборда и аналитики;
• формирует snapshot-отчёты;
• экспортирует всё это через GraphQL.

4. Представление и управление

npp-web:

• показывает защищённый кабинет;
• разделяет роли USER / ANALYST / DEVELOPER / ADMIN;
• даёт доступ к дашбордам, аналитике, реестрам, отчётам и административным экранам;
• не хранит бизнес-состояние локально, кроме клиентского UI-state.

Технические компоненты платформы

Компонент	Роль в системе
Postgres	primary storage для backend
Redis	служебные backend-сценарии, кэши и runtime-помощь
RabbitMQ	транспорт между сбором и нормализацией
MinIO	артефакты и S3-совместимое файловое хранилище
Xray proxy	доступ к ограниченным внешним площадкам
GitHub Pages	публикация документационного сайта

Доменные сущности

Ключевые бизнес-объекты сходятся в backend:

• Procurement — карточка закупки или договора в нормализованном виде;
• Source — конфигурация источника данных;
• SourceRun — факт запуска источника со статусом и счётчиками;
• Report — сохранённый отчётный snapshot;
• User, UserSession, RefreshToken — auth и доступ;
• rawPayload/sourceSpecificData — трассировка до исходного контекста.

Аналитический слой

Аналитика в NPPWEB строится не отдельно от платформы, а поверх живого доменного слоя.

Что считает backend

• срочные и просроченные закупки;
• высокие чеки и среднюю сумму;
• успех и publication rate по источникам;
• атомный контур по АЭС;
• концентрацию по поставщикам и заказчикам;
• due diligence и отчётные сценарии.

Почему это важно архитектурно

• UI не содержит логики подсчёта аналитики;
• аналитические агрегаты и отчёты можно стабильно воспроизводить;
• источник деградации видно по той же системе, что и бизнес-значение данных.

Границы ответственности

Сервис	Не должен делать
scrape-helper	писать напрямую в Postgres или принимать доменные решения
processing-worker	хранить бизнес-состояние и подменять backend
npp-backend	зависеть от внутреннего формата конкретного парсера в UI
npp-web	читать внутренние таблицы, очереди и артефакты напрямую

Точки изменений

Если меняется:

• внешний источник — сначала меняется scrape-helper;
• shape raw/normalized событий — меняется contracts, затем воркер и backend;
• GraphQL-модель — сначала обновляется contracts, затем npp-backend и npp-web;
• логика отчётов или аналитики — меняется npp-backend, а UI только подхватывает новый срез.

Технический follow-up для новых участников

1. Поднять стек по быстрому старту.
2. Прочитать аналитический контур, чтобы не путать operational и business-слой.
3. Разобрать карту репозиториев и ownership каждого сервиса.