slm-design/docs/canons/index.md

title, description

title	description
SLM Design	Назначение архитектуры, ключевые принципы и карта разделов документации

Основы SLM Design

Scoped Layered Module Design — модульная архитектура фронтенд-приложений. Код организован по слоям ответственности, а модуль содержит всё, что ему нужно: компоненты, хуки, сторы, типы, стили.

Рабочий алгоритм

1. Заполни архитектурную карточку из процесса принятия решения: роль, владелец, данные, runtime-capabilities, место, public API, lifecycle и проверки.
2. Сначала выбери слой ответственности, затем module scope, затем segments и только после этого конкретные файлы.
3. Для product data и domain state примени runtime-границу business.
4. Выбирай минимальное корректное место и не создавай общий provider, store, package или business-контракт «на будущее».
5. После реализации пройди архитектурную проверку. Задача не завершена без обязательных business и assembly tests.

Дополнительные примеры

Каноны ниже достаточны для базового архитектурного решения. Если нужен подробный пример реализации, открой конкретный файл:

• Композиция через Provider — page-level provider, store и business composition.
• Структуры compositions — допустимые структуры слоя compositions.
• Business composition — runtime-сборка business-фабрик в compositions/business/{domain}.
• Тестирование business-модулей — factory-level тесты и тесты сборки.

Разделы спецификации

Спецификация SLM Design состоит из нескольких связанных разделов. Этот обзор даёт общий контекст, а детальные правила описаны дальше:

• Слои — уровни организации src/, направление зависимостей и зона ответственности каждого слоя.
• Модули — границы ответственности, публичный API, типы модулей и отличие модуля от компонента.
• Атлас файлов SLM — root files, segments, структуры всех типов modules, public API и tests.
• Business-фабрика — контракт business-модуля, logic API, deps, доменные ошибки и сборка фабрик.
• Runtime-граница business — capabilities фабрики, adapters, hooks, stores и безусловные domain errors.
• Сегменты — внутренние папки модуля (ui/, parts/, hooks/, types/ и другие) и правила размещения файлов.
• Монорепозитории — применение SLM в apps/ и packages/, правила выноса общих слоёв и ограничения для business/compositions.
• Архитектурная проверка — блокирующие gates создания, рефакторинга и ревью.

Рекомендуемый порядок чтения: процесс решения → runtime-граница business → архитектурная проверка → атлас или подробности только нужной ветки.

Преимущества

Единый слой композиции

Страницы, маршруты и крупные продуктовые части интерфейса собираются в compositions. Слой не навязывает жёсткую структуру: команда может использовать pages/layouts/screens/widgets или другую организацию под свой фреймворк и продукт.

Вертикальная организация домена

Бизнес-домен не разбивается по техническим слоям — сценарии, сущности, типы, hooks, services и mappers живут в одном модуле. Это сокращает время навигации и упрощает сопровождение: доменная логика локализована.

Dependency Injection без фреймворков

Runtime-зависимости business-модуля реализуются через фабрики — модуль декларирует что ему нужно, а composition-сборка предоставляет зависимости. Домены изолированы от SDK, storage и backend-клиентов без DI-контейнеров и шин событий.

Разделение ответственности без перегрузки слоёв

Композиция приложения (compositions/), сервисы приложения (infra/), UI-кит (ui/) и общие ресурсы (shared/) — разные слои с разной природой. Ни один слой не превращается в свалку разнородного кода.

Графовая композиция там, где она нужна

Внутри compositions допускается граф импортов через публичный API. Это позволяет page-level store, provider или сборку business-фабрик использовать одновременно в layout, screen и widget, не перенося продуктовый runtime-state в infra или shared.

Горизонтальная инкапсуляция

Вложенные модули (parts/) и публичные API позволяют нескольким разработчикам работать над одной областью приложения параллельно, не затрагивая код друг друга.

Колокация по умолчанию

Код начинает жизнь рядом с местом использования и поднимается в общие слои только при реальной потребности. Глобальные слои не засоряются преждевременными абстракциями.

Масштабирование через группировку

При росте проекта слои не теряют структуру — модули группируются по естественным признакам: композиции по страницам и маршрутам, бизнес-домены по субдоменам, UI-компоненты по уровню абстракции.

Адаптация к монорепозиториям

SLM применяется внутри каждого приложения, а packages/* используются только для общего кода из слоёв ui, infra и shared. compositions и бизнес-домены остаются внутри приложений, чтобы не размывать продуктовые границы.

Происхождение

SLM Design вырос на основе:

• Feature-Sliced Design — слоистая структура, публичный API модуля, направление зависимостей
• Vertical Slice Architecture — модуль как вертикальный срез, содержащий всё необходимое
• Screaming Architecture — структура проекта «кричит» о назначении: открыл business/auth — видишь авторизацию
• Colocation Principle — код живёт рядом с местом использования

Пример структуры проекта

src/
├── app/
│
├── compositions/
│   ├── business/
│   │   ├── auth/
│   │   └── user/
│   ├── pages/
│   │   ├── home/
│   │   ├── profile/
│   │   └── product-detail/
│   ├── layouts/
│   │   ├── main/
│   │   └── dashboard/
│   ├── screens/
│   │   ├── home/
│   │   └── profile/
│   └── widgets/
│       ├── page-heading/
│       └── promo-banner/
│
├── business/
│   ├── auth/
│   ├── catalog/
│   ├── orders/
│   └── chat/
│
├── infra/
│   ├── theme/
│   ├── i18n/
│   ├── backend-api/
│   └── logger/
│
├── ui/
│   ├── button/
│   ├── input/
│   ├── modal/
│   ├── toast/
│   └── dropdown/
│
└── shared/
    ├── lib/
    ├── types/
    └── styles/

Принципы

• Композиция — отдельный слой. Страницы, маршруты и крупные продуктовые части интерфейса собираются в compositions.
• Структура композиции свободна. Команда сама выбирает организацию внутри compositions; базовая рекомендация — pages/layouts/screens/widgets.
• Домен — единое целое. Доменная модель, сценарии, типы, services и mappers живут в одном business-модуле. Concrete data/state/query hooks передаются фабрике через adapters.
• Колокация. Код рождается рядом с местом использования и поднимается только при необходимости.
• Зависимости однонаправлены за пределами compositions. app подключает compositions; compositions связывает business, infra, ui и shared; business вызывает concrete runtime-возможности только через переданные фабрике deps.
• Product data проходит через business. Page, layout, screen и widget не обращаются к product source напрямую.
• Ошибки принадлежат домену. Из business API выходят только собственные domain errors со стабильным code.
• Внутри compositions допустим граф. Composition modules могут импортировать друг друга через public API.
• Архитектура — каркас, не клетка. Правила фиксируют границы ответственности и public API, а внутреннюю форму композиции определяет команда.