Карта репозиториев

Этот раздел нужен как техническая карта ownership по всей экосистеме NPPWEB: что за что отвечает, от чего зависит и куда идти при изменениях.

Общая карта

Репозиторий	Технологии	Основная ответственность
infra	Docker Compose, Make	запуск и deploy-контур
contracts	GraphQL SDL, JSON Schema	source of truth по API и событиям
scrape-helper	Node.js, Pino, Undici	сбор данных, source runs, артефакты
processing-worker	Node.js worker	нормализация, ingest, retry/DLQ
npp-backend	NestJS, GraphQL, Prisma	доменная модель, auth, отчёты, аналитика
npp-web	Nuxt 3, Tailwind, Apollo	пользовательский кабинет и аналитические экраны

Как читать систему

Если смотреть сверху вниз, поток такой:

1. infra поднимает среду.
2. scrape-helper собирает данные и публикует raw-события.
3. processing-worker приводит их к общей форме.
4. npp-backend хранит доменные сущности и агрегаты.
5. npp-web показывает результат через GraphQL.
6. contracts связывает несколько репозиториев едиными схемами.

Какие зависимости самые важные

Репозиторий	От чего зависит	Что отдаёт другим
infra	Dockerfiles, env, compose-конфигурация	единый runtime-контур
contracts	согласованные изменения API и событий	стабильные контракты
scrape-helper	RabbitMQ, MinIO, proxy, contracts	source.raw.v1, артефакты, SourceRun статусы
processing-worker	RabbitMQ, backend ingest, contracts	normalized ingest и source.normalized.v1
npp-backend	Postgres, Redis, ingest, runtime scraper	GraphQL API, отчёты, analytics summary
npp-web	GraphQL API, Nuxt runtime	интерфейс платформы

Куда идти при изменениях

Изменение	С чего начинать
новый внешний источник	scrape-helper
изменился HTML/API площадки	scrape-helper
новое поле в raw/normalized payload	contracts, потом worker/backend
новая доменная сущность или ingest-поток	npp-backend
новый аналитический показатель	npp-backend, затем npp-web
новый экран или представление	npp-web
новый env или runtime-service	infra
изменение GraphQL	contracts + npp-backend + npp-web

Как не запутаться в ownership

scrape-helper и processing-worker — это не одно и то же

• scrape-helper знает внешний источник;
• processing-worker знает нормализованный смысл данных;
• npp-backend знает бизнес-модель;
• npp-web знает пользовательский сценарий.

Если смешать эти уровни, будет трудно поддерживать платформу при любом изменении площадки.

contracts — это не “вспомогательный” репозиторий

Он важен тем, что:

• не даёт backend и frontend разъехаться по GraphQL;
• фиксирует форму raw и normalized событий;
• помогает ревьюить cross-repo изменения как осознанную эволюцию контракта.

infra — это часть продукта, а не только dev tooling

Потому что именно там живут:

• реальные env-дефолты;
• compose-зависимости;
• proxy-контур;
• условия устойчивого старта сервисов.

Во многих инцидентах причина находится именно в infra, а не в приложении.

Рекомендуемый порядок изучения

Если вы новый участник проекта, удобнее идти так:

1. Быстрый старт
2. Архитектура
3. Аналитический контур
4. infra
5. scrape-helper
6. processing-worker
7. npp-backend
8. npp-web
9. contracts

Типичные ошибки новых участников

• менять GraphQL только на frontend или только на backend;
• считать, что успешный SourceRun гарантирует наполненную аналитику;
• чинить backend, когда фактическая проблема в proxy или внешней площадке;
• пытаться записывать бизнес-сущности прямо из парсера;
• не обновлять docs после важных архитектурных решений.

Что читать дальше

• infra
• scrape-helper
• processing-worker
• npp-backend
• npp-web