Архитектура

Архитектура построена на FSD (Feature‑Sliced Design) и строгих границах модулей. Цель — разделить ответственность, упростить сопровождение и контроль зависимостей.

Принципы

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

Слои (FSD)

• app — инициализация приложения: провайдеры, глобальные стили. В Next.js эта же папка app/ дополнительно содержит системные файлы роутинга (layout.tsx, page.tsx).
• screens — UI-компоненты страниц. Каждый экран — отдельный компонент, который собирает виджеты и фичи конкретной страницы. Роутинг только использует эти компоненты — он не является частью слоя screens. В Next.js файлы page.tsx остаются тонкими: импортируют экран и рендерят его.
• layouts — каркас и шаблоны страниц.
• widgets — крупные блоки интерфейса, собирающие несколько сценариев.
• features — отдельные пользовательские действия и сценарии.
• entities — бизнес-сущности и их модель.
• shared — переиспользуемая инфраструктура, утилиты и базовые UI‑компоненты.

Модули (FSD)

• Модуль — это отдельная папка в слоях screens, layouts, widgets, features, entities, которая реализует один сценарий/блок. В корне модуля лежит главный файл (*.screen.tsx, *.layout.tsx, *.widget.tsx, *.feature.tsx, *.entity.tsx) и публичный API (index.ts).
• Внутри модуля используются подпапки (по необходимости):
  • ui/ — дочерние UI‑компоненты модуля.
  • model/ — состояние и бизнес‑логика модуля.
  • styles/ — локальные стили модуля.
  • helpers/ — локальные хелперы.
  • lib/ — утилиты модуля.
  • api/ — API‑вызовы модуля.

Правила зависимостей

• Допустимые импорты идут сверху вниз: app → screens → layouts → widgets → features → entities → shared.
• Импорты между слоями — через публичный API.
• Внутри одного слоя — относительные импорты.

Публичный API модулей

• Каждый модуль экспортирует наружу только то, что нужно другим слоям.
• Внешние импорты идут только через index‑файл модуля.
• Внутренние файлы не импортируются напрямую извне.

Границы ответственности

• Бизнес‑логика не размещается в UI‑компонентах.
• UI‑компоненты должны быть максимально простыми и предсказуемыми.
• Связь между независимыми сценариями поднимается на уровень выше.

Типовые ошибки

• Импорт из более высокого слоя в более низкий.
• Смешивание логики нескольких слоёв в одном модуле.
• Прямые импорты внутренних файлов, минуя публичный API.