marketplaces/docs/platform/01-architecture.md

01. Архитектура платформы

Назначение

Документ определяет архитектурную модель многоарендной платформы маркетплейсов и обязательные границы между конфигурацией, frontend-runtime и backend-данными.

Поведение системы

• Платформа использует единую frontend-кодовую базу для всех tenants.
• При старте приложение определяет tenant по домену.
• Затем загружается bootstrap-конфигурация.
• На основе конфигурации рендерятся страницы, секции и виджеты.
• Доменный контент (товары, категории, остатки) подгружается через backend API.

Архитектурные слои

1. Tenant Resolution Layer: определение tenant из host.
2. Bootstrap Layer: загрузка конфигурации UI и маршрутов.
3. Section/Layout Engine: построение структуры страницы.
4. Widget Engine: отрисовка и наполнение reusable виджетов.
5. Domain Data Layer: доступ к API продуктов и категорий.

Обязательные JSON-секции

• tenant
• layout
• pages
• sections
• widgets
• widgetRegistry
• theme
• apiEndpoints
• footer
• staticPages

Опциональные JSON-секции

• featureFlags
• localization
• seo
• permissions
• integrations

Строгие правила

• Запрещено смешивать layout-логику и data-fetch в виджетах.
• Запрещено tenant-specific ветвление в компонентах frontend.
• Backend может отдавать HTML-контент только для статических страниц (about/privacy/terms) через контролируемый контракт.
• Такой контент рендерится только через безопасную sanitization-цепочку.
• Запрещено добавлять новые обязательные поля без обновления schemaVersion.

Пример архитектурного bootstrap-фрагмента

{
  "tenant": {
    "id": "tenant-novo",
    "host": "novo.marketplace.com"
  },
  "apiEndpoints": {
    "catalog": { "baseUrl": "https://api.marketplace.com" }
  },
  "pages": [
    {
      "id": "home",
      "sections": [
        {
          "id": "hero-1",
          "type": "hero",
          "widgets": [
            { "id": "w-hero", "type": "hero", "dataSource": { "kind": "static" } }
          ]
        }
      ]
    }
  ]
}

Ответственность Frontend

• Следовать слоям архитектуры без cross-layer обходов.
• Выполнять fail-safe рендер при частично валидной конфигурации.
• Логировать нарушения контрактов конфигурации.

Ответственность Backend

• Отдавать данные строго по контракту API.
• Гарантировать tenant-aware ответы.
• Поддерживать прогнозируемую схему и документацию изменений.