slm-design/public/ARCHITECTURE.md

Локальная копия канонической спецификации SLM Design. Источник: https://slm-design.gromlab.ru/ARCHITECTURE.md Не редактировать вручную в этом проекте.

SLM Design

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

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

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

• Слои — уровни организации src/, направление зависимостей и зона ответственности каждого слоя.
• Модули — границы ответственности, публичный API, типы модулей и отличие модуля от компонента.
• Сегменты — внутренние папки модуля (ui/, parts/, hooks/, types/ и другие) и правила размещения файлов.

Рекомендуемый порядок чтения: обзор → слои → модули → сегменты.

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

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

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

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

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

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

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

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

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

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

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

Явное разделение каркаса и контента

Каркас группы маршрутов (layouts/) и контент конкретной страницы (screens/) — независимые слои с собственной ответственностью.

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

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

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

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

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

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

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

Принципы

• Домен — единое целое. Всё, что относится к домену, живёт в одном модуле.
• Колокация. Код рождается рядом с местом использования и поднимается только при необходимости.
• Зависимости однонаправлены. Импорты только сверху вниз, только через публичный API.
• Архитектура — каркас, не клетка. Правила фиксируют направление зависимостей и структуру модуля, остальное определяет команда.

Слои

Раздел описывает слои SLM: что такое слой, какие бывают, как между ними направлены зависимости и какие правила действуют на каждом.

Определение

Слой — уровень организации кода внутри src/. Каждый слой отвечает за свою область (каркас страницы, бизнес-логика, UI-кит) и задаёт правила для кода внутри: направление импортов, именование, допустимые связи между модулями.

Группы слоёв

Слои делятся на три группы:

Группа	Слои	Описание
Композиция	app, layouts, screens, widgets	Собирают интерфейс из готовых блоков: маршруты, каркасы, страницы
Ядро	business, infra, ui	Реализация продукта: бизнес-домены, техсервисы, UI-кит
Фундамент	shared	Общие ресурсы: утилиты, хелперы, стили, конфиги

Направление зависимостей

Любой импорт между модулями — только через публичный API.

app → [ layouts | screens ] → widgets → business → infra → ui → shared

• layouts и screens — параллельные слои, не импортируют друг друга
• Модули одного слоя в группе «Композиция» изолированы друг от друга
• Модули одного слоя infra и ui могут импортировать друг друга через публичный API
• Модули business — cross-domain зависимости по коду через фабрику, import type напрямую
• Импорт типов (import type) в «Ядре» разрешён в обоих направлениях

Слой App

Точка входа приложения. Отвечает за запуск, роутинг и композицию маршрутов из layout и screen.

В отличие от остальных слоёв, app/ не содержит модулей SLM. Здесь живут только инфраструктурные файлы, которые не могут быть никаким другим слоем: файлы фреймворка роутинга, точка запуска и код инициализации.

Требования

• Не содержит модулей SLM — только файлы фреймворка, роутинг, инициализация
• Содержит: файлы маршрутов, bootstrap, обработку ошибок верхнего уровня (404, error boundary), подключение глобальных стилей и ассетов
• Провайдеры и гарды — только подключает готовые из нижних слоёв, не реализует
• Не содержит бизнес-логику, UI-компоненты, хуки, сторы, сервисы
• Никем не импортируется

Слой Layouts

Каркас страницы: общие элементы, одинаковые для группы маршрутов (header, footer, sidebar).

src/layouts/
├── main/
├── dashboard/
└── auth/

Требования

• Содержит только модули
• Не содержит бизнес-логику
• Контекстно-зависимые блоки принимает через пропсы от app, не импортирует напрямую

Слой Screens

Контент конкретной страницы: собирает её из модулей нижних слоёв.

src/screens/
├── home/
├── products/
├── product-detail/
├── about/
└── contacts/

Когда количество страниц затрудняет навигацию — вводится группировка по разделам. Группа — папка для организации, не модуль (без index.ts).

src/screens/
├── shop/
│   ├── home/
│   ├── products/
│   ├── product-detail/
│   └── cart/
├── account/
│   ├── profile/
│   ├── settings/
│   └── order-history/
└── info/
    ├── about/
    ├── contacts/
    └── faq/

Требования

