docs: add guidance on when to create an entity by dyakubovskiy · Pull Request #898 · feature-sliced/documentation

dyakubovskiy · 2026-02-04T18:27:53Z

Background

Русский:
Добавляет практические рекомендации по выделению сущностей (entities) на этапе масштабирования проекта. Рекомендации помогают избежать распространённых ошибок при проектировании архитектуры: преждевременного выделения сущностей или, наоборот, запоздалого рефакторинга.

English:
Adds practical recommendations for extracting entities during project scaling. The guidelines help avoid common architectural pitfalls: premature entity extraction or, conversely, delayed refactoring when the codebase has already become entangled.

Changelog

Русский:

Добавлены рекомендации на русском языке о критериях выделения сущностей при масштабировании
Добавлен перевод рекомендаций на английский язык
Описаны признаки для выделения отдельной сущности: стабильность доменной области, повторное использование в разных слоях, рост сложности бизнес-логики

English:

Added Russian-language recommendations on entity extraction criteria during scaling
Provided English translation of the recommendations
Described indicators for extracting a separate entity: domain stability, reuse across layers, and growing complexity of business logic

github-actions · 2026-02-04T18:30:43Z

built with Refined Cloudflare Pages Action

⚡ Cloudflare Pages Deployment

Name	Status	Preview	Last Commit
pr-fsd	✅ Ready (View Log)	Visit Preview	`af99ee8`

i18n/en/docusaurus-plugin-content-docs/current/reference/layers.mdx

illright

The content is great, thank you! I agree with @Gaic4o that the diagram should perhaps be inserted as an image because it is unreadable when rendered by Docusaurus:

