docs

docs/platform/01-architecture.md

@@ -0,0 +1,81 @@
+# 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-фрагмента
+```json
+{
+  "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 ответы.
+- Поддерживать прогнозируемую схему и документацию изменений.