• Содержит только модули
• Не содержит бизнес-логику
• Локальные одноразовые секции живут внутри screen-модуля, не выносятся в widgets/business

Слой Widgets

Составной блок интерфейса, который компонует модули ядра, но не принадлежит конкретному бизнес-домену. Widget появляется когда блок используется в нескольких screens или layouts.

Если блок принадлежит домену — он живёт в business/{area}/, даже если переиспользуется. Если блок нужен только в одном месте — это screens/{name}/parts/ или layouts/{name}/parts/, а не widget.

src/widgets/
├── page-heading/
├── hero-section/
├── onboarding-checklist/
├── promo-banner/
└── error-boundary/

Требования

• Не принадлежит конкретному бизнес-домену. Если блок доменный — он живёт в business/
• Используется в нескольких screens или layouts

Слой Business

Бизнес-домены приложения: auth, catalog, orders, checkout, chat. Каждый домен — отдельный модуль со своими типами, логикой, UI и сервисами.

Слой входит в группу «Ядро». Импортирует infra/, ui/, shared/. Каждый бизнес-модуль создаёт публичный runtime API через фабрику в корне. Cross-domain зависимости: runtime — через аргументы фабрики, типы — напрямую через import type.

Business объединяет то, что в FSD разделено на features и entities: пользовательские сценарии и бизнес-сущности живут вместе, внутри одного домена. Внутри домена сегменты разделяют ответственность: types/ — доменная модель, hooks/ и services/ — сценарии и логика, mappers/ — трансформация данных, parts/ — составные блоки.

src/business/
├── auth/
├── catalog/
├── orders/
├── checkout/
└── chat/

Когда количество доменов затрудняет навигацию — вводится группировка по субдоменам. Группа — папка для организации, не модуль (без index.ts).

src/business/
├── commerce/
│   ├── catalog/
│   ├── cart/
│   ├── orders/
│   └── checkout/
└── communication/
    ├── chat/
    └── notifications/

Требования

• Один модуль = один бизнес-домен
• Циклические зависимости между доменами запрещены
• Публичный runtime API — через фабрику в корне модуля ({name}.factory.ts). index.ts экспортирует только фабрику и type-only экспорты
• Импорт runtime-кода между доменами — через фабрику. import type — напрямую
• Доменные типы (User, Product) живут здесь, не в shared/

Слой infra

Техсервисы приложения: theme, i18n, API-адаптеры, logger, realtime. Каждый сервис — отдельный модуль.

Слой входит в группу «Ядро». Импортирует infra/, ui/, shared/.

Отличие от shared/: infra — инфраструктура приложения (сервисы, темы, адаптеры к API), shared/ — общие ресурсы (утилиты, хелперы, стили, конфиги).

src/infra/
├── theme/
├── i18n/
├── backend-api/
├── maps-api/
├── logger/
├── feature-flags/
└── realtime/

Требования

• Один модуль = один техсервис
• Импортирует infra/, ui/, shared/

Слой UI

UI-кит без бизнес-логики: button, carousel, toast, modal.

Слой входит в группу «Ядро». Импортирует ui/ и shared/.

Компоненты строятся друг на друге: button использует icon, carousel использует button.

src/ui/
├── button/
├── input/
├── icon/
├── carousel/
├── modal/
├── toast/
├── dropdown/
├── tabs/
└── tooltip/

Когда количество компонентов затрудняет навигацию — вводится группировка на примитивы и композиции. Примитивы (button, icon, input) не импортируют композиции. Композиции (carousel, modal, dropdown) строятся на примитивах.

src/ui/
├── primitives/
│   ├── button/
│   ├── input/
│   ├── icon/
│   └── badge/
└── composites/
    ├── carousel/
    ├── modal/
    ├── dropdown/
    ├── tabs/
    └── tooltip/

Требования

• Не содержит бизнес-логику
• Импортирует только ui/ и shared/

Слой Shared

Общие ресурсы: утилиты, хелперы, стили, конфиги. Не знает о бизнес-домене.

Слой входит в группу «Фундамент» — ни о ком не знает, никого не импортирует.

Отличие от infra/: infra — инфраструктура приложения (сервисы, темы, адаптеры к API), shared/ — общие ресурсы (утилиты, хелперы, стили, конфиги).

Отличие от ui/: UI-компоненты (button, carousel, modal) живут в слое ui/, а не здесь.