And I also think that the Reference section is not the best place to put advice. This documentation is structured by the Diataxis framework (https://diataxis.fr/), and we've been keeping advice mostly in Guides. Speaking of which, there is a guide about Excessive entities (Code smells & issues), and I have a feeling that this new section shares a lot of content with that guide, could we perhaps deduplicate and leave a link instead?

dyakubovskiy

I replaced the diagram with a Mermaid

dyakubovskiy

I replaced the diagram with a Mermaid one

i18n/en/docusaurus-plugin-content-docs/current/reference/layers.mdx

Stanislavsky69 · 2026-02-07T12:59:38Z

[RU]

Рекомендации по выявлению сущностей.

Сущность - объект предметной области, который отражает суть бизнеса. Отличительная черта сущности - его уникальность. При проектировании слоя entities в рамках FSD нужно сначала определиться с бизнесом, что есть сущность по его уникальности. Например, уникальный атрибут у заказа - номер, у товара - артикул. Иногда, есть данные, которых не хватает для однозначного определения сущности. Тогда нужно изучить структуру, которую отдает бэк и найти уникальный атрибут, например, id. Если и этого не хватает для однозначного определения сущности, то можно подумать об объекте в реально жизни. Может ли он обладать своей уникальностью?

Слой entities отражает ваши основные объекты и нуждается в проектировании на ранних этапах.

Пример:

Типичная задача.

Заголовок:
Реализовать фичу добавления пользователя в систему

Описание:

Обязательное поле ФИО
Обязательное поле Адрес проживания (город, улица, дом)
Обязательное поле год рождения
Новому пользователю назначается роль "менеджер" по умолчанию.

Первый пункт. Может ли ФИО говорить об уникальности? Нет.
Второй пункт. Может ли адрес проживания говорить об уникальности? Я бы сказал, что он может являться уникальным, но не гарантировать уникальность. Обратите внимание, что в требованиях нет индекса.
Третий пункт. Год рождения всегда не уникальный.
Четвертый пункт. У роли есть имя и набор доступов. У роли нет явных бизнес ориентированных атрибутов указывающих на ее уникальность. А раз нет, то мы
смотрим на технические атрибуты. У роли есть id и это значение инкрементное. Вывод: роль - сущность.

А что с пользователем? Если по бизнесу нет явных атрибутов указывающих на ее уникальность, а их нет, то мы смотрим на технические атрибуты. У пользователя как и у роли есть атрибут id. Вывод: пользователь - сущность.

Другой пример

Заголовок:
Реализовать возможность делится сформированным отчетом

Описание:

После создания отчета показывать уникальный ключ (хэш) в модальном окне
Добавить описание в модальное окно: "Ключ живет 30 минут. Вы можете поделится им с другим пользователем, чтобы он мог просмотреть отчет."

Второй пункт нас не интересует. Первый пункт нам говорит о том, что у отчета есть уникальный ключ, который характеризует его как сущность.

Не бойтесь общаться с бизнесом. Слой entities должен изменятся именно с изменениями в бизнесе.

Я рекомендую нарезать сущности сразу, чтобы избежать анемичной модели (https://en.wikipedia.org/wiki/Anemic_domain_model).

Важно! Это противоречит подходу с page first, потому что требует чуть больше времени и усилий.

[EN]

Recommendations for identifying entities.

An entity is a domain object that reflects the essence of a business. The distinguishing feature of an entity is its uniqueness. When designing the entities layer within the FSD framework, it is necessary to first determine the business and identify the entity based on its uniqueness. For example, the unique attribute of an order is its number, while the unique attribute of a product is its SKU. In some cases, there may be data that is insufficient to uniquely identify an entity. In such cases, it is necessary to examine the structure provided by the back-end and identify a unique attribute, such as an ID. If even this is insufficient to uniquely identify an entity, it may be necessary to consider the entity in real life and determine whether it possesses its own uniqueness.

The entities layer represents your primary objects and requires early design.

Example:

This is a typical task.

Title:
Implement the feature of adding a user to the system

Description:

Required field: Full Name
Required field: Address (city, street, house)
Required field: Year of Birth
The new user is assigned the "manager" role by default.

First point: Can the Full Name be considered unique? No.
Second point. Can the residential address speak about uniqueness? I would say that it can be unique, but it does not guarantee uniqueness. Please note that there is no index in the requirements.
Third point. The year of birth is always not unique.
Fourth point. The role has a name and a set of permissions. The role does not have any explicit business-oriented attributes that indicate its uniqueness. Since there are no such attributes, we look at the technical attributes. The role has an id, and this value is incremental. Therefore, the role is an entity.

What about the user? If there are no explicit business-oriented attributes that indicate its uniqueness, and there are none, then we look at the technical attributes. The user, like the role, has an id attribute. Therefore, the user is an entity.

Another example

Title:
Implement the ability to share a generated report

Description:

After creating a report, show the unique key (hash) in a modal window.
Add a description to the modal window: "The key is valid for 30 minutes. You can share it with another user so they can view the report."

We are not interested in the second point. The first point tells us that the report has a unique key that characterizes it as an entity.

Don't be afraid to communicate with the business. The entities layer should change with changes in the business.

I recommend slicing entities immediately to avoid an anemic model (https://en.wikipedia.org/wiki/Anemic_domain_model).

Important! This goes against the page first approach because it requires a little more time and effort.

…ced/documentation into feature/update_entities_info

illright · 2026-02-12T09:41:38Z

I still think this page should not be in the Reference, but rather, in Guides. It gives advice rather than describing definitions and base principles, as the reference should, in my opinion.

Solant

I got a read, I see good points how we can show proper usage of entities, but I am a bit concerned about a current state of this article:

it is quite large and repeats itself a lot (in regards to business-management communication)
examples are vue-specific, and it would be much better to show how to handle business logic in pure js (without react state and vue reactivity), as it might be hard for React developers to follow Vue example and vice-versa
while text states that there should be a good reason to create an entity, in the examples there are couple of entities created straight from the DTO type, without any abstraction. so it looks like examples are trying to create an entity when it is not required (just for the sake of it), which can lead to leaky abstractions
some paragraphs are repeating already existing pages from the documentation

i18n/en/docusaurus-plugin-content-docs/current/reference/when-create-entity.md

i18n/en/docusaurus-plugin-content-docs/current/reference/when-create-entity.mdx

i18n/en/docusaurus-plugin-content-docs/current/reference/when-create-entity.md

Gaic4o · 2026-02-13T07:19:36Z

One concern about the entities/user example:

In real-world products, “User” is often a very broad umbrella concept, so readers might interpret this page as “put all user-related business logic into entities/user/api and entities/user/model.” Over time, this can turn entities/user into a dumping ground where more and more code accumulates, which may hurt maintainability.

With that in mind, I wanted to ask (carefully) whether there might be a better example than User, Customer, Order, Product etc.. for this section — or perhaps a better way to phrase it to avoid that interpretation.

Also, in larger domains, it’s common to either:

(a) modularize within the same slice by responsibility (e.g., splitting read/write operations and separating model concerns), for example:

entities/user/
  api/
    queries/      # read operations
    mutations/    # write operations
  model/
    permissions/
    ...

(b) or split by domain context into more specific entities or slice groups. For example:

entities/user/
  guide/
  profile/

It might be helpful to mention these evolution paths so readers don’t assume a single giant entities/user is always the intended direction.

Looking at the current example code, it seems like most of it follows a structure like this:

shared/
  api/
    client.ts         # infrastructure only
    types.ts

entities/
  user/
    api/
      user-api.ts     # API + mapping (~100 lines)
    model/
      types.ts
      use-user-permissions.ts  # business logic (~150 lines)
    index.ts

So I brought this up after thinking about it in that context.

dyakubovskiy · 2026-02-23T10:50:19Z

Taken into account and implemented in the new version. The file has been fully rewritten and moved from the reference section to guides — examples are now in React+TS and plain TypeScript without framework reactivity, repetitions are removed, the Approach A section is condensed with a link to the existing api-requests page, and architectural issues are fixed (entity type moved from api/ to model/, files renamed to reflect their contents).

Solant

I think the flow is a bit fragmented: some paragraphs have no text except the small code samples, and lists consisting of minimal synopses might not be enough for the reader to understand the idea behind the reasoning. So I suggest adding some reasoning/explanation

Solant · 2026-02-27T18:30:15Z

i18n/en/docusaurus-plugin-content-docs/current/guides/examples/entity-layer.md

+export interface UserProfile {
+  id: string
+  name: string
+  email: string
+  joinedDaysAgo: number
+}
+
+function mapProfile(dto: UserProfileDTO): UserProfile {
+  return {
+    id: String(dto.user_id),
+    name: dto.full_name,
+    email: dto.email,
+    joinedDaysAgo: dto.joined_days_ago,
+  }
+}


Why do we need the UserProfile type as a 1:1 mapping of the existing DTO? I think it can introduce unnecessary friction if some changes are required: instead of changing one UserProfileDTO, we have to change UserProfile and mapper every time the response changes.

Solant · 2026-02-27T18:35:41Z

i18n/en/docusaurus-plugin-content-docs/current/guides/examples/entity-layer.md

+- Unknown what other fields will be needed elsewhere
+- YAGNI — don't create structure "for the future"
+
+### Triggers for Moving to Approach A or B


nit: maybe it is better to clarify what approaches A and B are, because the reader might forget what options A and B were, for example

"Triggers to move code to shared/api or entities"

Solant · 2026-02-27T18:38:05Z

i18n/en/docusaurus-plugin-content-docs/current/guides/examples/entity-layer.md

+- Teams starting to work with FSD
+- Small projects (fewer than ~10 screens)
+- Projects with frequently changing business logic
+- When it's unclear which entities have stabilized


It is also a practical approach when generators like orval or openapi are used

Solant · 2026-02-27T18:49:03Z

i18n/en/docusaurus-plugin-content-docs/current/guides/examples/entity-layer.md

+
+// Approach A: ~15 files need updates
+// Approach B: 1 file (the mapper in entities/user/api/)
+```


I don't think this is a good way of using mappers. In this particular example (when the field is renamed), the change is indeed localized, but usually backend changes are different (like field addition/removal), and mappers cannot prevent cascade changes when some data is missing or a new field is added

Stanislavsky69 · 2026-02-28T11:17:20Z