slm-design/README.md

# SLM Design

**Scoped Layered Module Design (SLM)** - архитектурная модель для организации кода внутри фронтенд-приложения. Она описывает владельцев поведения, роли слоёв, границы модулей, публичные API и допустимые зависимости.

Цель SLM - сделать архитектурные решения наблюдаемыми в структуре проекта: понимать, какой модуль отвечает за результат, что доступно его потребителям и как изменение повлияет на остальное приложение.

[Документация](https://gromlab-ru.github.io/slm-design/) | [Пример React-приложения](./examples/react-vite/)

## AI skill

```bash
npx skills add gromlab-ru/slm-design
```

Или [скачать `slm-design.zip`](https://gromlab-ru.github.io/slm-design/downloads/slm-design.zip).

## О чём SLM

SLM отвечает на три основных вопроса:

1. Какой модуль владеет конкретным результатом или поведением?
2. Какие возможности модуль открывает внешним потребителям?
3. От каких других модулей он может зависеть?

Базовый принцип модели: **у каждой самостоятельной ответственности есть ровно один модуль-владелец**.

Модуль определяет публичный API ответственности, её зависимости, модели и правила, состояние, жизненный цикл и внутреннюю реализацию. Компонент, Provider, hook, store или service остаются механизмами реализации и не становятся отдельными архитектурными владельцами только из-за своей технической роли.

SLM применяется внутри `SLM root` - границы структурной архитектуры одного приложения. Конкретный проект сам сопоставляет свои пути с сущностями SLM.

## Структурная модель

```text
SLM root
└── слой
    ├── модуль
    │   ├── публичные фасеты
    │   ├── сегменты
    │   └── вложенные модули
    └── группа
        └── модули
```

| Сущность | Назначение |
|---|---|
| `SLM root` | Ограничивает область архитектуры одним приложением |
| Слой | Классифицирует код по архитектурной роли и ограничивает направления зависимостей |
| Модуль | Владеет одной самостоятельной ответственностью и её публичным API |
| Домен | Специализирует модуль для предметной ответственности и доменных сценариев |
| Группа | Навигационно классифицирует модули, но не владеет кодом или API |
| Сегмент | Организует внутренний код одного модуля без собственной ответственности |
| Вложенный модуль | Владеет отдельной подответственностью внутри родительского модуля |

Слой, группа и сегмент не являются владельцами. По умолчанию код внутри `SLM root` принадлежит ближайшему модулю; исключениями остаются точки входа `app` и небольшие детерминированные ресурсы `shared`.

## Слои

SLM определяет шесть архитектурных ролей:

| Слой | Роль |
|---|---|
| `app` | Запуск приложения, маршруты, преобразование внешних входов и подключение готовых публичных API |
| `compositions` | Представление и связывание готовых возможностей в страницы, макеты, экраны и виджеты |
| `domains` | Предметные ответственности и сценарии: модели, правила, состояние, операции с данными и доменный UI |
| `infra` | Технические сервисы без собственной предметной модели |
| `ui` | Универсальные интерфейсные модули без знания о конкретном продукте или странице |
| `shared` | Детерминированный фундамент без продуктового знания, ввода-вывода и изменяемого состояния |

Проект создаёт только те слои, для которых появился соответствующий код. Пустые слои и обязательное прохождение через каждый промежуточный уровень не требуются.

## Ключевые свойства

- **Один владелец ответственности.** Контракт, состояние, зависимости и внутренняя реализация связного результата принадлежат одному модулю.
- **Закрытая модульная граница.** Внешний код использует модуль только через его публичные фасеты. Глубокие импорты во внутренние файлы запрещены.
- **Фасеты сред выполнения.** Обязательный `index` содержит универсальный API; `client`, `browser` и `server` добавляются только при необходимости.
- **Вертикальные домены.** Домен владеет сценарием целиком: предметным контрактом, правилами, состоянием, ошибками, доменным UI и адаптацией источников данных.
- **Независимость от DTO.** Внешние request, response и error types остаются внутри интеграционной границы и не становятся публичной моделью домена.
- **Ацикличный модульный граф.** Межмодульные импорты проходят через публичный API, учитывают направление слоёв и не образуют циклов.
- **Рост по ответственности.** Сегменты организуют внутренний код, а новый или вложенный модуль появляется только для самостоятельной ответственности.
- **Владение состоянием и ресурсами.** Модуль определяет источник истины, область жизни, число экземпляров и очистку долгоживущих ресурсов.

## Проверка архитектуры

SLM разделяет смысловые и структурные решения.

- На архитектурном ревью проверяются ответственность, единственный владелец, роль слоя, состав публичного API, доменный контракт, состояние и жизненный цикл.
- Автоматически можно проверять направления между слоями, доступ через публичные фасеты, отсутствие глубоких импортов и циклов в модульном графе.

Блокирующие правила собраны в едином реестре и имеют стабильные коды. Рекомендации и примеры объясняют модель, но не подменяют нормативные требования.

## Что SLM не определяет

SLM не требует конкретного фреймворка, state manager, способа получения данных или потока управления. Модель не задаёт фиксированные имена сегментов, полный файловый стайлгайд и правила организации монорепозитория.

Эти решения остаются за проектом. SLM определяет только архитектурный смысл владельцев, границ и зависимостей внутри одного приложения.

## Документация и пример

- [Обзор архитектурной модели](https://gromlab-ru.github.io/slm-design/architecture/)
- [Слои](https://gromlab-ru.github.io/slm-design/architecture/layers)
- [Модули и публичный API](https://gromlab-ru.github.io/slm-design/architecture/modules)
- [Домены и граница внешних данных](https://gromlab-ru.github.io/slm-design/architecture/domains)
- [Зависимости и модульный граф](https://gromlab-ru.github.io/slm-design/architecture/dependencies)
- [Терминология](https://gromlab-ru.github.io/slm-design/reference/terminology)
- [Реестр правил](https://gromlab-ru.github.io/slm-design/rules/registry)
- [Проверка архитектуры](https://gromlab-ru.github.io/slm-design/reference/validation)
- [Пример React + Vite приложения](./examples/react-vite/)

<details>
<summary>Разработка репозитория</summary>

Требуется Node.js 20 или новее.

```bash
npm ci
npm run build:skill
npm run check
```

Локальный запуск документации:

```bash
npm run docs:dev
```

Документация находится в `docs/`, исходник skill - в `src-skills/slm-design/`. Собранный каталог `skills/slm-design/` не редактируется вручную.

</details>