src/shared/
├── lib/
├── types/
├── styles/
└── sprites/

Требования

• Не имеет runtime-состояния

Модули

Раздел описывает модуль как границу ответственности в SLM: что считается модулем, что такое компонент внутри модуля и как модуль взаимодействует с остальным кодом.

Определение

Модуль — минимальная архитектурная единица SLM. Он живёт на одном из слоёв, владеет конкретной областью ответственности и предоставляет наружу только публичный API.

Модуль может содержать всё, что нужно этой области: компоненты, вложенные модули, хуки, сторы, сервисы, типы, стили, конфиги и утилиты. Набор сегментов не фиксирован — модуль включает только то, что реально нужно.

Модуль не обязан быть UI-блоком. Это может быть страница, виджет, бизнес-домен, инфраструктурный сервис или UI-kit сущность.

Главная граница модуля — не папка, а ответственность.

Компонент

Компонент — презентационная единица модуля, которая находится только в ui/ своего родительского модуля и отвечает за отображение части интерфейса.

Компонент не является архитектурной единицей: он не владеет сценарием, зависимостями, данными или внутренней структурой. Он работает только внутри границы родительского модуля.

Компонент отображает. Модуль организует.

Компонент не может:

• Импортировать код проекта за пределами родительского модуля.
• Владеть архитектурными зависимостями.
• Содержать любые компоненты.
• Содержать любые модули.
• Делать внешние запросы.
• Самостоятельно получать данные.
• Выбирать источник данных.
• Композировать данные.
• Вызывать сценарные хуки.
• Оркестрировать сценарий.
• Композировать модули.
• Решать, как устроен процесс.
• Содержать бизнес-логику.
• Содержать сценарную логику.

Если компоненту требуется что-то из этого списка, он перестаёт быть компонентом и должен быть оформлен как модуль.

auth/
├── ui/
│   └── logout-button/
│       ├── logout-button.tsx
│       ├── styles/
│       │   └── logout-button.module.css
│       ├── types/
│       │   └── logout-button-props.type.ts
│       └── index.ts
└── index.ts

Что считается модулем

Модулем считается папка, которая представляет самостоятельную область ответственности и имеет публичную границу.

Примеры модулей:

• screens/home/ — модуль страницы.
• widgets/page-heading/ — модуль виджета.
• business/auth/ — модуль бизнес-домена.
• infra/theme/ — модуль инфраструктурного сервиса.
• ui/button/ — модуль UI-kit сущности.
• screens/home/parts/hero-section/ — вложенный модуль страницы.

Не считаются модулями:

• ui/, parts/, hooks/, types/, styles/, config/ — это сегменты.
• screens/shop/, business/commerce/ — это группы, если в них нет index.ts.
• screens/home/ui/user-card/ — это компонент, если он находится в ui/ и соблюдает ограничения компонента.

Типы модулей

Тип модуля определяет обязательный корневой файл и стартовую структуру.

UI-модуль

Модуль строится вокруг основного UI-компонента и обязан иметь основной .tsx файл в корне:

header/
├── header.tsx
└── index.ts

ui/ внутри такого модуля используется только для компонентов, которые помогают корневому .tsx файлу.

Бизнес-модуль

Бизнес-модуль — модуль, который строится вокруг публичного runtime API.

Бизнес-модуль обязан иметь фабрику в корне:

auth/
├── auth.factory.ts
├── index.ts
└── types/

Фабрика возвращает публичный runtime API модуля.

Инфраструктурный модуль

Инфраструктурный модуль — модуль, который строится вокруг технического сервиса или интеграции.

Инфраструктурный модуль не обязан иметь фиксированный корневой файл. Его структура определяется природой сервиса.

theme/
├── index.ts
├── config/
├── hooks/
├── styles/
└── ui/

backend-api/
├── backend-api.client.ts
├── config/
├── types/
└── index.ts

Структура

Модуль состоит из сегментов. Ни один сегмент не обязателен — модуль включает только те части, которые нужны его ответственности.

{module-name}/
├── {module-name}.factory.ts     # фабрика (для business-модулей)
├── {module-name}.tsx            # корневой файл модуля (опционален)
├── ui/                          # компоненты модуля
├── parts/                       # вложенные модули
├── hooks/                       # хуки
├── stores/                      # сторы состояния
├── services/                    # внешние источники данных
├── mappers/                     # трансформация данных между форматами
├── types/                       # типы
├── styles/                      # стили
├── lib/                         # утилиты модуля
├── config/                      # константы и конфигурация
└── index.ts                     # публичный API

