Перейти к основному содержимому

Архитектура Pin

Контекст​

Pin строится как multi-tenant enterprise-платформа для учета, каталогирования, управления товарами, остатками, объектами и персоналом. Архитектура должна быть пригодна для нескольких прикладных доменов, сохраняя единый стек, повторяемые building blocks и строгие operational standards.

Высокоуровневая Схема​

Высокоуровневая runtime-диаграмма вынесена в Runtime Context Diagram.

Runtime Слои​

  • Gateway: единая входная точка, маршрутизация, authentication forwarding, correlation, rate limiting и tenant resolution.
  • API: административные и системные операции с явными политиками доступа.
  • External Callback API: отдельный контур для входящих вызовов внешних систем с усиленными security controls.
  • Internal API: синхронные межсервисные запросы внутри private network.
  • Background: consumers, schedulers, reconciliation, projection maintenance, async orchestration.
  • Migrator: миграции схем, индексов, справочников и связанных инфраструктурных объектов.

Ключевые Архитектурные Принципы​

  • сервис владеет только своим состоянием, схемой, миграциями и контрактами;
  • business logic не живет в controllers, EF configurations, HTTP clients или UI components;
  • любой mutation flow описывается transaction boundary, side effects, audit и observability;
  • read models, search indexes и analytics stores не являются source of truth;
  • cross-service consistency достигается через events, compensation и reconciliation;
  • общая инфраструктурная логика выносится в src/shared/*, src/building-blocks/* и src/contracts/*.

CQRS В Сервисах​

Каждый backend service использует CQRS:

  • HTTP actions и callbacks маппят запрос в MediatR Command или Query;
  • Command меняет owned state, пишет audit/idempotency/outbox в одной локальной транзакции;
  • Query читает source of truth или документированный read model и указывает freshness SLA;
  • consumers работают через inbox/idempotency и не допускают повторного изменения состояния;
  • distributed transactions не применяются без отдельного ADR.

Данные​

  • PostgreSQL: operational source of truth.
  • ClickHouse: аналитические факты, агрегаты, dashboards и отчеты.
  • Elasticsearch: поисковые projections.
  • Redis: cache, locks, throttling, short-lived coordination state, realtime backplane.
  • S3-compatible storage: документы, вложения, экспортные файлы и медиа-артефакты.

Подробности описаны в:

Multi-Tenant Модель​

  • TenantId является обязательной границей изоляции.
  • При необходимости используются дополнительные scope identifiers: OrganizationUnitId, FacilityId, DepartmentId, WorkplaceId.
  • Shared reference data допускается только как явно документированный общий контур.
  • Global operators и tenant-scoped operators имеют разные политики доступа и audit expectations.

Надежность И Эксплуатация​

  • critical operations должны быть идемпотентными;
  • inbox/outbox обязателен для надежного event-driven взаимодействия;
  • reconciliation является частью дизайна, а не аварийной мерой;
  • feature flags, rollout, dashboards, alerts и runbooks проектируются вместе с поведением;
  • архитектурные тесты и quality gates контролируют соблюдение зависимостей и стандартов.

Архитектурные Ограничения​

  • нет cross-service imports бизнес-кода;
  • нет cross-service foreign keys;
  • нет неявных generic payloads без схемы;
  • нет чтения privileged scope из недоверенных клиентских полей;
  • нет скрытых side effects вне documentable runtime boundaries;
  • нет прямого редактирования финансовых и учетных итогов без документированной компенсирующей процедуры.

Обратные ссылки​

Автоссылки: где используется этот документ.

Связанные Документы​