Подробное описание сегментов — в разделе Сегменты.

Публичный API

Внешний код импортирует модуль только через публичный API.

// Хорошо
import { customerFactory } from '@/business/customer'
import type { Customer } from '@/business/customer'

// Плохо
import { validateToken } from '@/business/auth/lib/tokens'

index.ts модуля не обязан экспортировать всё содержимое. Он экспортирует только то, что действительно нужно снаружи.

Внутренние сегменты модуля остаются деталями реализации.

Business-модуль экспортирует из index.ts только фабрику и type-only экспорты. Хуки, компоненты, сервисы, мапперы и утилиты напрямую из index.ts не экспортируются — они доступны через API, который возвращает фабрика.

// business/customer/index.ts
export { customerFactory } from './customer.factory'

export type { Customer } from './types/customer.type'
export type { CustomerApi } from './types/customer-api.type'
export type { CustomerDeps } from './types/customer-deps.type'
export type { CustomerFactory } from './types/customer-factory.type'

Фабрика

Business-модуль всегда экспортирует фабрику. Фабрика лежит в корне модуля ({name}.factory.ts), типизируется через {Name}Factory и возвращает публичный runtime API модуля.

Всё, что нужно внешнему коду в runtime, должно быть частью API, который возвращает фабрика.

Модуль без cross-domain зависимостей экспортирует фабрику без аргументов. Модуль с зависимостями — фабрику, принимающую зависимости доменными именами. Типы всегда экспортируются напрямую через export type — import type не является runtime-зависимостью.

Компоновка фабрик происходит на уровне модуля-потребителя: screen, layout, widget или любой другой модуль группы «Композиция».

Структура business-модуля

business/customer/
├── customer.factory.ts
├── index.ts
└── types/
    ├── customer.type.ts
    ├── customer-api.type.ts
    ├── customer-deps.type.ts
    └── customer-factory.type.ts

Типы

// business/customer/types/customer-api.type.ts
export type CustomerApi = {
  useCustomer: () => Customer
  CustomerCard: (props: CustomerCardProps) => ReactNode
}

// business/order/types/order-deps.type.ts
export type OrderDeps = {
  customer: Pick<CustomerApi, 'useCustomer'>
}

// business/order/types/order-factory.type.ts
export type OrderFactory = (deps: OrderDeps) => OrderApi

Фабрика без зависимостей

// business/customer/customer.factory.ts
import type { CustomerFactory } from './types/customer-factory.type'

export const customerFactory: CustomerFactory = () => {
  return {
    useCustomer,
    CustomerCard,
  }
}

Фабрика с зависимостями

// business/order/order.factory.ts
import type { OrderFactory } from './types/order-factory.type'

export const orderFactory: OrderFactory = (deps) => {
  return {
    useOrder,
    OrderCard,
  }
}

Композиция на уровне screen

// screens/home/home.screen.tsx
import { customerFactory } from '@/business/customer'
import { orderFactory } from '@/business/order'

const customer = customerFactory()
const order = orderFactory({ customer })

const { useOrder, OrderCard } = order

export const HomeScreen = () => {
  const currentOrder = useOrder()

  return <OrderCard order={currentOrder} />
}

Жизненный цикл

Модуль рождается на самом низком уровне использования и поднимается выше только при реальной потребности.

• Нужен на одной странице → screens/{name}/parts/
• Появился в 2+ местах → поднимается по природе:
  • абстрактный UI → ui/
  • блок с данными/логикой → widgets/
  • представление бизнес-домена → business/{area}/parts/

Подъём — обычный рефакторинг в рамках задачи, а не отдельная активность.

Сегменты

Раздел описывает сегменты SLM: что такое сегмент, какие бывают и что в каждом из них лежит.

Определение

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

Обзор

Сегмент	Содержимое
ui/	Презентационные компоненты родительского модуля
parts/	Вложенные модули со своими сегментами
hooks/	React-хуки
stores/	Сторы состояния
services/	Работа с внешними источниками данных
mappers/	Трансформация данных между форматами
types/	TypeScript-типы и интерфейсы
styles/	Стили
lib/	Утилиты и хелперы модуля
config/	Константы и конфигурация

Сегмент ui/

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

Компонент в ui/:

• Находится в собственной папке.
• Может содержать только {name}.tsx, index.ts, styles/, types/.
• Не содержит любые компоненты.
• Не содержит любые модули.
• Не импортирует код проекта за пределами родительского модуля.
• Не делает внешние запросы.
• Не вызывает сценарные хуки.
• Не получает данные самостоятельно, не выбирает источник данных и не композирует данные.
• Не содержит бизнес-логику или сценарную логику.

Если UI-сущности нужно что-то за пределами этих ограничений, она должна быть оформлена как модуль. Полная граница описана в разделе Компонент.

Корневой файл модуля в ui/ не размещается. Он лежит в корне модуля: {module-name}.tsx.

user/
├── ui/
│   ├── user-avatar/
│   │   ├── user-avatar.tsx
│   │   ├── styles/
│   │   │   └── user-avatar.module.css
│   │   ├── types/
│   │   │   └── user-avatar-props.type.ts
│   │   └── index.ts
│   └── user-status/
│       ├── user-status.tsx
│       └── index.ts
├── types/
├── hooks/
├── user.tsx
└── index.ts

Если UI-сущности нужна внутренняя декомпозиция, сценарная логика, получение данных или собственные архитектурные зависимости — это уже не компонент в ui/, а модуль в parts/.

Сегмент parts/

Вложенные модули со своими сегментами. parts/ содержит только модули: каждый элемент parts/ — папка полноценного модуля с собственным публичным API. Отдельные .tsx, стили, хуки или произвольные файлы в parts/ не размещаются.

home/
├── parts/
│   ├── hero-section/
│   │   ├── hero-section.tsx
│   │   ├── styles/
│   │   ├── parts/
│   │   │   └── top-banner/
│   │   │       ├── top-banner.tsx
│   │   │       └── index.ts
│   │   └── index.ts
│   └── features-section/
│       ├── features-section.tsx
│       ├── hooks/
│       └── index.ts
├── home.screen.tsx
└── index.ts

Отличие от ui/: элемент parts/ — модульная папка со своими сегментами. Элемент ui/ — компонент родительского модуля без собственной архитектурной ответственности.

Вложенность parts/ инкапсулирует область разработки горизонтально: каждый разработчик работает в своём parts/-модуле, не затрагивая чужие. Это снижает конфликты при параллельной разработке.

Если вложенный модуль обрастает своими parts/ — это сигнал, что он достаточно самостоятельный для подъёма на уровень выше.

Сегмент hooks/

React-хуки модуля. Инкапсулируют логику, состояние, подписки, побочные эффекты.

hooks/
├── use-auth.hook.ts
├── use-session.hook.ts
└── use-permissions.hook.ts

Сегмент stores/

Сторы состояния модуля. Конкретная реализация зависит от выбранного стейт-менеджера (Zustand, MobX, Redux и т.д.).

stores/
├── auth.store.ts
└── session.store.ts

Сегмент services/

Работа с внешними источниками данных: API-вызовы, запросы, подписки.

services/
├── auth.service.ts
└── token.service.ts

Сегмент mappers/

Функции трансформации данных из одного формата в другой: DTO в доменный тип, доменный тип в DTO, доменный тип в ViewModel.

mappers/
├── map-user.ts
├── map-product.ts
└── map-order-to-dto.ts

Сегмент types/

TypeScript-типы и интерфейсы модуля. Доменные типы, DTO, пропсы компонентов.

types/
├── user.type.ts
└── session.type.ts

Сегмент styles/

Стили модуля. Формат зависит от выбранного подхода (CSS Modules, SCSS, CSS-in-JS и т.д.).

styles/
├── auth.module.css
└── login-form.module.css

Сегмент lib/

Утилиты и хелперы, специфичные для модуля. Чистые функции без побочных эффектов.

lib/
├── validate-email.ts
└── format-phone.ts

Отличие от shared/lib/: здесь лежат утилиты, нужные только этому модулю. Общие утилиты — в shared/lib/.

Сегмент config/

Константы и конфигурация модуля: маршруты, лимиты, дефолтные значения.

config/
├── routes.ts
└── constants.ts